CreateCaret 函式 (winuser.h)

發行項
05/09/2024

建立系統插入號的新圖形，並將插入號的擁有權指派給指定的視窗。插入號圖形可以是線條、區塊或點陣圖。

語法

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

參數

[in] hWnd

類型： HWND

擁有插入號之視窗的句柄。

[in, optional] hBitmap

類型： HBITMAP

定義插入號圖形之點陣圖的句柄。如果此參數為 NULL，插入號為實心。如果此參數為 (HBITMAP) 1，插入號為灰色。如果此參數是位圖句柄，插入號就是指定的點陣圖。點陣圖句柄必須由 CreateBitmap、CreateDIBitmap 或 LoadBitmap 函式建立。插入號會透過 XOR 作業繪製到畫面。

如果 hBitmap 是位圖句柄， CreateCaret 會忽略 nWidth 和 nHeight 參數;位圖會定義自己的寬度和高度。除非插入號被另一個插入號終結或取代，否則應用程式不應該刪除 hBitmap 。

[in] nWidth

類型： int

插入號的寬度，以邏輯單元表示。如果此參數為零，則寬度會設定為系統定義的視窗框線寬度。如果 hBitmap 是位圖句柄， CreateCaret 會忽略此參數。

[in] nHeight

類型： int

插入號的高度，以邏輯單元表示。如果此參數為零，則高度會設定為系統定義的視窗框線高度。如果 hBitmap 是位圖句柄， CreateCaret 會忽略此參數。

傳回值

類型： BOOL

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

nWidth 和 nHeight 參數會以邏輯單元指定插入號的寬度和高度;確切的寬度和高度，以像素為單位，取決於窗口的對應模式。

不論擁有插入號的窗口為何，CreateCaret 都會自動終結先前的插入號圖形。插入號會隱藏，直到應用程式呼叫 ShowCaret 函式，才能顯示插入號。

系統會針對每個佇列提供一個插入號。只有在視窗具有鍵盤焦點或作用中時，才會建立插入號。窗口應該會在失去鍵盤焦點或變成非作用中之前終結插入號。

DPI 虛擬化

此 API 不會參與 DPI 虛擬化。寬度和高度參數會解譯為有問題窗口的邏輯大小。呼叫線程不會納入考慮。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winuser.h (包括 Windows.h)
程式庫	User32.lib
Dll	User32.dll
API 集合	ext-ms-win-ntuser-caret-l1-1-0 (於 Windows 8)