CreateEnhMetaFile
The CreateEnhMetaFile
function creates a device context for an enhanced-format metafile. This device
context can be used to store a device-independent picture.
HDC CreateEnhMetaFile(
|
HDC hdcRef, |
// handle to a
reference device context |
|
LPCTSTR lpFilename, |
// pointer to a
filename string |
|
CONST RECT *lpRect, |
// pointer to a
bounding rectangle |
|
LPCTSTR lpDescription |
// pointer to an
optional description string |
|
); |
|
Parameters
hdcRef
Identifies a
reference device for the enhanced metafile.
lpFilename
Points to the
filename for the enhanced metafile to be created. If this parameter is NULL,
the enhanced metafile is memory based and its contents are lost when it is
deleted by using the DeleteEnhMetaFile function.
lpRect
Points to a RECT structure that specifies
the dimensions (in .01-millimeter units) of the picture to 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 Values
If the
function succeeds, the return value is a handle to the device context for the
enhanced metafile.
If the
function fails, the return value is NULL.
Remarks
Where text
arguments must use Unicode characters, use the CreateEnhMetaFile
function as a wide-character function. Where text arguments must use characters
from the Windows 3.x character set, use this function as an ANSI
function.
Windows uses
the reference device identified by the hdcRef parameter to record the
resolution and units of the device on which a picture originally appeared. If
the hdcRef parameter is NULL, it uses the current display device for
reference.
The left
and top members of the RECT structure pointed to by the lpRect
parameter 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, the graphics device interface (GDI) computes
the dimensions of the smallest rectangle that surrounds the picture drawn by
the application. The lpRect parameter should be provided where possible.
The string
pointed to by the lpDescription parameter must contain a null character
between the application name and the picture name and must terminate with two
null characters 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 device context can be passed
to any GDI function.
After 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 pointed to by the lpRect
parameter 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 device context.
Applications
must use the GetWinMetaFileBits function to convert an enhanced metafile
to the older Windows metafile format.
The filename
for the enhanced metafile should use the .EMF extension.
See Also