SetClipboardData
The SetClipboardData
function places data on the clipboard in a specified clipboard format. The
window must be the current clipboard owner, and the application must have
called the OpenClipboard3W7HWO and WM_RENDERALLFORMATS messages, the clipboard owner
must not call OpenClipboard before calling SetClipboardData.)
HANDLE SetClipboardData(
UINT uFormat, |
// clipboard
format |
HANDLE hMem |
// data handle |
); |
|
Parameters
uFormat
Specifies a
clipboard format. This parameter can be a registered format or any of the
standard clipboard formats listed in the following Remarks section. For
information about registered clipboard formats, see the RegisterClipboardFormat
hMem
Identifies
the data in the specified format. This parameter can be NULL, indicating that
the window provides data in the specified clipboard format (renders the format)
upon request. If a window delays rendering, it must process the WM_RENDERFORMAT
Once SetClipboardData is called, the system owns the object
identified by the hMem parameter. The application can read the data, but
must not free the handle or leave it locked. If the hMem parameter
identifies a memory object, the object must have been allocated using the GlobalAlloc
Return Values
If the
function succeeds, the return value is the handle of the data.
If the
function fails, the return value is NULL. To get extended error information,
call GetLastError
Remarks
The uFormat
parameter can identify a registered clipboard format, or it can be one of the
following values:
Value |
Meaning |
CF_BITMAP |
A handle to
a bitmap (HBITMAP). |
CF_DIB |
A memory
object containing a BITMAPINFO |
CF_DIF |
Software
Arts Data Interchange Format. |
CF_DSPBITMAP |
Bitmap
display format associated with a private format. The hMem parameter
must be a handle of data that can be displayed in bitmap format in lieu of
the privately formatted data. |
CF_DSPENHMETAFILE |
Enhanced
metafile display format associated with a private format. The hMem
parameter must be a handle of data that can be displayed in enhanced metafile
format in lieu of the privately formatted data. |
CF_DSPMETAFILEPICT |
Metafile-picture
display format associated with a private format. The hMem parameter
must be a handle of data that can be displayed in metafile-picture format in
lieu of the privately formatted data. |
CF_DSPTEXT |
Text
display format associated with a private format. The hMem parameter
must be a handle of data that can be displayed in text format in lieu of the
privately formatted data. |
CF_ENHMETAFILE |
A handle of
an enhanced metafile (HENHMETAFILE). |
CF_GDIOBJFIRST
through CF_GDIOBJLAST |
Range of
integer values for application-defined GDI object clipboard formats. Handles
associated with clipboard formats in this range are not automatically deleted
using the GlobalFree |
CF_HDROP |
A handle of
type HDROP that identifies a list of files. An application can
retrieve information about the files by passing the handle to the DragQueryFile
functions. |
CF_LOCALE |
The data is
a handle to the locale identifier associated with text in the clipboard. When
you close the clipboard, if it contains CF_TEXT data but no CF_LOCALE data,
the system automatically sets the CF_LOCALE format to the current input
locale. You can use the CF_LOCALE format to associate a different locale with
the clipboard text. An
application that pastes text from the clipboard can retrieve this format to
determine which character set was used to generate the text. Note that
the clipboard does not support plain text in multiple character sets. To
achieve this, use a fomatted text data type such as RTF instead. Windows
NT: The system uses the code page
associated with CF_LOCALE to implicitly convert from CF_TEXT to
CF_UNICODETEXT. Therefore, the correct code page table is used for the
conversion. |
CF_METAFILEPICT |
Handle of a
metafile picture format as defined by the METAFILEPICT |
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 viewer
window, and receive the WM_ASKCBFORMATNAME |
CF_PALETTE |
Handle of a
color palette. Whenever an application places data in the clipboard that
depends on or assumes a color palette, it should place the palette on the
clipboard as well. |
|
If the
clipboard contains data in the CF_PALETTE (logical color palette) format, the
application should use the SelectPalette |
|
When
displaying clipboard data, Windows clipboard always uses as its current
palette any object on the clipboard that is in the CF_PALETTE format. |
CF_PENDATA |
Data for
the pen extensions to the Microsoft Windows for Pen Computing. |
CF_PRIVATEFIRST
through CF_PRIVATELAST |
Range of
integer values for private clipboard formats. Handles associated with private
clipboard formats are not freed automatically; the clipboard owner must free
such handles, typically in response to the WM_DESTROYCLIPBOARD |
CF_RIFF |
Represents
audio data more complex than can be represented in a CF_WAVE standard wave
format. |
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. Use this format for ANSI text. |
CF_WAVE |
Represents
audio data in one of the standard wave formats, such as 11 kHz or 22 kHz
pulse code modulation (PCM). |
CF_TIFF |
Tagged-image
file format. |
CF_UNICODETEXT |
Windows
NT only: Unicode text format. Each
line ends with a carriage return/linefeed (CR-LF) combination. A null
character signals the end of the data. |
The operating
system performs implicit data format conversions between certain clipboard
formats when an application calls the GetClipboardData
Clipboard
Format |
Conversion
Format |
Platform
Support |
CF_BITMAP |
CF_DIB |
Windows NT,
Windows 95 |
CF_DIB |
CF_BITMAP |
Windows NT,
Windows 95 |
CF_DIB |
CF_PALETTE |
Windows NT,
Windows 95 |
CF_ENHMETAFILE |
CF_METAFILEPICT |
Windows NT,
Windows 95 |
CF_METAFILEPICT |
CF_ENHMETAFILE |
Windows NT,
Windows 95 |
CF_OEMTEXT |
CF_TEXT |
Windows NT,
Windows 95 |
CF_OEMTEXT |
CF_UNICODETEXT |
Windows NT |
CF_TEXT |
CF_OEMTEXT |
Windows NT,
Windows 95 |
CF_TEXT |
CF_UNICODETEXT |
Windows NT |
CF_UNICODETEXT |
CF_OEMTEXT |
Windows NT |
CF_UNICODETEXT |
CF_TEXT |
Windows NT |
If the
operating system provides an automatic type conversion for a particular
clipboard format, there is no advantage to placing the conversion format(s) on
the clipboard.
When copying
bitmaps, it is best to place only the CF_DIB format on the clipboard. This is
because the colors in a device-dependent bitmap (CF_BITMAP) are relative to the
system palette, which may change before the bitmap is pasted. If only the
CF_DIB format is on the clipboard and a window requests the CF_BITMAP format,
the system renders the device-dependent bitmap using the current palette at
that time.
If you place
the CF_BITMAP format on the clipboard (and not CF_DIB), the system renders the
CF_DIB clipboard format as soon as the clipboard is closed. This ensures that
the correct palette is used to generate the device-independent bitmap (DIB).
Conversions between other clipboard formats occur upon demand.
Windows
platforms support two clipboard formats for metafiles: CF_ENHMETAFILE and
CF_METAFILEPICT. Specify CF_ENHMETAFILE for enhanced metafiles and
CF_METAFILEPICT for Windows metafiles.
See Also