| HANDLE SetClipboardData(wFormat, hMem) | |||||
| UINT wFormat; | /* clipboard format | */ | |||
| HANDLE hMem; | /* data handle | */ | |||
This function sets a data handle to the clipboard for the data specified by the hMem parameter. The data are assumed to have the format specified by the wFormat parameter. After setting a clipboard data handle, the SetClipboardData function frees the block of memory identified by hMem.
wFormat
Specifies a data format. It can be any one of the predefined formats shown in the Comments section.
In addition to the predefined formats, any format value registered through the RegisterClipboardFormat function can be used as the wFormat parameter.
hMem
Identifies the global memory block that contains the data in the specified format. The hMem parameter can be NULL. When hMem is NULL the application does not have to format the data and provide a handle to it until requested to do so through a WM_RENDERFORMAT message.
The return value is a handle to the data if the function is successful. The return value is NULL if the hMem parameter specified a NULL handle or an error occurred.
Once the hMem parameter has been passed to SetClipboardData, the block of data becomes the property of the clipboard. The application may read the data, but should not free the block or leave it locked.
The following list shows the various predefined data-format values for the wFormat parameter:
| Value | Meaning |
| CF_BITMAP | ||
| A handle to a bitmap (HBITMAP). | ||
| CF_DIB | ||
| A memory block containing a BITMAPINFO structure followed by the bitmap bits. | ||
| CF_DIF | ||
| Software Arts' Data Interchange Format. | ||
| CF_DSPBITMAP | ||
| Bitmap display format associated with private format. The hMem parameter must be a handle to data that can be displayed in bitmap format in lieu of the privately formatted data. | ||
| CF_DSPENHMETAFILE | ||
| Enhanced metafile display format associated with private format. The hMem parameter must be a handle to data that can be displayed in enhanced metafile format in lieu of the privately formatted data. | ||
| CF_DSPMETAFILEPICT | ||
| Metafile-picture display format associated with private format. The hMem parameter must be a handle to data that can be displayed in metafile-picture format in lieu of the privately formatted data. | ||
| CF_DSPTEXT | ||
| Text display format associated with private format. The hMem parameter must be a handle to data that can be displayed in text format in lieu of the privately formatted data. | ||
| CF_ENHMETAFILE | ||
| A handle to an enhanced metafile (HEMF). | ||
| CF_METAFILEPICT | ||
| Handle to a metafile picture format as defined by the METAFILEPICT structure. When passing a CF_METAFILEPICT handle via DDE, the application responsible for deleting hData should also free the metafile referred to by the CF_METAFILEPICT handle. | ||
| CF_OEMTEXT | ||
| Text format containing characters in the OEM character set. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data. | ||
| CF_OWNERDISPLAY | ||
| Owner display format. The clipboard owner must display and update the clipboard application window, and will receive WM_ASKCBFORMATNAME, WM_HSCROLLCLIPBOARD, WM_PAINTCLIPBOARD, WM_SIZECLIPBOARD, and WM_VSCROLLCLIPBOARD messages. The hMem parameter must be NULL. | ||
| CF_PALETTE | ||
| Handle to a color palette. Whenever an application places data in the clipboard that depends on or assumes a color palette, it should also place the palette in the clipboard as well. | ||
| If the clipboard contains data in the CF_PALETTE (logical color palette) format, the application should assume that any other data in the clipboard is realized against that logical palette. | ||
| The clipboard-viewer application (CLIPBRD.EXE) always uses as its current palette any object in CF_PALETTE format that is in the clipboard when it displays the other formats in the clipboard. | ||
| CF_PRIVATEFIRST to CF_PRIVATELAST | ||
| Range of integer values used for private formats. Data handles associated with formats in this range will not be freed automatically; any data handles must be freed by the application before the application terminates or when a WM_DESTROYCLIPBOARD message is received. | ||
| CF_SYLK | ||
| Microsoft Symbolic Link (SYLK) format. | ||
| CF_TEXT | ||
| Text format. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data. | ||
| CF_TIFF | ||
| Tag Image File Format. | ||
Windows supports two formats for text, CF_TEXT and CF_OEMTEXT. CF_TEXT is the default Windows text clipboard format, while Windows uses the CF_OEMTEXT format for text in non-Windows applications. If you call GetClipboardData to retrieve data in one text format and the other text format is the only available text format, Windows automatically converts the text to the requested format before supplying it to your application.
Windows supports two formats for metafiles, CF_ENHMETAFILE and CF_METAFILEPICT. CF_ENHMETAFILE is specified for the enhanced metafiles and CF_METAFILEPICT is specified for the Windows metafiles. If an application calls GetClipboardData to retrieve data in one metafile format and the other metafile format is the available metafile format, Windows automatically converts the metafile to the requested format before supplying it to the application. Only one metafile format can be set at a time. The new metafile replaces the previous metafile even if it is in a different format. An application needs to understand only one metafile format to display metafiles.
An application registers other standard formats, such as Rich Text Format (RTF), by name using the RegisterClipboardFormat function rather than by a symbolic constant. For information on these external formats, see the README.TXT file.
GetClipboardData, RegisterClipboardFormat