次の方法で共有

テクニカル ノート 28: 状況依存のヘルプのサポート

  • [アーティクル]

ここでは、 MFC でヘルプ コンテキスト ID および他のヘルプの問題を割り当てるための規則について説明します。状況依存のヘルプ サポートは、 Visual C++ で使用できるヘルプ コンパイラが必要です。

[!メモ]

WinHelp を使用する状況依存のヘルプの実装に加えて、 HTML を使用しても、 MFC サポートができます。このサポートの詳細および HTML ヘルプでのプログラミングについては、 HTML ヘルプ: プログラムの状況依存のヘルプを参照してください。

サポートされるヘルプの種類

Windows アプリケーションで実行される状況依存のヘルプの 2 種類があります。1 番目のは現在アクティブなオブジェクトに基づいて適切なコンテキストに、 「F1 ヘルプ」として参照されます WinHelp を起動します。2 番目 Shift+ 「F1」モードです。このモードでは、オブジェクトをクリックすると、マウス カーソルは、ヘルプのカーソルとユーザーの順序に変更します。この時点で、 WinHelp は、ユーザーがクリックしたオブジェクトのヘルプを提供するために起動します。

Microsoft の基本クラスは、ヘルプの二つの形式を実行します。また、フレームワークは 2 種類の単純なヘルプ コマンドは、ヘルプ索引を使用するヘルプ サポートします。

ヘルプ ファイル

Microsoft の基本クラスは一つのヘルプ ファイルを前提としています。ヘルプ ファイルは、アプリケーションと同じ名前およびパスが必要な場合。たとえば、実行可能ファイルが 15 C 場合: \MyApplication\MyHelp.exe the help file must be C:\MyApplication\MyHelp .hlp。CWinApp クラスの m_pszHelpFilePath のメンバー変数でパスを設定します。

ヘルプ コンテキストのスコープ

MFC の既定の実装は、プログラムがヘルプ コンテキスト ID の代入に関する規則に従う必要があります。これらの規則は、特定のコントロールに割り当てられた ID の範囲です。さまざまなヘルプ関連のメンバー関数の異なる実装を提供することにより、これらの規則をオーバーライドできます。

0x00000000 - 0x0000FFFF : user defined
0x00010000 - 0x0001FFFF : commands (menus/command buttons)
   0x00010000 + ID_
   (note: 0x18000-> 0x1FFFF is the practical range since command IDs are >=0x8000)
0x00020000 - 0x0002FFFF : windows and dialogs
   0x00020000 + IDR_
   (note: 0x20000-> 0x27FFF is the practical range since IDRs are <= 0x7FFF)
0x00030000 - 0x0003FFFF : error messages (based on error string ID)
   0x00030000 + IDP_
0x00040000 - 0x0004FFFF : special purpose (non-client areas)
   0x00040000 + HitTest area
0x00050000 - 0x0005FFFF : controls (those that are not commands)
   0x00040000 + IDW_

単純な 「Help」コマンド

Microsoft の基本クラスによって実装される 2 種類の単純なヘルプ コマンドがあります:

最初のコマンドは、アプリケーションのヘルプ索引を示します。2 番目のは、 WinHelp のプログラム用にユーザー ヘルプを示します。

状況依存のヘルプ （F1 ヘルプ）

F1 キーは、通常、メイン ウィンドウのアクセラレータ テーブルにあるアクセラレータによって ID_HELP の ID とコマンドに変換されます。ID_HELP コマンドは、メイン ウィンドウまたはダイアログ ボックスに ID_HELP の ID のボタンに生成されることがあります。

ID_HELP コマンドは実行方法に関係なく生成するか、コマンド ハンドラーに到達するまで正常なコマンドとしてルーティングされます。MFC のコマンド ルーティング アーキテクチャに関する詳細については、 テクニカル ノート 21を参照してください。アプリケーションに有効なヘルプがある場合 ID_HELP コマンドは CWinApp::OnHelpによって処理されます。アプリケーション オブジェクトがヘルプ メッセージを受け取り、コマンドを適切にパスを指定します。これが既定のコマンドのルーティングが特定のコンテキストを決定するには十分ではないためです。

CWinApp::OnHelp は、次の順序で WinHelp を起動しようとしています:

  1. ヘルプ ID を持つ AfxMessageBox のアクティブな呼び出しのチェックメッセージ ボックスが現在アクティブな場合は、 WinHelp は、メッセージ ボックスに適切なコンテキストに起動します。

  2. アクティブ ウィンドウに WM_COMMANDHELP のメッセージを送信します。そのペインが WinHelp を起動して応答しない場合、同じメッセージは、ウィンドウの親にメッセージが処理される場合、または現在のペインがトップレベル ウィンドウになるまで送信されます。

  3. メイン ウィンドウに ID_DEFAULT_HELP コマンドを送信します。これは、既定のヘルプを起動します。このコマンドは CWinApp::OnHelpIndexに一般にマップされます。

