リスト ボックスについて

  • [アーティクル]

リスト ボックス コントロールには、ユーザーが通常 1 つ以上の項目を選択できる単純なリストが含まれています。 リスト ボックスでは、 リスト ビュー コントロールと比較して柔軟性が制限されます。

リスト ボックス項目は、テキスト文字列、ビットマップ、またはその両方で表すことができます。 リスト ボックスが一度にすべてのリスト ボックス項目を表示するのに十分な大きさでない場合、リスト ボックスにはスクロール バーが表示されます。 ユーザーはリスト ボックス項目をスクロールし、必要に応じて選択状態を適用または削除します。 リスト ボックス項目を選択すると、通常、テキストと背景色を関連するオペレーティング システム メトリックで指定された色に変更することで、外観が変更されます。 ユーザーが項目を選択または選択解除すると、システムはリスト ボックスの親ウィンドウに通知メッセージを送信します。

ANSI アプリケーションの場合、 CP_ACP コード ページを使用して、リスト ボックス内のテキストが Unicode に変換されます。 これにより、問題が発生する可能性があります。 たとえば、Windows の Unicode 以外のリスト ボックスにアクセント付きのローマ文字が含まれると、日本語のバージョンが文字化けして表示されます。 これを修正するには、アプリケーションを Unicode としてコンパイルするか、所有者が描画したリスト ボックスを使用します。

このセクションでは、次のトピックについて説明します。

リストボックスの作成

ダイアログ ボックスでリスト ボックスを作成する最も簡単な方法は、Microsoft Visual Studio のツールボックスからダイアログ リソースにドラッグすることです。 リスト ボックスを動的に作成したり、ダイアログ ボックス以外のウィンドウにリスト ボックスを作成したりするには、 CreateWindowEx 関数を使用して、 WC_LISTBOX ウィンドウ クラスと適切な リスト ボックス スタイル を指定します。

リスト ボックスの種類とスタイル

リスト ボックスには、単一選択 (既定) と複数選択の 2 種類があります。 単一選択リスト ボックスでは、ユーザーは一度に 1 つの項目のみを選択できます。 複数選択リスト ボックスでは、ユーザーは一度に複数の項目を選択できます。 複数選択リスト ボックスを作成するには、 LBS_MULTIPLESEL または LBS_EXTENDEDSEL スタイルを指定します。

リスト ボックスの外観と操作は、 リスト ボックスのスタイル とウィンドウ スタイルによって制御されます。 これらのスタイルは、リストが並べ替えられたり、複数の列に配置されたり、アプリケーションによって描画されたりするかどうかを示します。 リスト ボックスのディメンションとスタイルは、通常、アプリケーションのリソースに含まれるダイアログ ボックス テンプレートで定義されます。

Note

これらのコントロールで視覚スタイルを使用するためには、アプリケーションにマニフェストを含め、プログラムの開始時に InitCommonControls 関数を呼び出す必要があります。 視覚スタイルの詳細については、 視覚スタイルを参照してください。 マニフェストの詳細については、 視覚スタイルを有効にするを参照してください。

リスト ボックス関数

DlgDirList 関数は 、 リスト ボックスの内容を、指定した条件セットに一致するドライブ、ディレクトリ、およびファイルの名前に置き換えます。 DlgDirSelectEx 関数は、 DlgDirList によって初期化されたリスト ボックス内の現在の選択範囲を取得します。 これらの関数を使用すると、ユーザーがファイルの場所と名前を入力しなくても、リスト ボックスからドライブ、ディレクトリ、またはファイルを選択できるようになります。

また、 GetListBoxInfo 関数は、指定したリスト ボックス内の列ごとの項目数を返します。

リスト ボックスからの通知メッセージ

リスト ボックスでイベントが発生すると、リスト ボックスは、 WM_COMMAND メッセージの形式で、所有者ウィンドウのダイアログ ボックス プロシージャに通知コードを送信します。 リストボックス通知コードは、ユーザーがリストボックス項目を選択、ダブルクリック、またはキャンセルしたとき、リストボックスがキーボードフォーカスを受けたとき、または失ったとき、およびシステムがリストボックス要求に対して十分なメモリを割り当てられないときに送信されます。 WM_COMMAND メッセージには、 wParam パラメーターの下位ワードのリスト ボックス識別子と、上位ワードの通知コードが含まれます。 lParam パラメーターには、コントロール ウィンドウ ハンドルが含まれています。

