[バージョン情報] ダイアログ ボックス

  • [アーティクル]

ダイアログ ボックスの作成と管理に役立つ多くの関数、メッセージ、および定義済みのコントロールがあるため、アプリケーションのユーザー インターフェイスを簡単に開発できます。 この概要では、ダイアログ ボックスの機能とメッセージについて説明し、それらを使用してダイアログ ボックスを作成および使用する方法について説明します。

この概要には、次のトピックが含まれます。

一般的なダイアログ ボックスの詳細については、「 共通ダイアログ ボックス ライブラリ」を参照してください。

ダイアログ ボックスを使用するタイミング

ほとんどのアプリケーションでは、ダイアログ ボックスを使用して、ユーザー入力を必要とするメニュー項目に関する追加情報の入力を求めます。 ダイアログ ボックスの使用は、アプリケーションが入力を取得するための唯一の推奨される方法です。 たとえば、一般的な [開く ] メニュー項目では、開くファイルの名前が必要であるため、アプリケーションではダイアログ ボックスを使用してユーザーに名前の入力を求める必要があります。 このような場合、ユーザーがメニュー項目をクリックすると、アプリケーションによってダイアログ ボックスが作成され、ユーザーが情報を提供した直後にダイアログ ボックスが破棄されます。

多くのアプリケーションでは、ユーザーが別のウィンドウで作業している間に、ダイアログ ボックスを使用して情報やオプションを表示することもできます。 たとえば、ワープロ アプリケーションでは、多くの場合、テキスト検索オプションを含むダイアログ ボックスが使用されます。 アプリケーションがテキストを検索している間、ダイアログ ボックスは画面に残ります。 その後、ユーザーはダイアログ ボックスに戻り、同じ単語をもう一度検索できます。または、ユーザーはダイアログ ボックスのエントリを変更し、新しい単語を検索できます。 この方法でダイアログ ボックスを使用するアプリケーションは、通常、ユーザーがメニュー項目をクリックし、アプリケーションが実行されている限り、またはユーザーがダイアログ ボックスを明示的に閉じるまで表示し続けると、ダイアログ ボックスを作成します。

アプリケーションでダイアログ ボックスを使用するさまざまな方法をサポートするために、モーダルとモードレスの 2 種類のダイアログ ボックスがあります。 モーダル ダイアログ ボックスでは、アプリケーションの続行を許可する前に、ユーザーが情報を提供するか、ダイアログ ボックスをキャンセルする必要があります。 アプリケーションでは、モーダル ダイアログ ボックスを、続行する前に追加情報を必要とするメニュー項目と組み合わせて使用します。 モードレス ダイアログ ボックスを使用すると、ユーザーはダイアログ ボックスを閉じずに情報を提供し、前のタスクに戻ることができます。 モーダル ダイアログ ボックスは、作成、タスクの実行、および単一の関数の呼び出しによって破棄されるため、モードレス ダイアログ ボックスよりも管理が簡単です。

モーダル ダイアログ ボックスまたはモードレス ダイアログ ボックスを作成するには、ダイアログ ボックスのスタイルとコンテンツを記述するダイアログ ボックス テンプレートをアプリケーションで指定する必要があります。アプリケーションでは、タスクを実行するためのダイアログ ボックス プロシージャも指定する必要があります。 ダイアログ ボックス テンプレートは、ダイアログ ボックスとそのダイアログ ボックスに含まれるコントロールのバイナリ説明です。 開発者は、このテンプレートをリソースとして作成して、アプリケーションの実行可能ファイルから読み込んだり、アプリケーションの実行中にメモリに作成したりできます。 ダイアログ ボックス プロシージャは、ダイアログ ボックスまたはダイアログ ボックスが実行するタスクの入力がある場合にシステムが呼び出すアプリケーション定義のコールバック関数です。ダイアログ ボックス プロシージャはウィンドウ プロシージャに似ていますが、同じ責任はありません。

通常、アプリケーションは DialogBox 関数または CreateDialog 関数を使用してダイアログ ボックスを作成します。 DialogBox は モーダル ダイアログ ボックスを作成します。 CreateDialog では 、モードレス ダイアログ ボックスが作成されます。 これら 2 つの関数は、アプリケーションの実行可能ファイルからダイアログ ボックス テンプレートを読み込み、テンプレートの仕様に一致するポップアップ ウィンドウを作成します。 メモリ内のテンプレートを使用してダイアログ ボックスを作成する他の関数があります。ダイアログ ボックスが作成されると、ダイアログ ボックス プロシージャに追加情報が渡されます。