全体的に既定の ID の基本値を上書きするには （たとえば。コマンドの 0x10000、ダイアログのようなリソースの 0x20000）は、アプリケーション CWinApp::WinHelpをオーバーライドする必要があります。

この機能とヘルプ コンテキストが決定する方法をオーバーライドするには、 WM_COMMANDHELP メッセージを処理する必要があります。現在の MDI 子ウィンドウだけ深さので、フレームワークが提供するよりも多くの特定のルーティングを提供することがあります。そのオブジェクトの現在の内部状態またはダイアログ内のアクティブなコントロールに固有のヘルプを特定のウィンドウまたはダイアログに、基づいて提供する必要があります。

WM_COMMANDHELP

afx_msg LRESULT CWnd::OnCommandHelp(WPARAM wParam, LPARAM lParam)

WM_COMMANDHELP は、ヘルプが要求されたときにアクティブ ウィンドウが受信プライベート ウィンドウの MFC メッセージです。ウィンドウがメッセージを受け取ると、ウィンドウの内部状態に一致するコンテキストの CWinApp::WinHelp をダイヤルする場合があります。

  • lParam
    現在使用できるヘルプ コンテキストが含まれます。lParam は、ヘルプ コンテキストが定められなかったらゼロになります。OnCommandHelp の実装は lParam で異なるコンテキストを確認するには、コンテキスト ID を使用して、 CWinApp::WinHelpにを渡すことができます。

  • wParam
    は使用されず、です。

OnCommandHelp の関数呼び出し CWinApp::WinHelpでは、 TRUEを返します。TRUE を返すことは、他のクラスとそのほかのペインにこのコマンドのルーティングを停止します。

ヘルプ モード （Shift+F1 ヘルプ）

これは状況依存のヘルプの 2 番目の形式です。通常、このモードは Shift + F1 キーを押すか、メニューおよびツールバーに入力されます。は、コマンド （ID_CONTEXT_HELP）として実装されます。モーダル ダイアログ ボックスまたはメニューがアクティブな間、メッセージ フィルターのフック関数でこのコマンドを使用していないため、アプリケーションがメイン メッセージ ポンプ （CWinApp::Run）を実行する場合は、このコマンドはユーザーにのみ使用できます。

このモードになったら、ヘルプ マウス カーソルは、アプリケーションのすべての領域にアプリケーションは、通常、その領域の独自のカーソルが表示されます （ペインの周囲のサイズ変更境界など）。ユーザーがコマンドを選択するには、マウスまたはキーボードを使用できます。コマンドを実行する代わりに、そのコマンドのヘルプが表示されます。また、ユーザーはツールバー ボタンのような画面に表示されているオブジェクトをクリックし、ヘルプは、そのオブジェクトのように表示されます。ヘルプこのモードは CWinApp::OnContextHelpによって提供されます。

このループの実行中に、すべてのキーボード入力をメニューにアクセスするキーを除く無効になります。または、コマンド変換は、 PreTranslateMessage によってユーザーがアクセラレータ キーを押して、そのコマンドのヘルプを受け取るようにするために実行されます。

特定の変換がある場合、または + F1 ヘルプ モードの間に発生しない PreTranslateMessage での操作が機能すると、それらの操作を実行する前に CWinApp の m_bHelpMode のメンバーをチェックする必要があります。PreTranslateMessage の CDialog の実装は IsDialogMessageを呼び出す前に、たとえばチェックします。これは、 + F1 モードではモードレス ダイアログのダイアログ ナビゲーション 「」のキーを無効にします。また、 CWinApp::OnIdle は、このループの間に呼び出されます。

ユーザーがメニュー コマンドを選択すると、そのコマンドのヘルプとして処理されます （ WM_COMMANDHELPによっては、次を参照）。ユーザーがアプリケーション ウィンドウの表示領域をクリックすると、決定は、非クライアントのクリックやクライアント クリックであるかについてされます。クライアントへの非クライアントのクリックOnContextHelp ハンドルの マップすると、自動的にクリックします。クライアント クリックすると、クリックされたペインに、 WM_HELPHITTEST を送信します。そのペインがゼロ以外の値を返した場合、その値はヘルプは、コンテキストとして使用されます。これがを返した場合、 OnContextHelp は親ウィンドウします （とその親の失敗する場合など）。ヘルプ コンテキストを決定できない場合、既定値は CWinApp::OnHelpIndex（通常は）マップされるメイン ウィンドウへ ID_DEFAULT_HELP コマンドを送信することです。

