ヘルプ・キー ([F1] キー) を使用可能にする
ヘルプ・キー機能は、すべての OSF/Motif マネージャ・ウィジェットとプリミティブ・ウィジェットに組み込まれています。ヘルプ・キーをアクティブにしたいウィジェットにヘルプ・コールバックを追加すると、ヘルプ・キーが使用可能になります。
アプリケーション内では、ヘルプに固有のエントリ・ポイントが必要なウィジェットすべてに、それぞれヘルプ・コールバックを追加してください。そのコールバックを呼び出すまで、ヘルプ・コールバック機能は自動的にウィジェット階層を (シェル・ウィジェットまで) 上ります。
ヘルプ・コールバックをマネージャ・ウィジェットに追加する場合、ヘルプ・キーを任意の子のために押すと、(子ウィジェットに独自のヘルプ・コールバックがなければ) マネージャのヘルプ・コールバックが呼び出されます。
ヘルプ・コールバックを追加するには
XtAddCallback() 関数を次のように使用します。
XtAddCallback (
Widget widget,
String DtNhelpCallback,
XtCallbackProc HelpRequestCB,
XtPointer clientData );
- widget
-
ヘルプ・キーをアクティブにする場所のウィジェット
- HelpRequestCB()
-
ユーザがヘルプ・キーを押したときにヘルプ要求を処理するアプリケーションの関数
- 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 が別の場所で宣言されたものと見なしています。
- © 2010, Oracle Corporation and/or its affiliates