ダイアログ ボックスは、通常、定義済みの排他ウィンドウ クラスに属します。 システムは、このウィンドウ クラスとそれに対応するウィンドウ プロシージャをモーダル ダイアログ ボックスとモードレス ダイアログ ボックスの両方に使用します。 関数が呼び出されると、ダイアログ ボックスのウィンドウとダイアログ ボックス内のコントロールのウィンドウが作成され、選択したメッセージがダイアログ ボックス プロシージャに送信されます。 ダイアログ ボックスが表示されている間、定義済みのウィンドウ プロシージャはすべてのメッセージを管理し、一部のメッセージを処理し、他のメッセージをダイアログ ボックス プロシージャに渡して、プロシージャがタスクを実行できるようにします。 アプリケーションは、定義済みのウィンドウ クラスまたはウィンドウ プロシージャに直接アクセスすることはできませんが、ダイアログ ボックス テンプレートとダイアログ ボックス プロシージャを使用して、ダイアログ ボックスのスタイルと動作を変更できます。

ダイアログ ボックスの [所有者] ウィンドウ

ほとんどのダイアログ ボックスには、所有者ウィンドウ (またはより単純に所有者) があります。 ダイアログ ボックスを作成するときに、アプリケーションは所有者のウィンドウ ハンドルを指定して所有者を設定します。 ダイアログ ボックスが常に所有者の上に配置されるように、所有者を使用してダイアログ ボックスの位置を Z オーダーで決定します。 また、システムは所有者のウィンドウ プロシージャにメッセージを送信し、ダイアログ ボックスのイベントを通知できます。

システムは、その所有者が非表示または破棄されるたびに、ダイアログ ボックスを自動的に非表示または破棄します。 つまり、ダイアログ ボックス プロシージャでは、所有者ウィンドウの状態に対する変更を検出するために特別な処理は必要ありません。

一般的なダイアログ ボックスはメニュー項目と組み合わせて使用されるため、所有者ウィンドウは通常、メニューを含むウィンドウです。 所有者がいないダイアログ ボックスを作成することはできますが、推奨されません。 たとえば、モーダル ダイアログ ボックスに所有者がいない場合、システムはアプリケーションの他のウィンドウを無効にせず、ユーザーが他のウィンドウで引き続き作業を実行できるようにして、モーダル ダイアログ ボックスの目的を無効にします。

モードレス ダイアログ ボックスに所有者がいない場合、アプリケーション内の他のウィンドウが非表示または破棄されたときに、システムはダイアログ ボックスを非表示にしたり破棄したりしません。 これはモードレス ダイアログ ボックスの目的を損ないませんが、ダイアログ ボックスが適切な時間に非表示になり破棄されるように、アプリケーションで特別な処理を実行する必要があります。

メッセージ ボックス

メッセージ ボックスは、アプリケーションがメッセージを表示し、単純な入力を求めるために使用できる特別なダイアログ ボックスです。 通常、メッセージ ボックスにはテキスト メッセージと 1 つ以上のボタンが含まれます。 アプリケーションは、MessageBox または MessageBoxEx 関数を使用してメッセージ ボックスを作成し、テキストと表示するボタンの数と種類を指定します。 現在、MessageBox と MessageBoxEx の動作に違いはありません。

メッセージ ボックスはダイアログ ボックスですが、システムはメッセージ ボックスの作成と管理を完全に制御します。 これは、アプリケーションがダイアログ ボックス テンプレートとダイアログ ボックス プロシージャを提供しないことを意味します。 メッセージ ボックスに指定されたテキストとボタンに基づいて独自のテンプレートが作成され、独自のダイアログ ボックス プロシージャが提供されます。

メッセージ ボックスはモーダル ダイアログ ボックスであり、 DialogBox で使用されるのと同じ内部関数を使用して作成されます。 MessageBox または MessageBoxEx を呼び出すときにアプリケーションで所有者ウィンドウが指定されている場合、システムは所有者を無効にします。 また、アプリケーションは、ダイアログ ボックスの作成時に MB_TASKMODAL 値を指定することで、現在のスレッドに属するすべての最上位ウィンドウを無効にするようにシステムに指示することもできます。

システムは、モーダル ダイアログ ボックスの作成時と同様に、 WM_CANCELMODE や WM_ENABLEなどのメッセージを所有者に送信できます。 所有者ウィンドウは、これらのメッセージによって要求されたすべてのアクションを実行する必要があります。

モーダル ダイアログ ボックスは、ウィンドウ メニュー、タイトル バー、太い境界線を含むポップアップ ウィンドウである必要があります。つまり、ダイアログ ボックス テンプレートでは、 WS_POPUP、 WS_SYSMENU、 WS_CAPTION、 およびDS_MODALFRAME スタイルを指定する必要があります。 アプリケーションは WS_VISIBLE スタイルを指定できますが、ダイアログ ボックス テンプレートで WS_VISIBLE スタイルが指定されているかどうかに関係なく、常にモーダル ダイアログ ボックスが表示されます。 アプリケーションでは、 WS_CHILD スタイルを持つモーダル ダイアログ ボックスを作成しないでください。 このスタイルのモーダル ダイアログ ボックスはそれ自体を無効にし、後続の入力がアプリケーションに到達するのを防ぎます。

