2.15.1 Creating a Metafile

A Windows application must create a metafile in a special device context. It cannot use the device contexts that the CreateDC or GetDC function returns; instead, it must use the device context that the CreateMetaFile function returns.

Windows allows an application to use a subset of the GDI functions to create a metafile. This subset consists of all GDI functions that create output (rather than functions that provide state information, such as the GetDeviceCaps function). The following list shows GDI functions that an application can use in a metafile:

AnimatePalette Arc BitBlt Chord CreateBrushIndirect CreateDIBPatternBrush CreateFontIndirect CreatePatternBrush Ellipse Escape ExcludeClipRect ExtTextOut FloodFill IntersectClipRect LineTo MoveTo OffsetClipRgn OffsetViewportOrg OffsetWindowOrg PatBlt Pie Polygon Polyline PolyPolygon RealizePalette RestoreDC RoundRect SaveDC ScaleViewportExt ScaleWindowExt SelectClipRgn SelectObject SelectPalette SetBkColor SetBkMode SetDIBitsToDevice SetMapMode SetMapperFlags SetPixel SetPolyFillMode SetROP2 SetStretchBltMode SetTextColor SetTextJustification SetViewportExt SetViewportOrg SetWindowExt SetWindowOrg StretchBlt StretchDIBits TextOut

To create output in a metafile, an application must follow four steps:

1.Create a special device context by using the CreateMetaFile function.

2.Send GDI commands to the metafile by using the special device context.

3.Close the metafile by calling the CloseMetaFile function. This function returns a metafile handle.

4.Display the image or text on a device by using the PlayMetaFile function and passing to the function the metafile handle obtained from CloseMetaFile and a device-context handle for the device on which the metafile is to be played.

The device context that the CreateMetaFile function creates does not have default attributes of its own. Whatever device-context attributes are in effect for the output device when an application plays a metafile will be the defaults for the metafile. The metafile can change these attributes while it is playing. If the application needs to retain the same device-context attributes after the metafile has finished playing, it should save the output device context by calling the SaveDC function before calling the PlayMetaFile function. Then, when PlayMetaFile returns, the application can call the RestoreDC function to restore the original device-context attributes.

Although the maximum size of a metafile is 232 bytes or records, the actual size of a metafile is limited by the amount of memory or disk space available. For information about the format of metafile records and descriptions of their contents, see the Microsoft Windows Programmer's Reference, Volume 4.