これらのメッセージを処理するためにダイアログ ボックス プロシージャは必要ありません。既定のウィンドウ プロシージャで処理されます。

アプリケーションは、次のリスト ボックス通知コードを監視し、処理する必要があります。

通知コード 説明
LBN_DBLCLK ユーザーがリスト ボックス内の項目をダブルクリックします。
LBN_ERRSPACE リスト ボックスは、要求を満たすのに十分なメモリを割り当てることができません。
LBN_KILLFOCUS リスト ボックスはキーボード フォーカスを失います。
LBN_SELCANCEL ユーザーは、リスト ボックス内の項目の選択を取り消します。
LBN_SELCHANGE リスト ボックス内の選択内容が変更されようとしています。
LBN_SETFOCUS リスト ボックスはキーボード フォーカスを受け取ります。

リスト ボックスへのメッセージ

ダイアログ ボックス プロシージャは、リスト ボックスにメッセージを送信して、リスト ボックス項目の追加、削除、確認、変更を行うことができます。 たとえば、ダイアログ ボックス プロシージャは、 LB_ADDSTRING メッセージをリスト ボックスに送信して項目を追加し、 LB_GETSEL メッセージを送信して項目が選択されているかどうかを確認できます。 その他のメッセージは、リスト ボックスのサイズ、外観、動作に関する情報を設定および取得します。 たとえば、 LB_SETHORIZONTALEXTENT メッセージは、リスト ボックスのスクロール可能な幅を設定します。 ダイアログ ボックス プロシージャは、 SendMessage または SendDlgItemMessage 関数を使用して、任意のメッセージをリスト ボックスに送信できます。

リスト ボックス項目は、リスト ボックス内の項目の位置を表す整数である インデックス によって参照されることがよくあります。 リスト ボックスの最初の項目のインデックスは 0、2 番目の項目のインデックスは 1 などです。

次の表では、定義済みのリスト ボックス プロシージャがリスト ボックス メッセージにどのように応答するかを示します。

