Macro

Summary

Creates a metafile on disk using Graphics Ports operations.

Package

capi

Signature

with-external-metafile ( var &key pane bounds format pathname drawing-mode ) &body body => nil

Arguments

var

A variable.

pane

A graphics port, or nil .

bounds

A list of four integers. Can also be nil on Microsoft Windows.

format

One of the keywords :enhanced , :enhanced-plus , :enhanced-gdi and :windows .

pathname

A pathname or string.

drawing-mode

One of the keywords :compatible and :quality .

body

Code containing Graphic Ports operations that draw to var .

Description

The macro with-external-metafile creates a metafile at the location given by pathname containing records corresponding to the Graphics Ports operations in body that draw to var .

On Microsoft Windows the metafile is a device-independent format for storing pictures. For more information about metafiles, see the Microsoft documentation.

On Cocoa and GTK+ the metafile format is PDF.

If pane is nil , the macro binds var to a graphics port object representing the metafile. If pane is non-nil then it must be an instance of output-pane or a subclass. In this case var is bound to pane , and pane is modified within the dynamic extent of with-external-metafile so all drawing operations draw to the metafile instead of pane . This can be useful when reusing existing redisplay code that is written expecting an output-pane. The default value of pane is nil .

If bounds is nil the metafile size will be computed from the drawing done within the body. This value is not allowed on Cocoa.

If bounds is non-nil (required on Cocoa), it should be a list of integers specifying the coordinate rectangle ( x y width height ) that the metafile contains.

format is used only on Microsoft Windows. It can be one of:

:enhanced

Generate an Enhanced-metafile file containing "dual drawing" both in GDI+ and GDI.

:enhanced-plus

Generate an Enhanced-metafile file containing drawing only in GDI+.

:enhanced-gdi

Generate an Enhanced-metafile file containing drawing only in GDI.

:windows

Generate a Windows-metafile.

The default value of format is :enhanced .

When drawing-mode is :compatible (rather than the default value :quality ) :enhanced and :enhanced-plus behave like :enhanced-gdi .

Note: GDI+ gives the best quality, so normally that is what you would want. However some programs may be able to display only GDI (and not GDI+), which is why the default is dual drawing. This however generates a larger file and is presumably slightly slower, so if you are sure that the file will be used only by programs that can draw GDI+ emf files (sometimes called EMF+), you can use format :enhanced-plus .

On Cocoa the metafile format is always PDF as a single page, and the format argument is ignored.

pathname specifies the filename of the metafile. If its pathname-type is nil , then the file extension "EMF" is used for an Enhanced-metafile, or "WMF" for a Windows-metafile.

drawing-mode should be either :compatible which causes drawing to be the same as in LispWorks 6.0, or :quality which causes all the drawing to be transformed properly, and allows control over anti-aliasing on Microsoft Windows and GTK+. The default value of drawing-mode is :quality .

For more information about drawing-mode , see "Drawing mode and anti-aliasing" in the CAPI User Guide .

Notes

with-external-metafile is not implemented on X11/Motif.

See also

draw-metafile
with-internal-metafile