アプリケーションは、DialogBox または DialogBoxIndirect 関数を使用してモーダル ダイアログ ボックスを作成します。 DialogBox には、ダイアログ ボックス テンプレートを含むリソースの名前または識別子が必要です。 DialogBoxIndirect には、ダイアログ ボックス テンプレートを含むメモリ オブジェクトへのハンドルが必要です。 DialogBoxParam 関数と DialogBoxIndirectParam 関数もモーダル ダイアログ ボックスを作成します。これらは前述の関数と同じですが、ダイアログ ボックスの作成時に指定したパラメーターをダイアログ ボックス プロシージャに渡します。

モーダル ダイアログ ボックスを作成すると、システムによってアクティブ ウィンドウになります。 ダイアログ ボックス プロシージャが EndDialog 関数を呼び出すか、システムが別のアプリケーションでウィンドウをアクティブ化するまで、ダイアログ ボックスはアクティブなままになります。 モーダル ダイアログ ボックスが破棄されるまで、ユーザーもアプリケーションも所有者ウィンドウをアクティブにすることはできません。

所有者ウィンドウがまだ無効でない場合は、モーダル ダイアログ ボックスを作成するときに、ウィンドウとそのウィンドウに属する子ウィンドウが自動的に無効になります。 ダイアログ ボックスが破棄されるまで、所有者ウィンドウは無効のままです。 ダイアログ ボックス プロシージャは、いつでも所有者ウィンドウを有効にする可能性がありますが、所有者を有効にするとモーダル ダイアログ ボックスの目的が無効になり、推奨されません。 ダイアログ ボックス プロシージャが破棄されると、モーダル ダイアログ ボックスによって所有者が無効にされた場合にのみ、システムによって所有者ウィンドウが再度有効になります。

モーダル ダイアログ ボックスが作成されると、現在マウス入力をキャプチャしているウィンドウ (存在する場合) に WM_CANCELMODE メッセージが送信されます。 このメッセージを受信するアプリケーションは、ユーザーがモーダル ダイアログ ボックスでマウスを移動できるように、マウス キャプチャを解放する必要があります。 システムは所有者ウィンドウを無効にするため、所有者がこのメッセージの受信時にマウスの解放に失敗すると、すべてのマウス入力が失われます。

モーダル ダイアログ ボックスのメッセージを処理するために、システムは独自のメッセージ ループを開始し、アプリケーション全体のメッセージ キューを一時的に制御します。 ダイアログ ボックスに対して明示的に指定されていないメッセージを取得すると、メッセージは適切なウィンドウにディスパッチされます。 WM_QUIT メッセージを取得する場合は、アプリケーションのメッセージ キューにメッセージをポストバックして、アプリケーションのメイン メッセージ ループが最終的にメッセージを取得できるようにします。

システムは、アプリケーション メッセージ キューが空のときは常に、 WM_ENTERIDLE メッセージを所有者ウィンドウに送信します。 アプリケーションは、このメッセージを使用して、ダイアログ ボックスが画面に残っている間にバックグラウンド タスクを実行できます。 アプリケーションでこの方法でメッセージを使用する場合、モーダル ダイアログ ボックスが任意のユーザー入力を受け取ることができるように、アプリケーションは頻繁に制御 ( PeekMessage 関数を使用するなど) を生成する必要があります。 モーダル ダイアログ ボックスが WM_ENTERIDLE メッセージを送信できないようにするために、アプリケーションはダイアログ ボックスの作成時にDS_NOIDLEMSGスタイルを指定できます。

アプリケーションは 、EndDialog 関数を使用してモーダル ダイアログ ボックスを破棄します。 ほとんどの場合、ダイアログ ボックスのプロシージャは、ユーザーがダイアログ ボックスのウィンドウ メニューから [閉じる] をクリックするか、ダイアログ ボックスの [OK] または [キャンセル] ボタンをクリックしたときに EndDialog を呼び出します。 ダイアログ ボックスは、EndDialog 関数を呼び出すときに値を指定することで、DialogBox 関数 (またはその他の作成関数) を使用して値を返すことができます。 ダイアログ ボックスを破棄すると、この値が返されます。 ほとんどのアプリケーションでは、この戻り値を使用して、ダイアログ ボックスがタスクを正常に完了したか、ユーザーによって取り消されたかを判断します。 ダイアログ ボックス プロシージャが EndDialog 関数を呼び出すまで、ダイアログ ボックスを作成する関数からコントロールが返されることはありません。

モードレス ダイアログ ボックス

