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

キャレットの幅 (論理単位)。このパラメーターが 0 の場合、幅はシステム定義のウィンドウ罫線の幅に設定されます。 hBitmap がビットマップハンドルの場合、CreateCaret はこのパラメーターを無視します。

[in] nHeight

型: int

キャレットの高さ (論理単位)。このパラメーターが 0 の場合、高さはシステム定義のウィンドウ罫線の高さに設定されます。 hBitmap がビットマップハンドルの場合、CreateCaret はこのパラメーターを無視します。

戻り値

種類: BOOL

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

nWidth パラメーターと nHeight パラメーターは、キャレットの幅と高さを論理単位で指定します。正確な幅と高さ (ピクセル単位) は、ウィンドウのマッピングモードによって異なります。

CreateCaret は、キャレットを所有するウィンドウに関係なく、前のキャレット図形 (存在する場合) を自動的に破棄します。キャレットは、アプリケーションが ShowCaret 関数を呼び出してキャレットを表示するまで非表示になります。

システムは、キューごとに 1 つのキャレットを提供します。ウィンドウにキャレットが作成されるのは、キーボードフォーカスがある場合、またはアクティブな場合のみです。ウィンドウは、キーボードフォーカスを失うか非アクティブになる前にキャレットを破棄する必要があります。

DPI 仮想化

この API は、DPI 仮想化には参加しません。幅と高さのパラメーターは、問題のウィンドウの観点から論理サイズとして解釈されます。呼び出し元のスレッドは考慮されません。

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	winuser.h (Windows.h を含む)
Library	User32.lib
[DLL]	User32.dll
API セット	ext-ms-win-ntuser-caret-l1-1-0 (Windows 8で導入)