SetClipboardData Function

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 OpenClipboard function. (When responding to the WM_RENDERFORMAT and WM_RENDERALLFORMATS messages, the clipboard owner must not call OpenClipboard before calling SetClipboardData.)

Syntax

HANDLE SetClipboardData(      
    UINT uFormat,
    HANDLE hMem
);

Parameters

uFormat
[in] Specifies a clipboard format. This parameter can be a registered format or any of the standard clipboard formats. For more information, see Registered Clipboard Formats and Standard Clipboard Formats.
hMem
[in] Handle to 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 and WM_RENDERALLFORMATS messages.

If SetClipboardData succeeds, the system owns the object identified by the hMem parameter. The application may not write to or free the data once ownership has been transferred to the system, but it can lock and read from the data until the CloseClipboard function is called. (The memory must be unlocked before the Clipboard is closed.) If the hMem parameter identifies a memory object, the object must have been allocated using the function with the GMEM_MOVEABLE flag.

Return Value

If the function succeeds, the return value is the handle to 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 standard clipboard formats. For more information, see Registered Clipboard Formats and Standard Clipboard Formats.

If an application calls SetClipboardData in response to WM_RENDERFORMAT or WM_RENDERALLFORMATS, the application should not use the handle after SetClipboardData has been called.

If an application calls OpenClipboard with hwnd set to NULL, EmptyClipboard sets the clipboard owner to NULL; this causes SetClipboardData to fail.

The system performs implicit data format conversions between certain clipboard formats when an application calls the GetClipboardData function. For example, if the CF_OEMTEXT format is on the clipboard, a window can retrieve data in the CF_TEXT format. The format on the clipboard is converted to the requested format on demand. For more information, see Synthesized Clipboard Formats.

Example

For an example, see Copying Information to the Clipboard.

Function Information

Minimum DLL Versionuser32.dll
HeaderDeclared in Winuser.h, include Windows.h
Import libraryUser32.lib
Minimum operating systems Windows 95, Windows NT 3.1

See Also

Tags :


Community Content

byteboon
You must OpenClipboard with WM_RENDERALLFORMATS!
This document incorrectly states that "the clipboard owner must not call OpenClipboard before calling SetClipboardData" when handling WM_RENDERALLFORMATS. See the documentation for WM_RENDERALLFORMATS which correctly indicates that you need to.
Tags :

Dan Mattsson
Copying a CString to the Clipboard
Maybe it's self-evident for some, but for me it was hard to find how to copy a CString (or any string, actually) to the clipboard. I was missing that I was supposed to do a GlobalAlloc and "manually" copy the data like below:

msg.Format(_T("Error: %s(%d) %s"), fileName, iLine, errText);

HGLOBAL hResult = GlobalAlloc(GMEM_MOVEABLE, msg.GetLength()); 
LPTSTR lptstrCopy = (LPTSTR)GlobalLock(hResult); 
memcpy(lptstrCopy, msg.GetBuffer(), msg.GetLength()); 
GlobalUnlock(hResult); 

if ( ::SetClipboardData( CF_OEMTEXT, hResult ) == NULL )
{
    TRACE( "Unable to set Clipboard data" );
    CloseClipboard();
    return;
}
CloseClipboard();
Tags :

Page view tracker