モードレス ダイアログ ボックスは、ウィンドウ メニュー、タイトル バー、細い境界線を含むポップアップ ウィンドウである必要があります。つまり、ダイアログ ボックス テンプレートでは、 WS_POPUP、 WS_CAPTION、 WS_BORDER、 およびWS_SYSMENU スタイルを指定する必要があります。 テンプレートでWS_VISIBLEスタイルが指定されていない限り、ダイアログ ボックスは自動的 に 表示されません。

アプリケーションは、 CreateDialog または CreateDialogIndirect 関数を使用してモードレス ダイアログ ボックス を作成 します。 CreateDialog には、ダイアログ ボックス テンプレートを含むリソースの名前または識別子が必要です。 CreateDialogIndirect には、ダイアログ ボックス テンプレートを含むメモリ オブジェクトへのハンドルが必要です。 CreateDialogParam とCreateDialogIndirectParam という他の 2 つの関数も、モードレス ダイアログ ボックスを作成します。ダイアログ ボックスの作成時に、指定したパラメーターをダイアログ ボックス プロシージャに渡します。

CreateDialog やその他の作成関数は、ダイアログ ボックスにウィンドウ ハンドルを返します。 アプリケーションとダイアログ ボックス プロシージャでは、このハンドルを使用してダイアログ ボックスを管理できます。 たとえば、ダイアログ ボックス テンプレートで WS_VISIBLE が指定されていない場合、ウィンドウ ハンドルを ShowWindow 関数に渡すことで、アプリケーションでダイアログ ボックスを表示できます。

モードレス ダイアログ ボックスでは、所有者ウィンドウを無効にしたり、メッセージを送信したりすることはありません。 ダイアログ ボックスを作成すると、システムによってアクティブ ウィンドウになりますが、ユーザーまたはアプリケーションは、いつでもアクティブ ウィンドウを変更できます。 ダイアログ ボックスが非アクティブになった場合、所有者ウィンドウがアクティブな場合でも、Z オーダーの所有者ウィンドウの上に残ります。

アプリケーションは、入力メッセージを取得してダイアログ ボックスにディスパッチする役割を担います。 ほとんどのアプリケーションでは、メイン メッセージ ループを使用します。 ただし、ユーザーがキーボードを使用してコントロールに移動して選択できるようにするには、アプリケーションで IsDialogMessage 関数を呼び出す必要があります。 この関数の詳細については、「 ダイアログ ボックス キーボード インターフェイス」を参照してください。

モードレス ダイアログ ボックスは、モーダル ダイアログ ボックスとしてアプリケーションに値を返すことはできませんが、ダイアログ ボックス プロシージャは SendMessage 関数を使用して所有者ウィンドウに情報を送信できます。

アプリケーションは、終了する前にすべてのモードレス ダイアログ ボックスを破棄する必要があります。 DestroyWindow 関数を使用すると、モードレス ダイアログ ボックスを破棄できます。 ほとんどの場合、ダイアログ ボックス プロシージャは、ユーザー入力に応じて DestroyWindow を呼び出します ([ キャンセル ] ボタンをクリックするなど)。 ユーザーがこの方法でダイアログ ボックスを閉じなかった場合、アプリケーションは DestroyWindow を呼び出す必要があります。

DestroyWindow はダイアログ ボックスのウィンドウ ハンドルを無効にするため、ハンドルを使用する関数の後続の呼び出しではエラー値が返されます。 エラーを防ぐために、ダイアログ ボックス プロシージャは、ダイアログ ボックスが破棄されたことを所有者に通知する必要があります。 多くのアプリケーションでは、ダイアログ ボックスへのハンドルを含むグローバル変数が保持されています。 ダイアログ ボックス プロシージャがダイアログ ボックスを破棄すると、グローバル変数も NULL に設定され、ダイアログ ボックスが無効になっていることを示します。

ダイアログ ボックス プロシージャは、モードレス ダイアログ ボックスを破棄するために EndDialog 関数を呼び出してはなりません。

ダイアログ ボックス テンプレート

ダイアログ ボックス テンプレートは、ダイアログ ボックスの高さ、幅、スタイル、およびダイアログ ボックスに含まれるコントロールを定義するバイナリ データです。 ダイアログ ボックスを作成するには、アプリケーションの実行可能ファイル内のリソースからダイアログ ボックス テンプレートを読み込むか、アプリケーションによってグローバル メモリに渡されたテンプレートを使用します。 どちらの場合も、ダイアログ ボックスを作成するときに、アプリケーションでテンプレートを指定する必要があります。

開発者は、リソース コンパイラまたはダイアログ ボックス エディターを使用してテンプレート リソースを作成します。 リソース コンパイラはテキストの説明をバイナリ リソースに変換し、ダイアログ ボックス エディターは対話形式で構築されたダイアログ ボックスをバイナリ リソースとして保存します。

