Função CreateCaret (winuser.h)

Artigo
05/09/2024

Cria uma nova forma para o cursor do sistema e atribui a propriedade do cursor à janela especificada. A forma de cursor pode ser uma linha, um bloco ou um bitmap.

Sintaxe

BOOL CreateCaret(
  [in]           HWND    hWnd,
  [in, optional] HBITMAP hBitmap,
  [in]           int     nWidth,
  [in]           int     nHeight
);

Parâmetros

[in] hWnd

Digite: HWND

Um identificador para a janela que possui o cursor.

[in, optional] hBitmap

Tipo: HBITMAP

Um identificador para o bitmap que define a forma de cursor. Se esse parâmetro for NULL, o cursor será sólido. Se esse parâmetro for (HBITMAP) 1, o cursor será cinza. Se esse parâmetro for um identificador de bitmap, o cursor será o bitmap especificado. O identificador de bitmap deve ter sido criado pela função CreateBitmap, CreateDIBitmap ou LoadBitmap . O cursor é desenhado para a tela por meio da operação XOR.

Se hBitmap for um identificador de bitmap, CreateCaret ignorará os parâmetros nWidth e nHeight ; o bitmap define sua própria largura e altura. O aplicativo não deve excluir o hBitmap até que o cursor seja destruído ou substituído por outro cursor.

[in] nWidth

Tipo: int

A largura do cursor, em unidades lógicas. Se esse parâmetro for zero, a largura será definida como a largura da borda da janela definida pelo sistema. Se hBitmap for um identificador de bitmap, CreateCaret ignorará esse parâmetro.

[in] nHeight

Tipo: int

A altura do cursor, em unidades lógicas. Se esse parâmetro for zero, a altura será definida como a altura da borda da janela definida pelo sistema. Se hBitmap for um identificador de bitmap, CreateCaret ignorará esse parâmetro.

Retornar valor

Tipo: BOOL

Se a função for bem-sucedida, o valor retornado será diferente de zero.

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

Comentários

Os parâmetros nWidth e nHeight especificam a largura e a altura do cursor, em unidades lógicas; a largura e a altura exatas, em pixels, dependem do modo de mapeamento da janela.

CreateCaret destrói automaticamente a forma de cursor anterior, se houver, independentemente da janela que possui o cursor. O cursor fica oculto até que o aplicativo chame a função ShowCaret para tornar o cursor visível.

O sistema fornece um cursor por fila. Uma janela deve criar um cursor somente quando tiver o foco do teclado ou estiver ativo. A janela deve destruir o cursor antes de perder o foco do teclado ou ficar inativa.

Virtualização de DPI

Essa API não participa da virtualização de DPI. Os parâmetros de largura e altura são interpretados como tamanhos lógicos em termos da janela em questão. O thread de chamada não é levado em consideração.

Requisitos

Requisito	Valor
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-caret-l1-1-0 (introduzido em Windows 8)