WM_HELPHITTEST

afx_msg LRESULT CWnd::OnHelpHitTest(WPARAM, LPARAM lParam)

WM_HELPHITTEST は + F1 ヘルプ モードでクリックされたアクティブ ウィンドウが受信 MFC のプライベート ウィンドウのメッセージです。ウィンドウがメッセージを受け取ると、 WinHelp で使用するためのダブルワードのヘルプ ID を返します。

  • LOWORD （lParam）
    マウスがペインのクライアント領域に関連して、クリックされた x 軸のデバイス座標が含まれます。

  • lParam HIWORD （）
    y 軸の座標が含まれます。

  • wParam
    は使用されず、です。戻り値がゼロ以外の場合は、 WinHelp はそのコンテキストと呼ばれます。戻り値がゼロの場合、親ペインはヘルプのために呼び出されます。

多くの場合、既に持っている可能性のあるヒットテスト コードを利用できます。WM_HELPHITTEST のメッセージを処理する例については CToolBar::OnHelpHitTest の実装を参照します （コードは CControlBarでボタンやツールヒントで使用されるテスト コードを利用します）。

MFC アプリケーション ウィザードのサポートと MAKEHM

MFC アプリケーション ウィザードは、ヘルプ ファイルをビルドに必要なファイルが作成されます （.cnt および .hpj ファイル）。また、 Microsoft ヘルプ コンパイラで使用される多くのプレビルド .rtf ファイルが含まれています。トピックの多くは完了ですが、一部は特定のアプリケーションのように変更する必要があります。

「Help」マッピング ファイルの自動作成は MAKEHM というユーティリティでサポートされます。MAKEHM ユーティリティは、ヘルプのマッピング ファイルにアプリケーションの RESOURCE.H ファイルを変換できます。次に例を示します。

#define IDD_MY_DIALOG   2000
#define ID_MY_COMMAND   150

に変換されます:

HIDD_MY_DIALOG    0x207d0
HID_MY_COMMAND    0x10096

このフォームはトピックの名前 （左側のシンボル）のコンテキスト ID （右側の数）をマップするヘルプ コンパイラの機能と互換性のある型です。

MAKEHM のソース・コードは、 MFC プログラミング ユーティリティ サンプル MAKEHMで使用できます。

ヘルプ サポートを MFC アプリケーション ウィザードを実行した後で追加します

アプリケーションにヘルプを追加する最良の方法は、アプリケーションを作成する前に、 MFC アプリケーション ウィザードの高度な機能のページの 「状況依存のヘルプ] をチェックすることです。この方法は CWinAppに、 MFC アプリケーション ウィザード自動的に必要なメッセージ マップ エントリ - サポート情報への派生クラスを追加します。

メッセージ ボックスのヘルプ

メッセージ ボックスのヘルプは、 （警告） AfxMessageBox の関数、 MessageBox Windows API のラッパーでサポートされます。

文字列を文字列の ID の使用の AfxMessageBox、 1、およびポインターで使用するための別の 2 種類のバージョンがあります （LPCSTR）:

int AFXAPI AfxMessageBox(LPCSTR lpszText, UINT nType, UINT nIDHelp);
int AFXAPI AfxMessageBox(UINT nIDPrompt, UINT nType, UINT nIDHelp);

どちらの場合も、省略可能なヘルプ ID があります

nIDHelp の最初の場合、既定では、メッセージ ボックスに関するヘルプを表示する 0 です。ユーザーがメッセージ ボックスなど、 F1 キーを押すと、アクティブな場合、ユーザーはヘルプを受け取りません （アプリケーションでサポートのヘルプなど）。これが好ましくなければ、ヘルプ ID は nIDHelp を用意する必要があります。

nIDHelp の 2 番目の場合、既定値はヘルプ ID は nIDPrompt と同じであることを示す -1 です。ヘルプは、アプリケーションがヘルプ有効になっている場合のみ機能します）。メッセージ ボックスは、ヘルプ サポートされていないことを望めば nIDHelp に 0 を提供する必要があります。あるメッセージに有効なヘルプにはが nIDPrompt、別のヘルプ ID が生じた場合、 nIDPrompt の値と別の nIDHelp に正の値だけを提供します。

参照

その他の技術情報

番号順テクニカル ノート

カテゴリ別テクニカル ノート