An application can redraw a picture stored in a metafile by executing the contents of metafile. This is known as playing a metafile into a graphics presentation space. How a picture is redrawn (that is, how the metafile is replayed) depends on the current drawing-mode of the target presentation space. The following table describes these dependencies.
Drawing Mode Dependencies When Playing Metafiles
┌──────────────────┬─────────────────────┬─────────────────────┐ │Drawing Mode │Result │If the metafile │ │ │ │contains a segment │ │ │ │chain... │ ├──────────────────┼─────────────────────┼─────────────────────┤ │DM_DRAW │The metafile contents│The contents of the │ │ │are executed, and the│segments in the chain│ │ │picture is directed │represent the picture│ │ │to the current output│output that is │ │ │device. │directed at the │ │ │ │target output device.│ ├──────────────────┼─────────────────────┼─────────────────────┤ │DM_RETAIN │The metafile contents│The chain is added to│ │ │are retained in the │the end of any chain │ │ │application's segment│that may already be │ │ │store. The picture │in the segment store.│ │ │defined in the │If any segment in the│ │ │metafile is not │metafile has the same│ │ │directed to an output│nonzero name as a │ │ │device until the │segment already in │ │ │application issues an│the segment store of │ │ │appropriate │the presentation │ │ │GpiDraw... function. │space, an error │ │ │ │condition is raised. │ ├──────────────────┼─────────────────────┼─────────────────────┤ │DM_DRAWANDRETAIN │The metafile contents│See above. │ │ │are both stored and │ │ │ │executed. │ │ └──────────────────┴─────────────────────┴─────────────────────┘
Note: Unchained segments in the metafile are always retained, regardless of the current drawing-mode parameter.
When the contents of a metafile are retained in the segment store of the target presentation space, they can be manipulated by the application as if the application had created them. For example, the segments can be edited, drawn, correlated, and deleted.
A metafile is "played" by calling GpiPlayMetaFile. A metafile cannot, however, be "played" within a segment bracket. GpiPlayMetaFile requires a metafile handle, an option count, an options array, a byte count of a descriptive record, and the descriptive record.
The GpiPlayMetaFile descriptive record is a natural-language description of the picture contents. For example, its value might be A House. This description is provided on input to the DevOpenDC function that defines the metafile device context. It can be used, for example, in a list box from which a user can select a picture.
The GpiPlayMetaFile options array specifies how the operating system alters your application's presentation space before playing the metafile. The options array determines the display attributes of the metafile. The array fields and their respective attributes, as numbered consecutively in the array, are shown in the following table.
┌──────────────────────────────┬──────────────────────────────┐ │Option │Attribute │ ├──────────────────────────────┼──────────────────────────────┤ │PMF_SEGBASE │Reserved, must be 0. │ ├──────────────────────────────┼──────────────────────────────┤ │PMF_LOADTYPE │Viewing transform, graphics. │ ├──────────────────────────────┼──────────────────────────────┤ │PMF_RESOLVE │Reserved, must be 0. │ ├──────────────────────────────┼──────────────────────────────┤ │PMF_LCIDS │Font and local bit map local │ │ │identifiers. │ ├──────────────────────────────┼──────────────────────────────┤ │PMF_RESET │Drawing attributes. │ ├──────────────────────────────┼──────────────────────────────┤ │PMF_SUPPRESS │Actual playing of the │ │ │metafile. │ ├──────────────────────────────┼──────────────────────────────┤ │PMF_COLORTABLES │Color tables, color palettes. │ ├──────────────────────────────┼──────────────────────────────┤ │PMF_COLORREALIZABLE │Realization of metafile color │ │ │table. │ ├──────────────────────────────┼──────────────────────────────┤ │PMF_DEFAULTS │Drawing defaults values. │ └──────────────────────────────┴──────────────────────────────┘