レガシー Windows API(概要)について

ここで紹介しているAPIは、Windows95、Windows NT3.5時代のAPI群であり、最新のAPIは含まれていないことに注しして欲しい。なお、当時の解説書は現在よりもより詳細に解説しているため、参考になるはずである。

  • レイアウトを変換する際、崩れているページがあります。
  • 概要およびSampleコードはありますが、APIの解説はありません。

塾生の方で、ご要望があれば旧版のWin32 API(HELP形式)をお譲りします。

Windows API キャレットの概要

キャレットとは、 ウィンドウのクライアント領域で点滅する直線、 ブロック、 またはビットマップです。通常、 キャレットは、 テキストやグラフィックが挿入される場所を示します。キャレットの一般的な外観をいくつか次の図に示します。

次に示すトピックでは、 Win32のキャレットについて説明しています。

キャレットの作成と表示

キャレットの非表示

キャレットの破棄

ブリンク時間の調整

キーボード入力の処理

キャレット関数

キーボード フォーカスを持てるウィンドウやアクティブなウィンドウは同時に1つしかないため、 システムにはキャレットは1つしかありません。一般に、 キーボード入力を受けつけるウィンドウは、 キーボード フォーカスを取得したらキャレットを作成し、 キーボード フォーカスを失ったらキャレットを破棄しなければなりません。キーボード入力について詳しくは、 キーボード入力を参照してください。

Microsoft(R) Windows(TM) 用に作成されたアプリケーションは、 キャレットの作成、 表示、 非表示、 位置の変更、 ブリンク時間の変更を行うことができます。

キャレットのパラメータを指定するには、 CreateCaret関数を使ってください。Microsoft Windowsは、 キャレットの位置、 幅、 高さが示す長方形内のピクセルの色を反転します。幅と高さは論理単位で指定します。このため、 キャレットの表示はウィンドウのマッピング モードによって異なります。

キャレットを定義したら、 ShowCaret関数を使ってキャレットを表示できます。キャレットは、 表示されると自動的に点滅を開始します。純色のキャレットを表示するときは、 Windowsは、 長方形内の全ピクセルを反転します。灰色のキャレットを表示するときは、 Windowsは、 ピクセルを1個おきに反転します。ビットマップ キャレットを表示するときは、 ビットマップの白いビットだけを反転します。

キャレットを反転するまでのミリ秒単位の経過時間は、 「ブリンク時間」と呼ばれます。キャレットのブリンク時間を判断するには、 GetCaretBlinkTime関数を使ってください。特定のブリンク時間を定義しなければならないときは、 SetCaretBlinkTime関数を使って、 ブリンク時間をミリ秒単位で設定してください。「点滅時間」とは、 キャレットを表示して反転し、 元の表示に復元するのに必要な時間 (ミリ秒単位) です。キャレットの点滅時間は、 ブリンク時間の2倍です。

キャレットの位置を判断するには、 GetCaretPos関数を使ってください。GetCaretPosのパラメータで指定したPOINT構造体に、 クライアント座標で表現した位置がコピーされます。ウィンドウ内でキャレットを移動するには、 SetCaretPos関数を使ってください。ウィンドウがキャレットを所有しているときだけ、 キャレットを移動できます。SetCaretPosは、 キャレットが表示されているかどうかにかかわらずキャレットを移動できます。

キャレットを画面から削除するには、 HideCaret関数を使ってください。これは、 メッセージの処理時に画面を再描画しなければならない場合、 キャレットが描画に影響を与えないようするのに役立ちます。アプリケーションは、 描画を終了したら、 ShowCaret関数を使ってキャレットをもう一度表示してください。キャレットを非表示にしても、 キャレットが破棄されたり、 挿入点が無効化されることはありません。キャレットの非表示は蓄積されます。つまり、 HideCaretを5回呼び出したら、 キャレットを再表示するにはShowCaretを5回呼び出さなければなりません。

キャレットを画面から削除して破棄するには、 DestroyCaret関数を使ってください。DestroyCaretは、 現在のタスクのウィンドウがキャレットを所有しているときだけ、 キャレットを破棄します。

 

キャレットの作成と表示

ウィンドウがキーボード フォーカスを受け取ったら、 キャレットを作成して表示してください。ウィンドウにキャレットを作成するには、 CreateCaret関数を使ってください。それから、 SetCaretPosを呼び出してキャレットの現在位置を設定し、 ShowCaretを呼び出してキャレットを表示してください。

システムは、 キーボード フォーカスを受け取るウィンドウにWM_SETFOCUSメッセージを送ります。このため、 WM_SETFOCUSメッセージを処理するときに、 キャレットを作成して表示してください。

HWND hwnd, /* window handle */
int x; /* horizontal coordinate of cursor */
int y; /* vertical coordinate of cursor */
int nWidth; /* width of cursor */
int nHeight; /* height of cursor */
char *lpszChar; /* pointer to character */
case WM_SETFOCUS:
/* Create a solid black caret. */
CreateCaret(hwnd, (HBITMAP) NULL, nWidth, nHeight);
/* Adjust the caret position, in client coordinates. */
SetCaretPos(x, y);
/* Display the caret. */
ShowCaret(hwnd); break;

ビットマップからキャレットを作成するには、 CreateCaretを呼び出すときに、 ビットマップ ハンドルを指定してください。ビットマップはグラフィック アプリケーションを使って作成し、 リソース コンパイラでアプリケーションのリソースに付加しでください。それから、 LoadBitmap関数を使って、 ビットマップをロードしてハンドルを取得してください。たとえば、 上記の例のCreateCaretの行は、 次に示すビットマップ キャレットを作成するコードで置き換えることができます。

/* Load the application-defined caret resource. */
hCaret = LoadBitmap(hinst, MAKEINTRESOURCE(120));
/* Create a bitmap caret. */
CreateCaret(hwnd, hCaret, 0, 0);

また、 CreateBitmap関数やCreateDIBitmap関数を使って、 キャレット ビットマップのハンドルを取得することもできます。ビットマップについて詳しくは、 ビットマップの概要を参照してください。

CreateCaretにビットマップ ハンドルを指定すると、 高さと幅のパラメータは無視されます。キャレットのサイズは、 ビットマップから判断されます。

 

キャレットの非表示

WM_PAINTメッセージ以外のメッセージの処理中に画面を再描画するときは、 HideCaret関数を使ってキャレットを非表示にしてください。描画を終了したら、 ShowCaret関数を使ってキャレットを再表示してください。WM_PAINTメッセージを処理するときは、 システムが自動的にキャレットの非表示と再表示を行うため、 アプリケーションがキャレット表示処理を行う必要はありません。

次に示すコード例は、 WM_CHARメッセージの処理時に画面に文字を描画する場合にキャレットを非表示にする方法を示しています。

HWND hwnd, /* window handle */
HDC hdc; /* device context */
case WM_CHAR:
switch (wParam) { case 0x08: break;
case 0x09: break;
case 0x0D: break;
case 0x1B: break;
case 0x0A: break;
default:
/* Process all other characters. */
/* Hide the caret. */