ヘルプ・キー機能は、すべての OSF/Motif マネージャ・ウィジェットとプリミティブ・ウィジェットに組み込まれています。ヘルプ・キーをアクティブにしたいウィジェットにヘルプ・コールバックを追加すると、ヘルプ・キーが使用可能になります。
アプリケーション内では、ヘルプに固有のエントリ・ポイントが必要なウィジェットすべてに、それぞれヘルプ・コールバックを追加してください。そのコールバックを呼び出すまで、ヘルプ・コールバック機能は自動的にウィジェット階層を (シェル・ウィジェットまで) 上ります。
ヘルプ・コールバックをマネージャ・ウィジェットに追加する場合、ヘルプ・キーを任意の子のために押すと、(子ウィジェットに独自のヘルプ・コールバックがなければ) マネージャのヘルプ・コールバックが呼び出されます。
XtAddCallback() 関数を次のように使用します。
XtAddCallback ( Widget widget, String DtNhelpCallback, XtCallbackProc HelpRequestCB, XtPointer clientData );
ヘルプ・キーをアクティブにする場所のウィジェット
ユーザがヘルプ・キーを押したときにヘルプ要求を処理するアプリケーションの関数
HelpRequestCB() 関数に渡すデータ。通常は表示するトピックを示します。
ユーザがヘルプ・キーを押すと、ウィジェットのヘルプ・コールバックが現在のキーボード・フォーカスと共に呼び出されます。ウィジェットにヘルプ・コールバックがない場合、ヘルプ・コールバックを持つ最も近い先祖のコールバックが呼び出されます。
ヘルプ・コールバックが見つからない場合は何も処理されません。この場合、ヘルプ・コールバックをアプリケーションの各シェルに追加するようにしてください。こうすると、ユーザのヘルプ要求が失われることがありません。
ヘルプ・コールバックをダイアログ・シェルに追加すると、自動的にダイアログの [ヘルプ] ボタンでヘルプ・コールバックを呼び出せるようになります。
追加したそれぞれのヘルプ・コールバックで clientData に固有の値を指定すると、各ヘルプ・コールバックを処理するために別々の関数を書かずに済みます。アプリケーションにはすべてのヘルプ要求を処理する 1 つのコールバック・プロシージャを持たせることができます (「ヘルプ・コールバックを追加するには」を参照してください)。コールバック・プロシージャでは、ユーザが要求したヘルプを識別するのに clientData を使用します。つまり、ヘルプ・コールバックを追加するたびに、clientData に固有の値を設定してください。
次の例は、ID をエントリ・ポイントに指定する方法の 1 つを示しています。HelpEntryIds.h ファイルは、各ヘルプ・コールバックの clientData に固有の整数を定義するのに使用します。各ウィジェットに対する 2 つの ID 文字列も定義されます。1 つは通常の [F1] ヘルプ用、もう 1 つはアイテムヘルプ・モード (ユーザがウィジェットから記述を取得する場所) 用です。
たとえば、アプリケーションのユーザ・インタフェースが、Name、Address、Telephone Number という 3 つの入力フィールドを持つメイン・ウィンドウだとします。次の例は HelpEntryIds.h ファイルの内容です。
#define HELP_volumeName "MyVolume" #define HELP_MainWindow 100 #define HELP_MainWindow_ID "basic-tasks" #define HELP_MainWindow_ITEM_ID "main-window-desc"
#define HELP_NameField 101 #define HELP_NameField_ID "specifying-a-name" #define HELP_NameField_ITEM_ID "name-field-desc" #define HELP_AddressField 102 #define HELP_AddressField_ID "specifying-an-address" #define HELP_AddressField_ITEM_ID "address-field-desc" #define HELP_PhoneField 103 #define HELP_PhoneField_ID "specifying-a-phone-no" #define HELP_PhoneField_ITEM_ID "phone-field-desc"
最初にウィジェットを作成したアプリケーションの一部で、次のようにヘルプ・コールバックが各ウィジェットに追加されます。
XtAddCallback (mainWindow, DtNhelpCallback, HelpRequestCB, HELP_MainWindow); XtAddCallback (nameField, DtNhelpCallback, HelpRequestCB, HELP_NameField); XtAddCallback (addressField, DtNhelpCallback, HelpRequestCB, HELP_AddressField); XtAddCallback (phoneField, DtNhelpCallback, HelpRequestCB, HELP_PhoneField);
HelpRequestCB() 関数では、ヘルプ要求を (switch() 文によって) ディスパッチするために clientData パラメータを使用します。ヘルプ・コールバックが [F1] キーによって呼び出された (フラグは「false」) のか、アイテムヘルプ・モードでユーザがウィジェットを選択した (フラグは「true」) のかを調べるため、グローバル・フラグ itemHelp の値が調べられます。
XtCallbackProc HelpRequestCB ( Widget w, XtPointer clientData, XtPointer callData ) { char *topicToDisplay; Boolean useQuickHelpDialog; /* Determine the topic ID for the given ` clientData.' */ switch ((int)clientData) { case HELP_MainWindow: useQuickHelpDialog = False; if (itemHelpFlag) topicToDisplay = HELP_MainWindow_ITEM_ID; else topicToDisplay = HELP_MainWindow_ID; break; case HELP_NameField: useQuickHelpDialog = True; if (itemHelpFlag) topicToDisplay = HELP_NameField_ITEM_ID; else topicToDisplay = HELP_NameField_ID; break; case HELP_AddressField: useQuickHelpDialog = True; if (itemHelpFlag) topicToDisplay = HELP_AddressField_ITEM_ID; else topicToDisplay = HELP_AddressField_ID; break; case HELP_PhoneField: useQuickHelpDialog = True; if (itemHelpFlag) topicToDisplay = HELP_PhoneField_ITEM_ID; else topicToDisplay = HELP_PhoneField_ID; break; default: /* An unknown clientData was received. */ /* Put your error handling code here. */ return; break; } /* Display the topic. */ ac = 0; XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_TOPIC); ac++; XtSetArg (al[ac], DtNhelpVolume, HELP_volumeName); ac++; XtSetArg (al[ac], DtNhelpType, topicToDisplay); ac++; if (useQuickHelpDialog) { XtSetValues (mainQuickHelpDialog, al, ac); XtManageChild (mainQuickHelpDialog); } else { XtSetValues (mainHelpDialog, al, ac); XtManageChild (mainHelpDialog); } /* Clear the ` item help' flag. */ itemHelpFlag = False; }
上記の関数は、アプリケーションがすべてのヘルプ要求に対して 2 つのヘルプ・ダイアログ (mainHelpDialog と mainQuickHelpDialog) を使用し、これらのダイアログがすでに作成されていると想定しています。また、(Xt 引き数リストで使用される) al と ac が別の場所で宣言されたものと見なしています。