Macro

Summary

Creates a metafile on disk using Graphics Ports operations.

Package

capi

Signature

with-external-metafile ( var &key pane bounds format pathname owner 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.

owner

Specifies the owner of the metafile, which calls to port-owner will return. This has an effect only when pane is nil.

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 an object of type metafile-port. 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.

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 The drawing mode and anti-aliasing.

On Cocoa and GTK+ the metafile format is always PDF as a single page, and the format argument is ignored. format is used only on Microsoft Windows and 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.

Notes

1. 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.
2. with-external-metafile is not implemented on X11/Motif.

See also

draw-metafile
metafile-port
port-owner
with-internal-metafile
Drawing - Graphics Ports