The GdiComment function copies a comment from a buffer into a specified enhanced-format metafile.
BOOL GdiComment(
|
HDC hdc, |
// handle to a device context |
|
UINT cbSize, |
// size of text buffer |
|
CONST BYTE *lpData |
// pointer to text buffer |
|
); |
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
A comment can include any kind of private information ¾ for example, the source of a picture and the date it was created. A comment should begin with an application signature, followed by the data.
Comments should not contain application-specific or position-specific data. Position-specific data specifies the location of a record, and it should not be included because one metafile may be embedded within another metafile.
A public comment is a comment that begins with the comment signature identifier GDICOMMENT_IDENTIFIER. The following public comments are defined:
|
Comment |
Description |
|
GDICOMMENT_WINDOWS_METAFILE | |
|
The GDICOMMENT_WINDOWS_METAFILE public comment contains a Windows-format metafile that is equivalent to an enhanced-format metafile. This comment is written only by the SetWinMetaFileBits function. The comment record, if given, follows the ENHMETAHEADER metafile record. The comment has the following form: |
DWORD ident; // This contains GDICOMMENT_IDENTIFIER. DWORD iComment; // This contains GDICOMMENT_WINDOWS_METAFILE. DWORD nVersion; // This contains the version number of the // Windows-format metafile. DWORD nChecksum; // This is the additive DWORD checksum for // the enhanced metafile. The checksum // for the enhanced metafile data including // this comment record must be zero. // Otherwise, the enhanced metafile has been // modified and the Windows-format // metafile is no longer valid. DWORD fFlags; // This must be zero. DWORD cbWinMetaFile; // This is the size, in bytes. of the // Windows-format metafile data that follows.
|
GDICOMMENT_BEGINGROUP | |
|
The GDICOMMENT_BEGINGROUP public comment identifies the beginning of a group of drawing records. It identifies an object within an enhanced metafile. The comment has the following form: |
DWORD ident; // This contains GDICOMMENT_IDENTIFIER. DWORD iComment; // This contains GDICOMMENT_BEGINGROUP. RECTL rclOutput; // This is the bounding rectangle for the // object in logical coordinates. DWORD nDescription; // This is the number of characters in the // optional Unicode description string that // follows. This is zero if there is no // description string.
|
GDICOMMENT_ENDGROUP | |
|
The GDICOMMENT_ENDGROUP public comment identifies the end of a group of drawing records. The GDICOMMENT_BEGINGROUP comment and the GDICOMMENT_ENDGROUP comment must be included in a pair and may be nested. The comment has the following form: |
DWORD ident; // This contains GDICOMMENT_IDENTIFIER. DWORD iComment; // This contains GDICOMMENT_ENDGROUP.
|
GDICOMMENT_MULTIFORMATS | |
|
The GDICOMMENT_MULTIFORMATS public comment allows multiple definitions of a picture to be included in an enhanced metafile. Using this comment, for example, an application can include an encapsulated PostScript definition as well as an enhanced metafile definition of a picture. When the record is played back, GDI selects and renders the first format recognized by the device. The comment has the following form: |
DWORD ident; // This contains GDICOMMENT_IDENTIFIER. DWORD iComment; // This contains GDICOMMENT_MULTIFORMATS. RECTL rclOutput; // This is the bounding rectangle for the // picture in logical coordinates. DWORD nFormats; // This contains the number of formats in // the comment. EMRFORMAT aemrformat[1];// This is an array of EMRFORMAT structures // in the order of preference. The data // for each format follows the last // EMRFORMAT structure.
The EMRFORMAT structure has the following form:
typedef struct tagEMRFORMAT {
DWORD dSignature;
DWORD nVersion;
DWORD cbData;
DWORD offData;
} EMRFORMAT;