CreateEnhMetaFile

HDC CreateEnhMetaFile(hdcRef, lpFilename, lpRect, lpDescription)
HDC hdcRef;	/* handle of a reference device-context	*/
LPTSTR lpFilename;	/* address of a filename string	*/
LPRECT lpRect;	/* address of a bounding rectangle	*/
LPTSTR lpDescription;	/* address of an optional description-string	*/

The CreateEnhMetaFile function creates an enhanced-metafile device context that can be used to store a device-independent picture.

Parameters

hdcRef

Identifies a reference device for the enhanced metafile.

lpFilename

Points to a filename in which the enhanced metafile is stored.

lpRect

Points to a RECT structure that specifies the dimensions (in .01 mm units) of the picture that will be stored in the enhanced metafile.

lpDescription

Points to a string that specifies the name of the application that created the picture as well as the picture's title.

Return Value

The return value identifies the device context for the enhanced metafile if the function is successful. Otherwise, it is 0.

Comments

The CreateEnhMetaFile function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set).

Windows uses the reference device identified by hdcRef to record the resolution and color format of the device on which a picture originally appeared.

If lpFilename is NULL, the enhanced metafile is stored temporarily in memory.

The left and top members of the RECT structure at which lpRect points must be less than the right and bottom members respectively. Points along the edges of the rectangle are included in the picture. If lpRect is NULL, GDI computes the dimensions of the smallest rectangle that will surround the picture drawn by the application.

The string at which lpDescription points must contain two null characters between the application and the picture name. For example: “XYZ Graphics Editor\0Bald Eagle\0\0” where '\0' represents the null character). If lpDescription is NULL, there is no corresponding entry in the enhanced-metafile header.

Applications use the device context created by this function to store a graphics picture in an enhanced metafile. The handle identifying this DC can be passed to any GDI drawing function.

Once an application stores a picture in an enhanced metafile, it can display the picture on any output device (by calling the PlayEnhMetaFile function.) When displaying the picture, Windows uses the rectangle at which the lpRect structure points and the resolution data (from the reference device) to position and scale the picture.

The device context returned by this function contains the same default attributes associated with any new DC.

Applications must use the GetWinMetaFileBits function to convert an enhanced metafile to the older Windows-metafile format.

It is recommended that the filename for the enhanced metafile use the .EMF extension.