Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

CreateEnhMetaFile function

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

Syntax


HDC CreateEnhMetaFile(
  _In_  HDC hdcRef,
  _In_  LPCTSTR lpFilename,
  _In_  const RECT *lpRect,
  _In_  LPCTSTR lpDescription
);

Parameters

hdcRef [in]

A handle to a reference device for the enhanced metafile. This parameter can be NULL; for more information, see Remarks.

lpFilename [in]

A pointer to the file name 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 [in]

A pointer to a RECT structure that specifies the dimensions (in .01-millimeter units) of the picture to be stored in the enhanced metafile.

lpDescription [in]

A pointer to a string that specifies the name of the application that created the picture, as well as the picture's title. This parameter can be NULL; for more information, see Remarks.

Return value

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 character set, use this function as an ANSI function.

The system 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 charactersfor 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, the system 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 file name for the enhanced metafile should use the .emf extension.

Examples

For an example, see Creating an Enhanced Metafile.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Wingdi.h (include Windows.h)

Library

Gdi32.lib

DLL

Gdi32.dll

Unicode and ANSI names

CreateEnhMetaFileW (Unicode) and CreateEnhMetaFileA (ANSI)

See also

Metafiles Overview
Metafile Functions
CloseEnhMetaFile
DeleteEnhMetaFile
GetEnhMetaFileDescription
GetEnhMetaFileHeader
GetWinMetaFileBits
PlayEnhMetaFile
RECT

 

 

Build date: 6/12/2013

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.