メッセージ 回答
LB_ADDFILE DlgDirList 関数によって入力されたディレクトリ リスト ボックスにファイルを 挿入し、 挿入された項目のリスト ボックス インデックスを取得します。
LB_ADDSTRING リスト ボックスに文字列を追加し、そのインデックスを返します。
LB_DELETESTRING リスト ボックスから文字列を削除し、リスト内に残っている文字列の数を返します。
LB_DIR リスト ボックスにファイル名のリストを追加し、最後に追加したファイル名のインデックスを返します。
LB_FINDSTRING リストボックス内で、指定した文字列で始まる最初の文字列のインデックスを返します。
LB_FINDSTRINGEXACT 指定した文字列と等しいリスト ボックス内の文字列のインデックスを返します。
LB_GETANCHORINDEX マウスが最後に選択した項目のインデックスを返します。
LB_GETCARETINDEX フォーカスの四角形を持つ項目のインデックスを返します。
LB_GETCOUNT リストボックス内の項目の数を返します
LB_GETCURSEL 現在選択されている項目のインデックスを返します。
LB_GETHORIZONTALEXTENT リスト ボックスのスクロール可能な幅をピクセル単位で返します。
LB_GETITEMDATA 指定されたリスト アイテムに関連付けられた値を返します。
LB_GETITEMHEIGHT リスト ボックス内の項目の高さをピクセル単位で返します。
LB_GETITEMRECT 指定したリスト ボックス項目のクライアント座標を取得します。
LB_GETLOCALE リスト ボックスのロケールを取得します。 上位ワードには国/地域コードが含まれ、下位ワードには言語識別子が含まれます。
LB_GETSEL リスト ボックス項目の選択状態を返します。
LB_GETSELCOUNT 複数選択リスト ボックスで選択した項目の数を返します。
LB_GETSELITEMS 複数選択リスト ボックスで選択したすべての項目のインデックスの配列を作成し、選択した項目の合計数を返します。
LB_GETTEXT 指定した項目に関連付けられている文字列と文字列の長さを取得します。
LB_GETTEXTLEN 指定した項目に関連付けられている文字列の長さを文字数で返します。
LB_GETTOPINDEX リスト ボックスに最初に表示されるアイテムのインデックスを返します。
LB_INITSTORAGE 指定した数の項目とそれに関連付けられている文字列にメモリを割り当てます。
LB_INSERTSTRING リスト ボックス内の指定したインデックス位置に文字列を挿入します。
LB_ITEMFROMPOINT リスト ボックス内の指定された点に最も近い項目の0から始まるインデックスを取得します。
LB_RESETCONTENT リスト ボックスからすべてのアイテムを削除します。
LB_SELECTSTRING 指定したプレフィックスと一致する最初の文字列を選択します。
LB_SELITEMRANGE リスト ボックス内の指定した項目範囲を選択します。
LB_SELITEMRANGEEX 範囲内の最初の項目のインデックスが範囲内の最後の項目のインデックスより小さい場合は、指定した項目範囲を選択します。 最初の項目のインデックスが最後の項目より大きい場合は、範囲内の選択範囲を取り消します。
LB_SETANCHORINDEX マウスで最後に選択した項目を、指定した項目に設定します。
LB_SETCARETINDEX フォーカスの四角形を指定したリスト ボックス項目に設定します。
LB_SETCOLUMNWIDTH リスト ボックス内のすべての列の幅をピクセル単位で設定します。
LB_SETCOUNT リスト ボックス内のアイテム数を設定します。
LB_SETCURSEL 指定したリスト ボックス項目を選択します。
LB_SETHORIZONTALEXTENT リスト ボックスのスクロール可能な幅をピクセル単位で設定します。
LB_SETITEMDATA 値をリスト ボックス項目に関連付けます。
LB_SETITEMHEIGHT リスト ボックス内の項目の高さをピクセル単位で設定します。
LB_SETLOCALE リスト ボックスのロケールを設定し、前のロケール識別子を返します。
LB_SETSEL 複数選択リスト ボックス内の項目を選択します。
LB_SETTABSTOPS タブ位置を、指定した配列で指定されたタブ位置に設定します。
LB_SETTOPINDEX 指定された項目が表示範囲の一番上になるように、リストボックスをスクロールします。

既定のウィンドウ メッセージ処理

定義済みのリスト ボックス ウィンドウ クラスのウィンドウ プロシージャは、リスト ボックスが処理しないすべてのメッセージに対して既定の処理を実行します。 リストボックス プロシージャがいずれかのメッセージについて FALSE を返すと、定義済みのウィンドウ プロシージャがメッセージをチェックし、次の表に示した既定のアクションを実行します。

メッセージ 既定の動作
WM_CHAR ユーザーが入力した文字で始まる最初の項目に選択範囲を移動します。 リスト ボックスに LBS_OWNERDRAW スタイルがある場合、アクションは発生しません。 短い間隔で入力された複数の文字がグループとして扱われ、その一連の文字で始まる最初の項目が選択されます。
WM_CREATE 空のリスト ボックスを作成します。
WM_DESTROY リスト ボックスを破棄し、使用するすべてのリソースを解放します。
ダイアログ ボックス プロシージャまたは親ウィンドウ プロセスにメッセージを渡します。
WM_ENABLE コントロールが表示されている場合は、文字列を灰色で塗りつぶすことができるように四角形を無効にします。
WM_ERASEBKGND リスト ボックスの背景を消去します。 リスト ボックスに LBS_OWNERDRAW スタイルがある場合、背景は消去されません。
WM_GETDLGCODE DLGC_WANTARROWS | を返します。DLGC_WANTCHARS、既定のリスト ボックス プロシージャが方向キーと WM_CHAR メッセージを処理することを示します。
WM_GETFONT リスト ボックスの現在のフォントへのハンドルを返します。
WM_HSCROLL リスト ボックスを水平方向にスクロールします。
WM_KEYDOWN スクロール用の仮想キーを処理します。 仮想キーは、キャレットを移動する項目のインデックスです。 選択内容は変更されません。
WM_KILLFOCUS キャレットをオフにして破棄します。 LBN_KILLFOCUS 通知コードをリスト ボックスの所有者に送信します。
WM_LBUTTONDBLCLK リスト ボックスのクライアント領域でマウスを追跡します。 これにより、マウス ボタンがリスト ボックス クライアント領域の外側で離された場合に、ユーザーは選択をキャンセルできます。
WM_LBUTTONDOWN リスト ボックスのクライアント領域でマウスを追跡します。 これにより、マウス ボタンがリスト ボックス クライアント領域の外側で離された場合に、ユーザーは選択をキャンセルできます。
WM_LBUTTONUP リスト ボックスのクライアント領域でマウスを追跡します。 これにより、マウス ボタンがリスト ボックス クライアント領域の外側で離された場合に、ユーザーは選択をキャンセルできます。
WM_MOUSEMOVE リスト ボックスのクライアント領域でマウスを追跡します。 これにより、マウス ボタンがリスト ボックス クライアント領域の外側で離された場合に、ユーザーは選択をキャンセルできます。
WM_PAINT デバイス コンテキスト (DC) のリスト ボックス ハンドルを使用して、サブクラス化されたペイント操作を実行します。
WM_SETFOCUS キャレットをオンにし、 LBN_SETFOCUS 通知コードをリスト ボックスの所有者に送信します。
WM_SETFONT リスト ボックスの新しいフォントを設定します。
WM_SETREDRAW wParam の値に基づいて再描画フラグを設定またはクリアします。
WM_SIZE リスト ボックスのサイズを整数の項目数に変更します。
WM_VSCROLL リスト ボックスを垂直方向にスクロールします。

