Função SetClipboardData (winuser.h)

Artigo
08/28/2023

Coloca os dados na área de transferência em um formato de área de transferência especificado. A janela deve ser o proprietário da área de transferência atual e o aplicativo deve ter chamado a função OpenClipboard . (Ao responder à mensagem WM_RENDERFORMAT , o proprietário da área de transferência não deve chamar OpenClipboard antes de chamar SetClipboardData.)

Sintaxe

HANDLE SetClipboardData(
  [in]           UINT   uFormat,
  [in, optional] HANDLE hMem
);

Parâmetros

[in] uFormat

Tipo: UINT

O formato da área de transferência. Esse parâmetro pode ser um formato registrado ou qualquer um dos formatos de área de transferência padrão. Para obter mais informações, consulte Formatos de área de transferência padrão e formatos de área de transferência registrados.

[in, optional] hMem

Tipo: HANDLE

Um identificador para os dados no formato especificado. Esse parâmetro pode ser NULL, indicando que a janela fornece dados no formato de área de transferência especificado (renderiza o formato) mediante solicitação; isso é conhecido como renderização atrasada. Se uma janela atrasar a renderização, ela deverá processar as mensagens WM_RENDERFORMAT e WM_RENDERALLFORMATS .

Se SetClipboardData for bem-sucedido, o sistema será o proprietário do objeto identificado pelo parâmetro hMem . O aplicativo pode não gravar ou liberar os dados depois que a propriedade tiver sido transferida para o sistema, mas pode bloquear e ler os dados até que a função CloseClipboard seja chamada. (A memória deve ser desbloqueada antes que a Área de Transferência seja fechada.) Se o parâmetro hMem identificar um objeto de memória, o objeto deverá ter sido alocado usando a função com o sinalizador GMEM_MOVEABLE .

Valor retornado

Tipo: HANDLE

Se a função for bem-sucedida, o valor retornado será o identificador para os dados.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Windows 8: Os bitmaps a serem compartilhados com aplicativos da Windows Store devem estar no formato CF_BITMAP (bitmap dependente do dispositivo).

Se um aplicativo chamar SetClipboardData em resposta a WM_RENDERFORMAT ou WM_RENDERALLFORMATS, o aplicativo não deverá usar o identificador depois que SetClipboardData tiver sido chamado.

Se um aplicativo chamar OpenClipboard com hwnd definido como NULL, EmptyClipboard definirá o proprietário da área de transferência como NULL; isso faz com que SetClipboardData falhe.

O sistema executa conversões implícitas de formato de dados entre determinados formatos de área de transferência quando um aplicativo chama a função GetClipboardData . Por exemplo, se o formato CF_OEMTEXT estiver na área de transferência, uma janela poderá recuperar dados no formato CF_TEXT . O formato na área de transferência é convertido no formato solicitado sob demanda. Para obter mais informações, consulte Formatos de área de transferência sintetizados.

Exemplos

Para obter um exemplo, consulte Copiando informações para a área de transferência.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll
Conjunto de APIs	ext-ms-win-ntuser-misc-l1-2-0 (introduzido no Windows 8.1)