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 returnlinefeed (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.

See Also

CloseClipboard, GetClipboardData, GlobalAlloc, OpenClipboard, RegisterClipboardFormat