GPIGuide - Metafiles: Difference between revisions
| Line 163: | Line 163: | ||
How these functions are used to create and manipulate metafiles in relationship to applications and components of the operating system is illustrated in the following figure. | How these functions are used to create and manipulate metafiles in relationship to applications and components of the operating system is illustrated in the following figure. | ||
[[Image:GPIMetafile_54.png|Metafile Functions]] | [[Image:GPIMetafile_54.png|Metafile Functions]] | ||
Revision as of 04:29, 14 May 2025
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
A metafile is a graphics object that, like a segment, contains the GPI instructions that contribute to the final version of a picture. Unlike a segment, a metafile also contains a header, with state information, and all resources necessary to identically create the picture. Because pictures that are displayed when a graphics application is executed are lost when the application finishes, metafiles provide a method of retaining pictures beyond a single execution of an application.
Related Topics
- Presentation spaces and device contexts
- Line primitives
- Marker primitives
- Area primitives
- Character string primitives
- Color and mix attributes
- Paths
- Regions
- Fonts
- Bit maps
- Coordinate spaces and transformations
- Print job submission and manipulation
About Metafiles
Metafiles can exist in three distinct forms. A metafile that has just been created is called a memory metafile because it exists in memory managed by the Presentation Manager on behalf of the application that created it. A metafile that is transferred to disk storage as a file with the default extension of .MET is called a disk metafile. A metafile that is loaded into an application's memory is editable by the application.
Metafiles save resources in the following ways:
- Metafiles can be created and used in draw mode by a single application. Therefore, an application that is not retaining segments in a segment store can retain graphics in a metafile.
- Metafiles remain available while the owning application is running, regardless of the number of presentation spaces the application obtains or defines.
- Given the same starting conditions in each presentation space, you can produce an identical picture each time the metafile contents are executed.
- Different threads or processes within an application can display a picture stored as a metafile without each having to own the metafile.
- If your organization has common graphical resources, such as a company logo, those resources can be stored in a metafile. This avoids the overhead of re-creating the resources each time they are needed.
- Because the metafile is a device-independent format, it is useful for transferring pictures that are to be printed when the printer-type is unknown.
- PM applications can exchange graphical information by using metafiles, either by using the clipboard or by transferring them over a network.
- Your application can also exchange graphics data with non-PM applications that support the Mixed Object Document Content Architecture (MO:DCA) interchange standard.
Unlike bit-maps, metafiles offer some device-independence. Bit maps store picture information on a pel-by-pel basis. Metafiles store picture information in the form of low-level graphics commands that the operating system uses to construct the pictures.
Remarks
Metafiles can contain bit maps or other graphics information that is in device-dependent format.
The graphics commands, called "graphics orders", represent graphics functions that create a picture. These include drawing instructions, as well as attribute-setting instructions (for example, color tables and logical fonts) and anything that describes the structure of the picture. The contents of a metafile, therefore, are similar to those of the graphics presentation space in which the picture is drawn. The Presentation Manager automatically records the environmental detail of the presentation space in which a picture is drawn in the metafile.
Remarks
A metafile can contain data generated from GPI functions only. Any non-graphical data included in a metafile is ignored.
An application can re-create a picture from a metafile and display it in a window on the screen or print it by "playing" the metafile. When an application displays the contents of a metafile, it can use the color table, font, fill pattern, and transformations that are stored in the metafile, or it can use the logical color table, logical font, fill pattern, and transformations that are set for the current presentation space. The appearance of the picture stored in the metafile can, therefore, be changed by editing the current presentation space before playing the metafile.
An application can save metafiles to a disk to be loaded later by any application that chooses to access the metafile. Disk metafiles loaded into application memory can also be edited in the same manner as elements in graphics segments are edited.
They contain both primitives and attributes.
Contents of a Metafile
Every graphic function can be represented by one or more graphics orders. The operating system defines graphics orders for:
- Areas
- Bit maps (for fill patterns) and pattern-reference points
- Character output and attribute
- Colors and mix modes (foreground and background)
- Lines and arcs and line and arc attributes (including GpiBox)
- Paths (including clip paths)
- Position (for example, GpiMove)
- Saving and resetting attributes (including GpiPop)
- Transformations (in model space)
- Viewing Limits
Editing Retained Graphics and Graphics Segments also describes orders and how to edit them.
When a picture is drawn in a presentation space associated with a metafile device context, the operating system converts the primitive attributes and drawing functions into graphics orders and stores them in the metafile.
The operating system stores the effects of region and other operations that are not permitted as escape orders in the metafile. When an application finishes playing a metafile, the system restores any regions that were defined for the presentation space prior to calling GpiPlayMetaFile.
An application can use any of the query functions while creating a metafile, but the system will not store those query functions in the metafile. Similarly, an application can set a value by using a mathematical operator, but the system will store only the result of the operation in the metafile. For example, if an application determines the end point of a line by subtracting 100 from the x- and y-coordinates of the upper-right corner of a window, the system records the end point, not the relative distance, in the metafile.
Because the output of bit map functions is dependent upon the capabilities of the output device, Gpi bit map functions might produce unexpected results when they are used in a metafile. If the pel dimensions of the output device are different from the pel dimensions of the device on which the metafile was created, the bit map will be distorted. If the output device is a plotter, the bit map functions will not work at all.
Most of the escape functions used by the DevEscape function can be used in metafiles. The escape functions that the system does not save in metafiles are DEVESC_QUERYESCSUPPORT and DEVESC_GETSCALINGFACTOR.
Metafile Content Restrictions
Like areas and paths, not all functions and attributes can be represented in a metafile. Metafile content is mainly dependent upon the drawing mode in which the metafile is to be played. If the metafile is to be played when the current drawing-mode parameter is DM_DRAW (and in no other drawing mode), the metafile content is restricted as shown in Draw-Mode Restrictions. If the metafile is to be played when the current drawing-mode parameter is DM_RETAIN or DM_DRAWANDRETAIN, or if the file is to conform to SAA* guidelines, the metafile content is restricted as shown in Creating Metafiles for Interchange.
Draw-Mode Restrictions
The following restrictions apply if the metafile is to be played when the current drawing mode parameter is DM_DRAW:
- If the DCTL_DISPLAY flag of GpiSetDrawControl is OFF when you are sending graphics to a metafile, the graphics will not be visible when the metafile is played. Their effects on the current position and on current attribute settings are recorded.
- Region functions are not recorded in a metafile. The effects of the following functions, however, are recorded:
When the metafile is played into a presentation space, temporary regions are created. Upon completion of GpiPlayMetaFile, these temporary regions are automatically deleted, and the clipping region that was current before the metafile was played is restored.
- In general, escape functions identified by reserved escape codes (that is, escape codes in the range of 0 through 32767) are recorded in a metafile. However, the DevEscape functions DEVESC_QUERYESCSUPPORT (escape code 0) and DEVESC_GETSCALINGFACTOR (escape code 1) are not stored in the metafile.
- The effect of GpiErase, including close-segment processing, is recorded in a metafile.
- The following functions can produce unexpected effects if the metafile contents are displayed on a different device from the one they were created for:
The reason for the unexpected effects is because the pel resolutions of the devices might differ. Raster operations (for example, GpiBitBlt) do not work on plotters.
- You can associate the metafile device context with a different presentation space while creating the metafile, but the new presentation space must have the same format as the original.
Creating Metafiles for Interchange
The following restrictions apply if the metafile is to be played when the current drawing-mode parameter is DM_DRAWANDRETAIN or DM_RETAIN, or if the metafile is to conform to SAA guidelines:
- Before you issue the first drawing instruction to a graphics presentation space that has been associated with a metafile device context, you must establish (or default) the following:
- The graphics field (use GpiSetGraphicsField)
- The color table (use GpiCreateLogColorTable)
- The code page for the default character set (use GpiSetCp)
- The default viewing transformation (use GpiSetDefaultViewMatrix)
- The settings of the drawing controls (use GpiSetDrawControl; DCTL_DISPLAY must be set on)
- The default values of attributes (use GpiSetDefAttrs)
- The default viewing limits (use GpiSetDefViewingLimits)
- The primitive tag (use GpiSetDefTag)
- The default arc parameters (use GpiSetDefArcParams)
You must not specify a graphics field if the metafile is to conform to SAA guidelines. If a graphics field is specified, you can play the metafile in DM_RETAIN or DM_DRAWANDRETAIN mode, but the graphics field must be specified before the first drawing instruction is issued to the metafile. The effect of the graphics field in the target presentation space when playing the metafile is controlled by the PMF_LOADTYPE option of GpiPlayMetaFile.
- You can define logical fonts and identify bit maps to be used as area-fill patterns at any time. You must not, however, issue GpiDeleteSetId against these resources after they have been established. Once assigned, therefore, lcids cannot be reused.
- The size of the logical-color-table data must not exceed 31KB.
- You must not use clipping regions. Therefore, none of the following functions are supported:
- You must not reassociate the metafile device context.
- When you use a bit map as the source of a GpiWCBitBlt operation or as an area-fill pattern, it must not be modified.
- Only the following foreground mixes can be used:
- FM_DEFAULT
- FM_OR
- FM_OVERPAINT
- FM_LEAVEALONE
- Only the following background mixes can be used:
- BM_DEFAULT
- BM_OVERPAINT
- BM_LEAVEALONE
- The following functions are not supported:
- GpiBitBlt
- GpiSetPel
- GpiSetPS
- GpiResetPS
- GpiErase
- GpiPaintRegion
- DevEscape
Micro Presentation Space Restrictions
When you create a metafile from a micro presentation space, or play the metafile through a micro presentation space, the contents of the metafile are restricted to those GPI functions that are valid in a micro presentation space. In this case, the application must use GpiDestroyPS instead of GpiAssociate before issuing DevCloseDC. GpiAssociate is not permitted in a micro presentation space.
Query Restrictions
Query functions can be issued, with the usual restrictions, unless the metafile device context was created using the no query option, OD_METAFILE_NOQUERY.
Segment Restrictions
Chained and unchained segments invoked by any GpiDraw... command are written to the metafile. Primitives outside segments are recorded automatically as zero segments. If the metafile is subsequently played in DM_RETAIN mode, all graphics are directed to the segment store.
Chained dynamic segments cannot be recorded in a metafile. GpiRemoveDynamics and GpiDrawDynamics cause an error condition to be raised when the presentation space is associated with a metafile device context. Unchained dynamic segments are recorded as zero segments. To draw an unchained dynamic segment, use GpiDrawSegment.
Asynchronous Drawing Thread Restrictions
If the metafile is being created on an asynchronous drawing thread and the thread is suspended by GpiSetStopDraw, an unusable metafile results.
Metafile Functions
The OS/2 operating system provides a set of functions that allow you to:
- Create a metafile
- Store pictures in a metafile
- Play a metafile
- Save a metafile
- Load a metafile
- Edit a metafile
- Copy a metafile
- Delete a metafile
How these functions are used to create and manipulate metafiles in relationship to applications and components of the operating system is illustrated in the following figure.
Creating a Metafile
Pictures are drawn in presentation spaces associated with device contexts. PM considers a metafile to be an output device or destination, in the same manner as a window or printer. This means that to record a picture in a metafile, a metafile device context must be created and associated with a presentation space.
A metafile device context is created by calling DevOpenDC and specifying the type of device context as:
- OD_METAFILE
- OD_METAFILE_NOQUERY
OD_METAFILE is generally used to specify a metafile device context, although OD_METAFILE_NOQUERY provides better recording performance. OD_METAFILE_NOQUERY does not support attribute queries, for example, GpiQueryCurrentPosition, or GpiQueryColor.
The device driver for the device that the metafile device context is associated with is specified in the DEVOPENSTRUC data structure required for DevOpenDC. DEVOPENSTRUC is described in Print Job Submission and Manipulation.
A metafile device context can be associated with a newly-created presentation space by calling GpiCreatePS and specifying the handle to the metafile device context returned from the call to DevOpenDC. A metafile device context can also be associated with an existing, normal presentation space by calling GpiAssociate and specifying the handle to the metafile device context returned from the call to DevOpenDC.
Storing Pictures in a Metafile
When a metafile device context is associated with a presentation space, presentation space resources (such as the current logical color table) and environmental settings (such as the presentation-page format) are copied automatically into the metafile. These items must be established before the presentation space is associated with the metafile device context.
Loading of additional resources (such as fonts) and adjustments to the environment (such as modifying the default viewing transform) should be made before you begin drawing. Attribute settings, segment-creation requests, and primitive-drawing requests that contribute to the picture are directed to the metafile after its device context has been associated with a presentation space.
If an application calls GpiSetDrawControl, specifying DCTL_DISPLAY and DCTL_OFF, before drawing graphics into a metafile, the graphics are not visible when the metafile is played. However, the metafile records any changes made to the current position or presentation-space attributes.
When the metafile device context has been associated with a graphics presentation space, the metafile is ready to receive graphical data. Just as with any other output destination, whether the picture is sent directly to the metafile is controlled by the current drawing mode, as shown in the following table.
Drawing Mode Dependencies When Recording Metafiles
| Drawing Mode | Effect |
|---|---|
| Draw mode | Graphics go directly to the metafile. |
| Retain mode | Graphics go to the segment store of the presentation space. They are not directed to the metafile until the application issues an appropriate GpiDraw... request (GpiDrawChain, GpiDrawFrom, GpiDrawSegment). |
| Draw-and-retain mode | Graphics go directly to the metafile, and also to the segment store of the presentation space. |
The drawing mode can be changed at any time while the metafile device context remains open by calling GpiSetDrawingMode.
As long as the metafile device context remains open, you can continue drawing. A metafile can only contain data generated from GPI functions. Any nongraphical data included in a metafile is ignored. The following list describes items found in a metafile:
- Picture
- Logical color table
- Logical font
- Fill pattern
- Viewing transformation
- Page units
- Page dimensions
When an application finishes drawing in a metafile, it must disassociate the metafile device context from the presentation space by calling GpiAssociate. If the metafile is associated with or through a micro presentation space, call GpiDestroyPS to perform an implicit disassociation.
When you have finished drawing in the metafile, and the presentation space has been disassociated, the application can close the metafile device context and obtain a handle to the metafile by calling DevCloseDC. A closed metafile cannot be reopened; therefore, additional drawing in the metafile is not possible. A closed metafile can be referenced by the metafile handle. The metafile handle is used to reference the metafile for subsequent operations on the metafile. Use the metafile handle to:
- Transfer a metafile to application memory
- Transfer a metafile from application memory
- Save a metafile on disk
- Play a metafile into presentation space
- Edit a metafile
- Copy a metafile
- Delete a metafile
Because each metafile can be distinctly identified, your application can work with more than one metafile at a time. However, because metafiles can be very large files, you must make maximum use of the metafile handles to avoid duplicating the actual metafiles in memory.
Playing a Metafile
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 are executed, and the picture is directed to the current output device. | The contents of the segments in the chain represent the picture output that is directed at the target output device. |
| DM_RETAIN | The metafile contents are retained in the application's segment store. The picture defined in the metafile is not directed to an output device until the application issues an appropriate GpiDraw... function. | The chain is added to the end of any chain that may already be in the segment store. If any segment in the metafile has the same nonzero name as a segment already in the segment store of the presentation space, an error condition is raised. |
| DM_DRAWANDRETAIN | The metafile contents are both stored and executed. | See above. |
Remarks
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.
GpiPlayMetaFile Options
| 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. |
PMF_RESET Option
The PMF_RESET option, more so than the other array options, controls the effects of other array options. This option allows a total reset of the presentation space and provides further control of the following presentation space environmental attributes:
- Page units (device transform)
- Page dimensions
- Default viewing transform
Remarks
Warning: If the metafile page units, page dimensions and page coordinate format do not match those in the presentation space, playing the metafile will cause an error.
The PMF_RESET option can have one of the values shown in the following table.
PMF_RESET Options for GpiPlayMetaFile
| Value | Description |
|---|---|
| RES_RESET | Allows the presentation space to be completely reset, just as if it were newly created, and the values of the aforementioned environmental attributes to be specified from the metafile into the presentation space. This option is equivalent to specifying GRES_ALL on GpiResetPS. If this option is used, the target presentation page is redefined so that it is the same size, and defined in the same units, as the metafile. It also ensures that the physical size of the metafile picture is preserved if the presentation page is defined in units other than pels, or arbitrary units. |
| RES_NORESET RES_DEFAULT |
Prevents resetting of the presentation space. The existing presentation space values of the environmental attributes will be preserved, and their values in the metafile will be discarded. If this option is used, ensure that the presentation-page units of the target presentation space are the same as those with which the metafile was generated, before you play a metafile into the presentation space. For example, if the original presentation page is defined in increments of 0.1 mm, the target presentation page must be defined in the same way. To change the format of the target presentation page, if the presentation-page formats do not match, issue GpiSetPS, but only if you know the metafile presentation-page units. |
If you are certain that the settings of the current presentation space are appropriate for the metafile, then you can play the metafile with the NO_RESET option. To reset some or all of the current values in the target presentation space, without redefining the presentation page, call:
- GpiResetPS, with the GRES_ATTRS or GRES_SEGMENTS option
- GpiPlayMetaFile, with the NO_RESET option
The PMF_LCID option may be used to append or replace fonts from the metafile to the fonts in the presentation space. The PMF_COLORTABLES option may be used to append or replace color table entries in the presentation space from the metafile. Other options (PMF_LOADTYPE, PMF_DEFAULTS, and so on) can be used to selectively replace settings in the presentation space from the metafile.
Like the PMF_RESET option, other options, except for PMF_SUPPRESS, either:
- Allow the values in the presentation space to be preserved and those in the metafile to be discarded, or
- Allow the presentation space to be loaded using the values in the metafile.
If the first choice is used with RES_RESET, then the items controlled by the PMF_options will be left set to their default reset state, otherwise it will occur as described in the first choice above.
If the second choice is used with RES_RESET, then the items controlled by the PMF_options are as described above. If it is used with RES_NORESET, then the fonts and color tables in the metafile can append to the existing color tables and fonts in the presentation space. Existing presentation space color table entries and fonts, such as viewing transform will be replaced if respecified in the metafile.
Remarks
If your application uses the attributes from the metafile, the attributes that were specified in the presentation space before the metafile was played are overwritten.
PMF_SUPPRESS Option
The PMF_SUPPRESS option allows you to control the playing of the metafile. The PMF_SUPPRESS option can have one of the values shown in the following table.
PMF_SUPPRESS Options for GpiPlayMetaFile
| Value | Description |
|---|---|
| SUP_SUPPRESS | The operating system does not draw the metafile on the device associated with the presentation space. This option is useful if you need to alter the presentation space before drawing it on an output device. |
| SUP_NOSUPPRESS SUP_DEFAULT |
The operating system draws the metafile on the device associated with the presentation space. |
You can use the RES_RESET option to reinitialize the presentation space and modify certain resources or presentation space environmental attributes from the application before playing the remainder of the metafile by:
- Saving the current state of the presentation space by calling GpiSavePS. Use this function only if you wish to restore the previous state of the presentation space after playing the metafile.
- Calling GpiPlayMetaFile and specifying:
- The PMF_RESET option with the value RES_RESET
- The PMF_SUPPRESS option with the value SUP_SUPPRESS
This causes GpiPlayMetaFile to set the presentation space to the specifications recorded in the metafile but not to play the picture in the metafile.
- Making any required changes to the presentation space.
- Calling GpiPlayMetaFile and specifying:
- The PMF_RESET option with the value RES_NORESET
- The PMF_SUPPRESS option with the value SUP_NOSUPPRESS
This causes the picture to play.
- Restoring the state of the presentation space after playing the metafile by calling GpiRestorePS.
PMF_LOADTYPE Option
The PMF_LOADTYPE option of GpiPlayMetaFile determines which viewing transformations and graphics fields affect the metafile picture. The PMF_LOADTYPE option can have one of the values shown in the following table.
PMF_LOADTYPE Options for GpiPlayMetaFile
| Value | Description |
|---|---|
| LT_ORIGINALVIEW | Viewing transformations recorded in the metafile are used in the target presentation space. If changes to the graphics field are recorded in the metafile, the graphics field in the target presentation space is updated, and the picture is clipped to that graphics field. Changes to the default viewing transformation recorded in the metafile are used to update the default viewing transformation in the target presentation space. |
| LT_NOMODIFY LT_DEFAULT |
Any viewing transformations recorded in the metafile are ignored. The metafile contents are drawn in accordance with the current viewing transformation in the target presentation space. (Note that, if you also specify RES_RESET, the current viewing transformation is reset to its default value.) The picture is clipped to any graphics field defined in the target presentation space, and any graphics field recorded in the metafile is ignored. |
The PMF_RESET option RES_RESET changes values in the target presentation space. Therefore, the effect of the PMF_LOADTYPE option should always be considered in conjunction with the PMF_RESET option. For example, if you specify both RES_RESET and LT_NOMODIFY, the default viewing transformation in the target presentation space is updated with that from the metafile, even though LT_NOMODIFY means that such values should be ignored.
PMF_LCIDS Option
The PMF_LCIDS option of GpiPlayMetaFile controls whether logical resources referenced by a local identifier (lcid) are loaded from the metafile. Logical resources include logical fonts and bit maps used as area-fill patterns. The PMF_LCIDS option can have one of the values shown in the following table.
PMF_LCIDS Options for GpiPlayMetaFile
| Value | Description |
|---|---|
| LC_LOADDISC | Loads lcid-referenced resources from the metafile. If the lcids of those resources are already in use in the target presentation space, the resources currently identified by those lcids are deleted and their lcids are freed before the metafile contents are loaded. The new fonts and bit maps replace the existing ones in the presentation space. (If the operating system uses a local identifier that the application has already defined, GpiPlayMetaFile deletes the existing identifier before using it for the metafile resource.) |
| LC_NOLOAD LC_DEFAULTS |
The operating system uses the presentation space's logical font and custom fill pattern; it will ignore any logical font or custom fill pattern in the metafile. An application can use GpiSavePS and GpiRestorePS to maintain the local identifiers it has already defined. |
PMF_COLORTABLE Option
The PMF_COLORTABLES option may be used to append or replace color table entries in the presentation space from the metafile. The PMF_COLORTABLES option can have one of the values shown in the following table.
PMF_COLORTABLES Options for GpiPlayMetaFile
| Value | Description |
|---|---|
| CTAB_REPLACE | Replaces the logical color table in the presentation space with the color table in the metafile. |
| CTAB_REPLACEPALETTE | Replaces the current palette, if it exists, in the presentation space with the palette in the metafile. |
| CTAB_NOMODIFY CTAB_DEFAULT |
Maintains the logical color table in the presentation space. |
PMF_COLORREALIZABLE Option
The PMF_COLORREALIZABLE option may be used to select whether color table from the metafile is realized upon loading. The PMF_COLORREALIZABLE option can have one of the values shown in the following table.
PMF_COLORREALIZABLE Options for GpiPlayMetaFile
| Value | Description |
|---|---|
| CREA_DOREALIZE | Sets the realizable option when loading the color table. |
| CREA_NOREALIZE CREA_DEFAULT |
Does not set the realizable option when loading the color table. |
PMF_DEFAULTS Option
The PMF_DEFAULTS option can have one of the values shown in the following table.
PMF_DEFAULTS Options for GpiPlayMetaFile
| Value | Description |
|---|---|
| DDEF_LOADDISC | Replaces the default attributes, default viewing limits, and default arc parameters in the presentation space with the values specified in the metafile. |
| DDEF_IGNORE DDEF_DEFAULTS |
Maintains the default attributes, default viewing limits, and default arc parameters in the presentation space. |
Saving a Metafile
A metafile is not a permanent object and, unless it is explicitly saved, disappears when the application that creates it ends. Metafiles are saved in disk files by calling GpiSaveMetaFile.
This function accepts as input the metafile handle and the name of the disk file in which the metafile is to be saved. As the disk file is created by this function, an error condition is raised if a file with this name already exists. When you call GpiSaveMetaFile, the memory version of the metafile is deleted. Its handle is no longer valid, until the file is reloaded from disk.
Loading a Metafile
A metafile saved on disk has to be reloaded before it can be used. Any application with access to the disk file can transfer the file from disk storage to application storage by calling GpiLoadMetaFile. GpiLoadMetaFile returns a metafile handle, which identifies the metafile after it has been loaded.
Editing a Metafile
Metafiles can be edited in a manner similar to editing graphics segments. To edit graphics orders in a metafile, an application transfers them into application storage (an array of bytes) by calling GpiQueryMetaFileBits. The number of graphics orders copied depends on the size of the array that the application supplies. The application can determine the size of the metafile (in bytes) by calling GpiQueryMetaFileLength. When the application has finished editing the graphics orders, it can copy them back into the metafile by calling GpiSetMetaFileBits.
Edited versions of metafiles can be saved by calling GpiSaveMetaFile. The disk file that contains the edited version of the metafile cannot have the same name as the file from which the metafile was originally loaded. GpiSaveMetaFile raises an error condition if the disk file already exists.
Copying a Metafile
A copy of a memory metafile can be made by calling GpiCopyMetaFile. PM makes a copy of the metafile and returns a new handle to the new metafile.
Deleting a Metafile
A memory metafile is deleted by calling GpiDeleteMetaFile. After the operation is complete, the handle to the metafile no longer points to a usable object. A disk file containing the metafile remains untouched by this operation. A disk metafile is deleted by using operating system commands that delete any other type of file.
Metafiles and the System Clipboard
A metafile that you have created or loaded can be made available to other applications at the same workstation by placing the handle to the metafile in the system clipboard. When a resource is passed to the clipboard, it becomes the property of the system, and is not deleted when the owning application ends. Any application that can access the clipboard can retrieve the handle to the metafile. Using the handle to the metafile, the application should copy the metafile by calling GpiCopyMetaFile before closing the clipboard. The application can then perform any metafile operation on the metafile.
Using Metafiles
Use metafile functions to:
- Create a metafile
- Draw into a metafile
- Load a metafile to disk
- Load a metafile from disk into an application
- Play a metafile
- Edit a metafile
- Copy a metafile
- Transfer metafile contents to application memory
- Transfer metafile contents from application memory
Creating and Drawing into a Metafile
To create a metafile, you must:
- Create a metafile device context with DevOpenDC.
- Create a presentation space with GpiCreatePS, and associate the presentation space with the metafile device context.
- Draw into the metafile with various Gpi drawing functions.
- Disassociate the metafile device context from the presentation space with GpiAssociate.
- Close the metafile device context with DevCloseDC.
The following example shows how to create a simple metafile that draws text within the borders of a three-color box.
#include <os2.h>
void fncMETA01(void){
DEVOPENSTRUC dop;
HDC hdcMeta;
HPS hpsMeta;
HMF hmf;
HAB hab;
SIZEL sizlPage;
POINTL ptl;
dop.pszLogAddress = (PSZ) NULL;
dop.pszDriverName = "DISPLAY";
hdcMeta = DevOpenDC(hab,
OD_METAFILE, /* Metafile device context */
"*", /* Ignores OS2.INI */
2L, /* Uses first two fields */
(PDEVOPENDATA) &dop, /* Device information */
(HDC) NULLHANDLE); /* Compatible device context */
hpsMeta = GpiCreatePS(hab,
hdcMeta, /* Metafile device context */
&sizlPage, /* Page viewport */
PU_PELS | GPIA_ASSOC); /* Device units and associated context */
/* Draw a box in a metafile. */
GpiSetColor(hpsMeta, CLR_CYAN);
ptl.x = 150; ptl.y = 200;
GpiMove(hpsMeta, &ptl);
ptl.x = 300; ptl.y = 275;
GpiBox(hpsMeta, DRO_FILL, &ptl, 0L, 0L);
GpiSetColor(hpsMeta, CLR_GREEN);
ptl.x = 300; ptl.y = 200;
GpiMove(hpsMeta, &ptl);
ptl.x = 390; ptl.y = 275;
GpiBox(hpsMeta, DRO_FILL, &ptl, 0L, 0L);
GpiSetColor(hpsMeta, CLR_YELLOW);
ptl.x = 390; ptl.y = 200;
GpiMove(hpsMeta, &ptl);
ptl.x = 530; ptl.y = 275;
GpiBox(hpsMeta, DRO_FILL, &ptl, 0L, 0L);
ptl.x = 175; ptl.y = 230;
GpiMove(hpsMeta, &ptl);
GpiSetColor(hpsMeta, CLR_PINK);
GpiCharString(hpsMeta, 41,
"METAFILE COPY METAFILE COPY METAFILE COPY");
GpiAssociate(hpsMeta, (HDC) NULLHANDLE);
hmf = DevCloseDC(hdcMeta);
} /* fncMETA01 */
Drawing into a Metafile in Retain Mode
To draw into a metafile, set the drawing mode to the appropriate value for your application and then perform the drawing operations. The following example shows how to copy the contents of a segment into a metafile.
#define INCL_GPIMETAFILES
#define INCL_GPICONTROL
#include <os2.h>
void fncMETA02(void){
HDC hdcMeta, hdc;
POINTL ptl;
HMF hmf;
LONG alOpt[10];
HPS hps;
/*
* Open a segment, assign it an identifier of 10,
* and draw some text into it.
*/
GpiSetDrawingMode(hps, DM_RETAIN);
GpiOpenSegment(hps, 10L);
ptl.x = 175; ptl.y = 230;
GpiMove(hps, &ptl);
GpiSetColor(hps, CLR_PINK);
GpiCharString(hps, 41,
"METAFILE COPY METAFILE COPY METAFILE COPY");
GpiCloseSegment(hps);
GpiAssociate(hps, NULLHANDLE); /* Disassociates PS and screen DC */
GpiAssociate(hps, hdcMeta); /* Associates PS and meta DC */
GpiDrawSegment(hps, 10L); /* Draws segment into metafile */
GpiAssociate(hps, NULLHANDLE); /* Disassociates PS and meta DC */
hmf = DevCloseDC(hdcMeta); /* Closes metafile */
GpiAssociate(hps, hdc); /* Associates PS and screen DC */
GpiSetDrawingMode(hps, DM_DRAW); /* Sets drawing mode to DM_DRAW */
/*
* Load the array of options for GpiPlayMetaFile
* with default values.
*/
alOpt[PMF_SEGBASE] = 0; /* Reserved */
alOpt[PMF_LOADTYPE] = LT_DEFAULT; /* Default transformations */
alOpt[PMF_RESOLVE] = 0; /* Reserved */
alOpt[PMF_LCIDS] = LC_DEFAULT; /* Uses default lcids */
alOpt[PMF_RESET] = RES_DEFAULT; /* Uses default */
alOpt[PMF_SUPPRESS] = SUP_DEFAULT; /* Uses default */
alOpt[PMF_COLORTABLES] = CTAB_DEFAULT; /* Uses default */
alOpt[PMF_COLORREALIZABLE] = CREA_DEFAULT; /* Uses default */
GpiPlayMetaFile(hps, /* Plays metafile onto screen */
hmf, 8L, alOpt, (PLONG) NULL, 0L, (PSZ) NULL);
} /* fncMETA02 */
If you want to create a simple drawing in a metafile for repeated display, you can set the drawing mode to DM_DRAW and draw directly into the metafile. The code in the first code fragment shows an example of how to do this. You can store named segments in the metafile that you are recording in DM_DRAW mode by bracketing your output primitive functions between GpiOpenSegment and GpiCloseSegment.
Copying a Metafile to Disk
You can copy a metafile to disk using GpiSaveMetaFile, and you can load the file back into your application using GpiLoadMetaFile. The following example shows how to copy a metafile to a file named META.MET, then load the same file back into the application and play it.
#define INCL_GPIMETAFILES
#include <os2.h>
void fncMETA03(void){
HMF hmf;
HAB hab;
HPS hps;
LONG alOpt[10];
GpiSaveMetaFile(hmf, "meta.met"); /* Saves metafile on disk */
hmf = GpiLoadMetaFile(hab, "meta.met"); /* Loads metafile */
alOpt[PMF_SEGBASE] = 0; /* Reserved */
alOpt[PMF_LOADTYPE] = LT_DEFAULT; /* Default transformations */
alOpt[PMF_RESOLVE] = 0; /* Reserved */
alOpt[PMF_LCIDS] = LC_DEFAULT; /* Uses default lcids */
alOpt[PMF_RESET] = RES_DEFAULT; /* Uses default */
alOpt[PMF_SUPPRESS] = SUP_DEFAULT; /* Uses default */
alOpt[PMF_COLORTABLES] = CTAB_DEFAULT; /* Uses default */
alOpt[PMF_COLORREALIZABLE] = CREA_DEFAULT; /* Uses default */
GpiPlayMetaFile(hps, hmf, 8, alOpt, (PLONG) NULL, 0L, (PSZ) NULL);
} /* fncMETA03 */
Playing a Metafile
The following example shows how to play the metafile using the font, color table, and fill-pattern descriptions in your application's presentation space.
#define INCL_GPIMETAFILES
#include <os2.h>
void fncMETA04(void){
HPS hps;
HMF hmf;
LONG alOpt[10];
alOpt[PMF_SEGBASE] = 0; /* Reserved */
alOpt[PMF_LOADTYPE] = LT_DEFAULT; /* Viewing transformation in PS */
alOpt[PMF_RESOLVE] = RS_DEFAULT; /* Reserved */
alOpt[PMF_LCIDS] = LC_DEFAULT; /* Font and fill pattern in PS */
alOpt[PMF_RESET] = RES_DEFAULT; /* Page units and dimensions in PS */
alOpt[PMF_SUPPRESS] = SUP_DEFAULT; /* Draws metafile into PS */
alOpt[PMF_COLORTABLES] = CTAB_DEFAULT; /* Color table in PS */
alOpt[PMF_COLORREALIZABLE] = CREA_DEFAULT; /* Sets realizable option */
GpiPlayMetaFile(hps, hmf, 8, alOpt, (PLONG) NULL, 0L, (PSZ) NULL);
} /* fncMETA04 */
The following example shows how to play a metafile using the font, color table, and fill-pattern descriptions in the metafile.
#define INCL_GPIMETAFILES
#include <os2.h>
void fncMETA05(void){
HPS hps;
HMF hmf;
LONG alOpt[10];
alOpt[PMF_SEGBASE] = 0; /* Reserved */
alOpt[PMF_LOADTYPE] = LT_DEFAULT; /* Viewing transformation in PS */
alOpt[PMF_RESOLVE] = RS_DEFAULT; /* Reserved */
alOpt[PMF_LCIDS] = LC_LOADDISC; /* Font and fill pattern in metafile */
alOpt[PMF_RESET] = RES_DEFAULT; /* Page units and dimensions in PS */
alOpt[PMF_SUPPRESS] = SUP_DEFAULT; /* Draws metafile into PS */
alOpt[PMF_COLORTABLES] = CTAB_REPLACE; /* Color table in metafile */
alOpt[PMF_COLORREALIZABLE] = CREA_DEFAULT; /* Sets realizable option */
GpiPlayMetaFile(hps, hmf, 8, alOpt, (PLONG) NULL, 0L, (PSZ) NULL);
} /* fncMETA05 */
The following example shows how to play a metafile using the viewing transformation, page units, and presentation-page dimensions specified in the metafile.
#define INCL_GPIMETAFILES
#include <os2.h>
void fncMETA06(void){
HPS hps;
HMF hmf;
LONG alOpt[10];
alOpt[PMF_SEGBASE] = 0; /* Reserved */
alOpt[PMF_LOADTYPE] = LT_ORIGINALVIEW; /* Viewing transformation */
alOpt[PMF_RESOLVE] = RS_DEFAULT; /* Reserved */
alOpt[PMF_LCIDS] = LC_DEFAULT; /* Font and fill pattern in PS */
alOpt[PMF_RESET] = RES_RESET; /* Page units/dimensions */
alOpt[PMF_SUPPRESS] = SUP_DEFAULT; /* Draws metafile into PS */
alOpt[PMF_COLORTABLES] = CTAB_DEFAULT; /* Uses color table in PS */
alOpt[PMF_COLORREALIZABLE] = CREA_DEFAULT; /* Sets realizable option */
GpiPlayMetaFile(hps, hmf, 8, alOpt, (PLONG) NULL, 0L, (PSZ) NULL);
} /* fncMETA06 */