with-external-metafile

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

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