注意

テンプレート リソースを作成してアプリケーションの実行可能ファイルに追加する方法については、この概要の範囲外です。 テンプレート リソースの作成と実行可能ファイルへの追加の詳細については、アプリケーション開発ツールに付属のドキュメントを参照してください。

 

テンプレート リソースを使用せずにダイアログ ボックスを作成するには、メモリ内にテンプレートを作成し、 CreateDialogIndirectParam 関数または DialogBoxIndirectParam 関数、または CreateDialogIndirect マクロまたは DialogBoxIndirect マクロに渡す必要があります。

メモリ内のダイアログ ボックス テンプレートは、ダイアログ ボックスを記述するヘッダーの後に、ダイアログ ボックス内の各コントロールを記述する 1 つ以上の追加のデータ ブロックで構成されます。 テンプレートでは、標準形式または拡張形式のいずれかを使用できます。 標準テンプレートでは、ヘッダーは DLGTEMPLATE 構造体とそれに続く追加の可変長配列です。各コントロールのデータは 、DLGITEMTEMPLATE 構造体の後に追加の可変長配列で構成されます。 拡張ダイアログ ボックス テンプレートでは、ヘッダーは DLGTEMPLATEEX 形式を使用し、コントロール定義では DLGITEMTEMPLATEEX 形式を使用します。

グローバル メモリ オブジェクトを割り当て、標準または拡張ヘッダーとコントロール定義で埋めることで、メモリ テンプレートを作成できます。 メモリ テンプレートは、フォームとコンテンツでテンプレート リソースと同じです。 メモリ テンプレートを使用する多くのアプリケーションでは、最初に LoadResource 関数を使用してテンプレート リソースをメモリに読み込み、読み込まれたリソースを変更して新しいメモリ テンプレートを作成します。 メモリ内にダイアログ ボックス テンプレートを作成する方法の詳細については、「メモリ 内のテンプレート」を参照してください。

次のセクションでは、ダイアログ ボックス テンプレートで使用されるスタイル、測定値、およびその他の値について説明します。

ダイアログ ボックステンプレートのスタイル

すべてのダイアログ ボックス テンプレートは、ダイアログ ボックスの外観と機能を定義するスタイル値の組み合わせを指定します。 スタイル値には、 WS_POPUP や WS_SYSMENUなどのウィンドウ スタイルと、DS_MODALFRAMEなどのダイアログ ボックス スタイル を指定できます。 テンプレートのスタイルの数と種類は、ダイアログ ボックスの種類と目的によって異なります。 値の一覧については、「 ダイアログ ボックスのスタイル」を参照してください。

システムは、ダイアログ ボックスの作成時に、テンプレートで指定されたすべてのウィンドウ スタイルを CreateWindowEx 関数に渡します。 指定したダイアログ ボックスのスタイルに応じて、1 つ以上の拡張スタイルが渡される場合があります。 たとえば、テンプレートが DS_MODALFRAMEを指定すると、ダイアログ ボックスの作成時に WS_EX_DLGMODALFRAME が使用されます。

ほとんどのダイアログ ボックスは、ウィンドウ メニューとタイトル バーがあるポップアップ ウィンドウです。 したがって、一般的なテンプレートでは、 WS_POPUP、 WS_SYSMENU、 およびWS_CAPTION スタイルを指定します。 また、このテンプレートでは、モードレス ダイアログ ボックス のWS_BORDER 、モーダル ダイアログ ボックス のDS_MODALFRAME など、罫線のスタイルも指定します。 テンプレートは、ダイアログ ボックスではなくカスタマイズされたウィンドウを作成する場合、ポップアップ以外のウィンドウの種類 ( WS_OVERLAPPED など) を指定できます。

WS_VISIBLE スタイルが指定されているかどうかに関係なく、モーダル ダイアログ ボックスが常 に 表示されます。 モードレス ダイアログ ボックスのテンプレートで WS_VISIBLE スタイルを指定すると、ダイアログ ボックスの作成時に自動的に表示されます。 それ以外の場合、アプリケーションは ShowWindow 関数を使用してダイアログ ボックスを表示します。

ダイアログ ボックスの測定値

すべてのダイアログ ボックス テンプレートには、ダイアログ ボックスの位置、幅、高さ、およびそれに含まれるコントロールを指定する測定値が含まれています。 これらの測定値はデバイスに依存しないため、アプリケーションは 1 つのテンプレートを使用して、すべての種類のディスプレイ デバイスに対して同じダイアログ ボックスを作成できます。 これにより、画面間で解像度と縦横比が異なるにもかかわらず、すべての画面でダイアログ ボックスの比率と外観が同じになります。