定義済みのリスト ボックス プロシージャは、既定の処理を行えるように、その他のすべてのメッセージを DefWindowProc 関数に渡します。

所有者描画リスト ボックス

アプリケーションは、リスト アイテムの描画を担当する 所有者描画 リスト ボックスを作成できます。 所有者が描画したリスト ボックス (その 所有者) の親ウィンドウまたはダイアログ ボックスは、リスト ボックスの一部を描画する必要があるときに WM_DRAWITEM メッセージを受信します。 所有者が描画したリスト ボックスは、テキスト文字列以外の情報を一覧表示できます。

所有者描画リスト ボックスの所有者は、 WM_DRAWITEM メッセージを処理する必要があります。 このメッセージは、リスト ボックスの一部を再描画する必要があるときに送信されます。 リスト ボックスに指定されたスタイルによっては、所有者が他のメッセージを処理する必要がある場合があります。

アプリケーションでは、 LBS_OWNERDRAWFIXED または LBS_OWNERDRAWVARIABLE スタイルを指定して、所有者描画リスト ボックスを作成できます。 リスト ボックス内のすべてのリスト アイテムが文字列やアイコンなど、同じ高さである場合、アプリケーションは LBS_OWNERDRAWFIXED スタイルを使用できます。 リスト項目の高さが異なる場合 (サイズの異なるビットマップなど)、アプリケーションは LBS_OWNERDRAWVARIABLE スタイルを使用できます。

所有者描画リスト ボックスの所有者は、 WM_MEASUREITEM メッセージを処理して、リスト アイテムのディメンションを指定できます。 アプリケーションが LBS_OWNERDRAWFIXED スタイルを使用してリスト ボックスを作成した場合、システムは WM_MEASUREITEM メッセージを 1 回だけ送信します。 所有者が指定したディメンションは、すべてのリスト アイテムに使用されます。 LBS_OWNERDRAWVARIABLE スタイルが使用されている場合、リスト ボックスに追加された各リスト アイテムに対して WM_MEASUREITEM メッセージが送信されます。 所有者は、 LB_GETITEMHEIGHT メッセージと LB_SETITEMHEIGHT メッセージをそれぞれ使用して、いつでもリスト アイテムの高さを決定または設定できます。

所有者が描画したリスト ボックスに表示される情報にテキストが含まれている場合、アプリケーションは LBS_HASSTRINGS スタイルを指定することで、各リスト アイテムのテキストを追跡できます。 LBS_SORT スタイルのリスト ボックスは、このテキストに基づいて並べ替えられます。 リスト ボックスがソートされているが、 LBS_HASSTRINGS スタイルではない場合、所有者は WM_COMPAREITEM メッセージを処理する必要があります。

