SetClipboardData

2.x

	HANDLE SetClipboardData(uFormat, hData)
	UINT uFormat;	/* clipboard format, */
	HANDLE hData;	/* data handle, */

The SetClipboardData function sets the data in the clipboard. The application must have called the OpenClipboard function before calling the SetClipboardData function.

Parameters

uFormat

Specifies the format of the data. It can be any one of the system-defined formats or a format registered by the RegisterClipboardFormat function. For a list of system-defined formats, see the following Comments section.

hData

Identifies the data to be placed in the clipboard. For all formats except CF_BITMAP and CF_PALETTE, this parameter must be a handle of the memory allocated by the GlobalAlloc function. For CF_BITMAP format, the hData parameter is a bitmap handle (see the description of the LoadBitmap function). For the CF_PALETTE format, hData is a palette handle (see the description of the CreatePalette function).

If this parameter is NULL, the owner of the clipboard will be sent a WM_RENDERFORMAT message when it must supply the data.

Return Value

The return value is a handle of the data, if the function is successful. Otherwise, it is NULL.

Comments

If the hData parameter contains a handle of the memory allocated by the GlobalAlloc function, the application must not use this handle once it has called the SetClipboardData function.

Following are the system-defined clipboard formats:

Value

Meaning

CF_BITMAP	The data is a bitmap.
CF_DIB	The data is a memory object containing a BITMAPINFO structure followed by the bitmap data.
CF_DIF	The data is in Data Interchange Format (DIF).
CF_DSPBITMAP	The data is a bitmap representation of a private format. This data is displayed in bitmap format in lieu of the privately formatted data.
CF_DSPMETAFILEPICT	The data is a metafile representation of a private data format. This data is displayed in metafile-picture format in lieu of the privately formatted data.
CF_DSPTEXT	The data is a textual representation of a private data format. This data is displayed in text format in lieu of the privately formatted data.
CF_METAFILEPICT	The data is a metafile (see the description of the METAFILEPICT structure in the Microsoft Windows Programmer's Reference, Volume 3).
CF_OEMTEXT	The data is an array of text 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	The data is in a private format that the clipboard owner must display.
CF_PALETTE	The data is a color palette.
CF_PENDATA	The data is for the pen extensions to the Windows operating system.
CF_RIFF	The data is in Resource Interchange File Format (RIFF).
CF_SYLK	The data is in Microsoft Symbolic Link (SYLK) format.
CF_TEXT	The data is an array of text characters. Each line ends with a carriage return–linefeed (CR–LF) combination. A null character signals the end of the data.
CF_TIFF	The data is in Tag Image File Format (TIFF).
CF_WAVE	The data describes a sound wave. This is a subset of the CF_RIFF data format; it can be used only for RIFF WAVE files.

Private data formats in the range CF_PRIVATEFIRST through CF_PRIVATELAST are not automatically freed when the data is removed from the clipboard. Data handles associated with these formats should be freed upon receiving a WM_DESTROYCLIPBOARD message.

Private data formats in the range CF_GDIOBJFIRST through CF_GDIOBJLAST will be automatically removed by a call to the DeleteObject function when the data is removed from the clipboard.

If Windows Clipboard is running, it will not update its window to show the data placed in the clipboard by the SetClipboardData until after the CloseClipboard function is called.