ダイアログ ボックス テンプレートの測定値は、ダイアログ テンプレート単位で指定されます。 ダイアログ テンプレート単位から画面単位 (ピクセル) に測定を変換するには、ダイアログ ボックスで使用されるフォントを考慮し、ダイアログ テンプレート単位の四角形をピクセルに正しく変換する MapDialogRect 関数を使用します。 システム フォントを使用するダイアログ ボックスでは、 GetDialogBaseUnits 関数を使用して変換計算を自分で実行できますが、 MapDialogRect の方が簡単です。

テンプレートでは、ダイアログ ボックスの左上隅の初期座標を指定する必要があります。 通常、座標は所有者ウィンドウのクライアント領域の左上隅を基準にしています。 テンプレートでDS_ABSALIGNスタイルが指定されている場合、またはダイアログ ボックスに所有者がいない場合、位置は画面の左上隅からの相対位置になります。 ダイアログ ボックスの作成時にこの初期位置が設定されますが、アプリケーションはダイアログ ボックスを表示する前に位置を調整できます。 たとえば、アプリケーションでは、所有者ウィンドウのディメンションを取得し、所有者ウィンドウのダイアログ ボックスを中央に配置する新しい位置を計算し、 SetWindowPos 関数を使用して位置を設定できます。

テンプレートでは、画面の幅と高さを超えないダイアログ ボックスの幅と高さを指定し、すべてのコントロールがダイアログ ボックスのクライアント領域内にあることを確認する必要があります。 システムではダイアログ ボックスを任意のサイズにできますが、小さすぎるか大きすぎるダイアログ ボックスを作成すると、ユーザーが入力を提供できず、ダイアログ ボックスの目的が無効になる可能性があります。 多くのアプリケーションでは、多数のコントロールがある場合に複数のダイアログ ボックスを使用します。 このような場合、通常、最初のダイアログ ボックスには、ユーザーが次のダイアログ ボックスを表示するために選択できる 1 つ以上のボタンが含まれています。

ダイアログ ボックス コントロール

テンプレートは、ダイアログ ボックスの各コントロールの位置、幅、高さ、スタイル、識別子、ウィンドウ クラスを指定します。 システムは、このデータを CreateWindowEx 関数に渡すことによって、各コントロールを作成します。 コントロールは、テンプレートで指定された順序で作成されます。 テンプレートでは、ダイアログ ボックスに関連付けられているタスクを完了するために必要な入力をユーザーが入力できるように、コントロールの適切な数、種類、順序を指定する必要があります。

各コントロールについて、テンプレートはコントロールの外観と操作を定義するスタイル値を指定します。 すべてのコントロールは子ウィンドウであるため、 WS_CHILD スタイルが必要です。 ダイアログ ボックスを表示するときにコントロールが表示されるようにするには、各コントロールにも WS_VISIBLE スタイルが必要です。 その他の一般的に使用されるウィンドウ スタイルは、 オプションの罫線を持つコントロール、ダイアログ ボックスの作成時に無効にする必要があるコントロールの WS_DISABLED 、キーボードを使用してアクセスできるコントロール のWS_TABSTOP と WS_GROUP にWS_BORDERされます。 WS_TABSTOPとWS_GROUPのスタイルは、このトピックで後述するダイアログ キーボード インターフェイスと組み合わせて使用します。

テンプレートでは、コントロールのウィンドウ クラスに固有のコントロール スタイルを指定することもできます。 たとえば、ボタン コントロールを指定するテンプレートでは、 BS_PUSHBUTTON や BS_CHECKBOXなどのボタン コントロール スタイルを指定する必要があります。 システムは、 WM_CREATE メッセージを 介してコントロール ウィンドウ プロシージャにコントロール スタイルを渡し、プロシージャがコントロールの外観と操作を調整できるようにします。

位置座標と幅と高さの測定値は、 CreateWindowEx に渡す前に、ダイアログの基本単位からピクセルに変換されます。 システムはコントロールを作成するときに、ダイアログ ボックスを親ウィンドウとして指定します。 つまり、システムは常に、ダイアログ ボックスのクライアント領域の左上隅を基準にして、コントロールの位置座標をクライアント座標として解釈します。

テンプレートは、各コントロールのウィンドウ クラスを指定します。 一般的なダイアログ ボックスには、ボタンや編集コントロール ウィンドウ クラスなど、定義済みのコントロール ウィンドウ クラスに属するコントロールが含まれています。 この場合、テンプレートは、クラスに対応する定義済みの atom 値を指定することで、ウィンドウ クラスを指定します。 ダイアログ ボックスにカスタム コントロール ウィンドウ クラスに属するコントロールが含まれている場合、テンプレートには、その登録済みウィンドウ クラスの名前または現在名前に関連付けられている atom 値が指定されます。