所有者が描画したリスト ボックスでは、所有者はテキスト以外またはテキストに加えて情報を含むリスト アイテムを追跡する必要があります。 これを行う便利な方法の 1 つは、 LB_SETITEMDATA メッセージを使用して、情報へのハンドルを項目データとして保存することです。 リスト ボックス内のアイテムに関連付けられているデータ オブジェクトを解放するために、所有者は WM_DELETEITEM メッセージを処理できます。

所有者描画リスト ボックスの例については、 所有者描画リスト ボックスを作成する方法 を参照してください。

リスト ボックスをドラッグする

ドラッグ リスト ボックスは、ユーザーが項目をある位置から別の位置にドラッグできるようにする特殊な種類のリスト ボックスです。 アプリケーションでは、ドラッグ リスト ボックスを使用して、特定のシーケンス内の文字列を表示し、ユーザーが項目を位置にドラッグしてシーケンスを変更できるようにします。

ドラッグ リスト ボックスの作成

ドラッグ リスト ボックスのウィンドウ スタイルは同じで、標準のリスト ボックスと同じメッセージを処理します。 ドラッグ リスト ボックスを作成するには、最初に標準のリスト ボックスを作成してから、 MakeDragList 関数を呼び出します。 ダイアログ ボックス内のリスト ボックスをドラッグ リスト ボックスに変換するには、WM_INITDIALOG メッセージの処理時に MakeDragList を呼び出します。

リスト ボックス メッセージをドラッグする

ドラッグ リスト ボックスは、ドラッグ リスト メッセージを送信することで、ドラッグ イベントを親ウィンドウに通知します。 親ウィンドウでドラッグ リスト メッセージを処理する必要があります。

MakeDragList 関数が呼び出されると、ドラッグ リスト ボックスによってこのメッセージが登録されます。 ドラッグ リスト メッセージのメッセージ識別子 (数値) を取得するには、 RegisterWindowMessage 関数を呼び出し、DRAGLISTMSGSTRING 値を指定します。

ドラッグ リスト メッセージの wParam パラメーターは、ドラッグ リスト ボックスのコントロール識別子です。 lParam パラメーターは DRAGLISTINFO 構造体のアドレスです。この構造体には、ドラッグ イベントとその他の情報の通知コードが含まれます。 メッセージの戻り値は通知によって異なります。

リスト ボックスの通知コードをドラッグする

ドラッグリスト通知コードは、ドラッグリストメッセージに含まれる DRAGLISTINFO 構造体の uNotification メンバによって識別され、 DL_BEGINDRAG、 DL_DRAGGING、 DL_CANCELDRAG、 DL_DROPPED のいずれかになります。

DL_BEGINDRAG 通知コードは、カーソルがリスト アイテム上にあり、ユーザーがマウスの左ボタンをクリックしたときに送信されます。 親ウィンドウは TRUE を返してドラッグ操作を開始するか、 FALSE を返してドラッグ操作を禁止することができます。 この方法では、親ウィンドウで一部のリスト 項目のドラッグを有効にし、他のリスト アイテムに対してドラッグを無効にすることができます。 LBItemFromPt 関数を使用して、指定した場所にあるリスト 項目を確認できます。

ドラッグが有効な場合、 DL_DRAGGING 通知コードは、マウスが移動されるたびに送信されるか、マウスが移動されていない場合は一定の間隔で送信されます。 親ウィンドウでは、最初に LBItemFromPt を使用してカーソルの下のリスト アイテムを特定し、次に DrawInsert 関数を使用して挿入アイコンを描画する必要があります。 LBItemFromPt の bAutoScroll パラメーターに TRUE を指定すると、カーソルがクライアント領域の上または下にある場合に、リスト ボックスを 1 行スクロールさせることができます。 この通知に対して返される値は、ドラッグ リスト ボックスで設定する必要があるマウス カーソルの種類を指定します。

ユーザーが マウスの右ボタンをクリックするか ESC キーを押してドラッグ操作をキャンセルすると、 DL_CANCELDRAG 通知コードが送信されます。 DL_DROPPED 通知コードは、カーソルがリスト アイテムの上にない場合でも、マウスの左ボタンを離してドラッグ操作を完了した場合に送信されます。 ドラッグ リスト ボックスは、いずれかの通知を送信する前にマウス キャプチャを解放します。 これら 2 つの通知の戻り値は無視されます。 リストのドラッグ