CreateCaret-Funktion (winuser.h)

Artikel
05/09/2024

Erstellt eine neue Form für das Caretzeichen des Systems und weist dem angegebenen Fenster den Besitz des Caretzeichens zu. Die Caretform kann eine Linie, ein Block oder eine Bitmap sein.

Syntax

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

Parameter

[in] hWnd

Typ: HWND

Ein Handle für das Fenster, das das Caret besitzt.

[in, optional] hBitmap

Typ: HBITMAP

Ein Handle für die Bitmap, das die Caretform definiert. Wenn dieser Parameter NULL ist, ist das Caret einfarbig. Wenn dieser Parameter ist, ist (HBITMAP) 1das Caretzeichen grau. Wenn es sich bei diesem Parameter um ein Bitmaphandle handelt, ist das Caret die angegebene Bitmap. Das Bitmaphandle muss von der Funktion CreateBitmap, CreateDIBitmap oder LoadBitmap erstellt worden sein. Das Caret wird über den XOR-Vorgang auf den Bildschirm gezeichnet.

Wenn hBitmap ein Bitmaphandle ist, ignoriert CreateCaret die Parameter nWidth und nHeight . die Bitmap definiert ihre eigene Breite und Höhe. Die Anwendung sollte die hBitmap erst löschen, wenn das Caretzeichen zerstört oder durch ein anderes Caretzeichen ersetzt wird.

[in] nWidth

Typ: int

Die Breite des Caretzeichens in logischen Einheiten. Wenn dieser Parameter null ist, wird die Breite auf die systemdefinierte Fensterrahmenbreite festgelegt. Wenn hBitmap ein Bitmaphandle ist, ignoriert CreateCaret diesen Parameter.

[in] nHeight

Typ: int

Die Höhe des Caretzeichens in logischen Einheiten. Wenn dieser Parameter null ist, wird die Höhe auf die systemdefinierte Fensterrahmenhöhe festgelegt. Wenn hBitmap ein Bitmaphandle ist, ignoriert CreateCaret diesen Parameter.

Rückgabewert

Typ: BOOL

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die Parameter nWidth und nHeight geben die Breite und Höhe des Carets in logischen Einheiten an. Die genaue Breite und Höhe in Pixel hängt vom Zuordnungsmodus des Fensters ab.

CreateCaret zerstört automatisch die vorherige Caret-Form, sofern vorhanden, unabhängig vom Fenster, das das Caretzeichen besitzt. Das Caret wird ausgeblendet, bis die Anwendung die ShowCaret-Funktion aufruft , um das Caret sichtbar zu machen.

Das System stellt ein Caret pro Warteschlange bereit. Ein Fenster sollte nur dann ein Caret erstellen, wenn es den Tastaturfokus hat oder aktiv ist. Das Fenster sollte das Caretzeichen zerstören, bevor der Tastaturfokus verloren geht oder inaktiv wird.

DPI-Virtualisierung

Diese API ist nicht an der DPI-Virtualisierung beteiligt. Die Parameter width und height werden als logische Größen im Hinblick auf das betreffende Fenster interpretiert. Der aufrufende Thread wird nicht berücksichtigt.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winuser.h (windows.h einschließen)
Bibliothek	User32.lib
DLL	User32.dll
APIs	ext-ms-win-ntuser-caret-l1-1-0 (eingeführt in Windows 8)