ダイアログ ボックス内の各コントロールは、他のコントロールと区別するために一意の識別子を持っている必要があります。 コントロールは、 WM_COMMAND メッセージを介してダイアログ ボックス プロシージャに情報を送信するため、コントロール識別子は、指定されたメッセージを送信したコントロールをプロシージャが判断するために不可欠です。 この規則の唯一の例外は、静的コントロールのコントロール識別子です。 静的コントロールは、WM_COMMANDメッセージを送信しないため、一意の識別子 は 必要ありません。

ユーザーがダイアログ ボックスを閉じできるようにするには、テンプレートで少なくとも 1 つのプッシュ ボタンを指定し、コントロール識別子 IDCANCEL を指定する必要があります。 ユーザーがダイアログ ボックスに関連付けられているタスクの完了または取り消しを選択できるようにするには、テンプレートで[ OK] と [ キャンセル] というラベルの付いた 2 つのプッシュ ボタンと、 IDOK とIDCANCEL のコントロール識別子をそれぞれ指定する必要があります。

テンプレートには、コントロールのオプションのテキストと作成データも指定されます。 テキストは通常、ボタン コントロールのラベルを提供するか、静的テキスト コントロールの初期コンテンツを指定します。 作成データは、コントロールの作成時にシステムがコントロール ウィンドウ プロシージャに渡す 1 バイト以上のデータです。 作成データは、他のデータで指定された情報よりも初期コンテンツまたはスタイルに関する詳細情報を必要とするコントロールに役立ちます。 たとえば、アプリケーションでは、作成データを使用して、スクロール バー コントロールの初期設定と範囲を設定できます。

ダイアログ ボックス ウィンドウ メニュー

テンプレートが WS_SYSMENU スタイルを指定すると、ダイアログ ボックスにウィンドウ メニューが表示されます。 不適切な入力を防ぐために、メニューの [移動 ] と [ 閉じる] を除くすべての項目が自動的に無効になります。 ユーザーは [ 移動 ] をクリックしてダイアログ ボックスを移動できます。 ユーザーが [閉じる] をクリックすると、wParam パラメーターが IDCANCEL に設定されたWM_COMMAND メッセージがダイアログ ボックス プロシージャに送信されます。 これは、ユーザーがクリックしたときに [キャンセル ] ボタンによって送信されるメッセージと同じです。 このメッセージの推奨されるアクションは、ダイアログ ボックスを閉じ、要求されたタスクをキャンセルすることです。

ダイアログ ボックス内の他のメニューは推奨されませんが、ダイアログ ボックス テンプレートでは、メニュー リソースの識別子または名前を指定することでメニューを指定できます。 この場合、システムはリソースを読み込み、ダイアログ ボックスのメニューを作成します。 アプリケーションでは、通常、テンプレートを使用してダイアログ ボックスではなくカスタム ウィンドウを作成するときに、テンプレートでメニュー識別子または名前を使用します。

ダイアログ ボックスのフォント

ダイアログ ボックスのフォントの平均文字幅を使用して、ダイアログ ボックスの位置と寸法が計算されます。 既定では、 SYSTEM_FONT フォントを 使用して、ダイアログ ボックス内のすべてのテキストが描画されます。

既定以外のダイアログ ボックスのフォントを指定するには、ダイアログ ボックス テンプレートを使用してダイアログ ボックスを作成する必要があります。 テンプレート リソースで、 FONT ステートメントを使用します。 ダイアログ ボックス テンプレートで、 DS_SETFONT または DS_SHELLFONT スタイルを設定し、ポイント サイズと書体名を指定します。 ダイアログ ボックス テンプレートでこの方法でフォントが指定されている場合でも、システムは常にダイアログ ボックスのタイトルとダイアログ ボックス メニューにシステム フォントを使用します。

ダイアログ ボックスに DS_SETFONT または DS_SHELLFONT スタイルがある場合、システムはダイアログ ボックス プロシージャと各コントロールに WM_SETFONT メッセージを送信します。 ダイアログ ボックスの手順では、 WM_SETFONT メッセージで渡されたフォント ハンドルを保存し、ウィンドウにテキストを書き込むたびに、そのハンドルをディスプレイ デバイス コンテキストに選択します。 既定では、定義済みのコントロールによってこの処理が行われます。

システム フォントは、Windows のバージョンによって異なる場合があります。 実行されているシステムに関係なく、アプリケーションでシステム フォントを使用するには、タイプフェイス MS Shell Dlg で DS_SHELLFONTを使用し、DIALOG リソースの代わりに DIALOGEX リソースを使用します。 このタイプフェイスは、ダイアログ ボックスで Tahoma フォントが使用されるようにマップされます。 タイプフェイスが MS Shell Dlg でない場合、 DS_SHELLFONT は効果がないことに注意してください。

メモリ内のテンプレート

