All Manuals > CAPI User Guide and Reference Manual > 21 CAPI Reference Entries

with-external-metafile 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
A graphics port, or 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.

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

On Cocoa and GTK+ the metafile format is always PDF as a single page, and format 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
13 Drawing - Graphics Ports


CAPI User Guide and Reference Manual (Macintosh version) - 01 Dec 2021 19:31:27