メモリ内のダイアログ ボックス テンプレートは、ダイアログ ボックスを記述するヘッダーの後に、ダイアログ ボックス内の各コントロールを記述する 1 つ以上の追加のデータ ブロックで構成されます。 テンプレートでは、標準形式または拡張形式のいずれかを使用できます。 標準テンプレートでは、ヘッダーは DLGTEMPLATE 構造体の後に追加の可変長配列が続きます。 各コントロールのデータは、 DLGITEMTEMPLATE 構造体の後に追加の可変長配列が続きます。 拡張ダイアログ ボックス テンプレートでは、ヘッダーは DLGTEMPLATEEX 形式を使用し、コントロール定義では DLGITEMTEMPLATEEX 形式を使用します。

標準テンプレートと拡張テンプレートを区別するには、ダイアログ ボックス テンプレートの最初の 16 ビットをチェックします。 拡張テンプレートでは、最初の WORD は0xFFFF。その他の値は標準テンプレートを示します。

メモリ内にダイアログ テンプレートを作成する場合は、 各 DLGITEMTEMPLATE または DLGITEMTEMPLATEEX コントロール定義が DWORD 境界に揃っていることを確認する必要があります。 さらに、コントロール定義に従う作成データは、 DWORD 境界に配置する必要があります。 ダイアログ ボックス テンプレート内の他のすべての可変長配列は、 WORD の境界に配置する必要があります。

テンプレート ヘッダー

ダイアログ ボックスの標準テンプレートと拡張テンプレートの両方で、ヘッダーには次の一般的な情報が含まれています。

  • ダイアログ ボックスの場所と寸法
  • ダイアログ ボックスのウィンドウとダイアログ ボックスのスタイル
  • ダイアログ ボックス内のコントロールの数。 この値は、テンプレート内の DLGITEMTEMPLATE または DLGITEMTEMPLATEEX コントロール定義の数を決定します。
  • ダイアログ ボックスのオプションのメニュー リソース。 テンプレートは、ダイアログ ボックスにメニューがないことを示したり、実行可能ファイル内のメニュー リソースを識別する序数値または null で終わる Unicode 文字列を指定したりできます。
  • ダイアログ ボックスのウィンドウ クラス。 これには、定義済みのダイアログ ボックス クラス、または登録済みウィンドウ クラスを識別する序数値または null で終わる Unicode 文字列のいずれかを指定できます。
  • ダイアログ ボックス ウィンドウのタイトルを指定する null で終わる Unicode 文字列。 文字列が空の場合、ダイアログ ボックスのタイトル バーは空白になります。 ダイアログ ボックスに WS_CAPTION スタイルがない場合、タイトルは指定した文字列に設定されますが、表示されません。
  • ダイアログ ボックスに DS_SETFONT スタイルがある場合、ヘッダーは、クライアント領域のテキストとダイアログ ボックスのコントロールに使用するフォントのポイント サイズと書体名を指定します。

拡張テンプレートでは、 DLGTEMPLATEEX ヘッダーによって次の追加情報も指定されます。

  • システムが WM_HELP メッセージを送信するときのダイアログ ボックス ウィンドウのヘルプ コンテキスト識別子。
  • ダイアログ ボックスに DS_SETFONT または DS_SHELLFONT スタイルがある場合、ヘッダーはフォントの太さを指定し、フォントが斜体かどうかを示します。

コントロール定義

テンプレート ヘッダーの後には、ダイアログ ボックスのコントロールを記述する 1 つ以上のコントロール定義があります。 標準テンプレートと拡張テンプレートの両方で、ダイアログ ボックス ヘッダーには、テンプレート内のコントロール定義の数を示すメンバーがあります。 標準テンプレートでは、各コントロール定義は DLGITEMTEMPLATE 構造体の後に追加の可変長配列で構成されます。 拡張テンプレートでは、コントロール定義で DLGITEMTEMPLATEEX 形式が使用されます。

標準テンプレートと拡張テンプレートの両方で、コントロール定義には次の情報が含まれます。

  • コントロールの位置と寸法。
  • コントロールのウィンドウとコントロールのスタイル。
  • コントロール識別子。
  • コントロールのウィンドウ クラス。 これには、定義済みのシステム クラスの序数値、または登録済みウィンドウ クラスの名前を指定する null で終わる Unicode 文字列のいずれかを指定できます。
  • コントロールの初期テキストを指定する null で終わる Unicode 文字列、または実行可能ファイル内のアイコンなどのリソースを識別する序数値。
  • 作成データの省略可能な可変長ブロック。 システムは、コントロールを作成するときに、コントロールに送信するWM_CREATE メッセージの lParam パラメーターで、このデータへのポインターを渡します。

拡張テンプレートでは、コントロール定義は、システムが WM_HELP メッセージを送信するときに、コントロールのヘルプ コンテキスト識別子も指定します。