一部のアプリケーションは、[ヘルプ] メニューに [アイテムヘルプ] コマンドまたは [ヘルプ・モード] コマンドを備えています。このコマンドはマウス・ポインタを一時的に ? (クエスチョン・マーク) として再定義し、ユーザに画面の項目を選択するようプロンプト要求します。項目を選択すると、その項目の説明をアプリケーションが表示します。
便利な関数に DtHelpReturnSelectedWidgetId() がありますが、これはポインタをクエスチョン・マークに変更してユーザがウィジェットを選択するのを待ちます。選択したウィジェットの ID が返されます。この関数は XmTrackingLocate() に似ていますが、ユーザがエスケープ・キーを押してオペレーションを取り消すと NULL を返す点が異なります。
選択した項目のヘルプを表示するには、単に返されたウィジェットのヘルプ・コールバックを呼び出すだけです。これはウィジェットの使用中にユーザが [F1] キーを押すのと同じことです。
アイテムヘルプと F1 ヘルプとを区別させる場合は、ウィジェットのヘルプ・コールバックを呼び出す前にフラグを設定します。こうすると、アイテムヘルプの結果として呼び出すコールバックを判別するのにそのフラグを使用し、それに従って応答するようになります。
DtHelpReturnSelectedWidgetId() 関数を使用して関数を記述します。この関数では、選択したウィジェットのヘルプ・コールバックを呼び出します。次のステップではこの関数を ProcessOnItemHelp() と呼びますが、他の名前を付けることもできます。
[ヘルプ] メニューに [アイテムヘルプ] というラベルの付いたコマンドを追加します。ProcessOnItemHelp() 関数を呼び出すアクティブ・コールバックを追加します。
アイテム・ヘルプを使用するアプリケーションの各ウィジェットに、ヘルプ・コールバックを追加します。
選択したウィジェットにヘルプ・コールバックがない場合、アプリケーションはその親ウィジェットの検索を試みます。同様に、親ウィジェットにない場合はその上の階層を検索し、ヘルプ・コールバックが見つかるまで試行を繰り返します。
次のプロシージャは ProcessOnItemHelp() 関数の例ですが、これは [ヘルプ] メニューから [アイテムヘルプ] を選択すると呼び出されます。
void ProcessOnItemHelp( Widget widget) { /* Declare a variable for the selected widget. */ Widget selWidget=NULL; int status=DtHELP_SELECT_ERROR; /* Get an application shell widget from our widget hierarchy to * pass into DtHelpReturnSelectedWidgetId(). */ while (!XtIsSubclass(widget, applicationShellWidgetClass)) widget = XtParent(widget); status = DtHelpReturnSelectedWidgetId(widget, NULL, &selWidget); switch ((int)status) { case DtHELP_SELECT_ERROR: printf("Selection Error, cannot continue¥n"); break; case DtHELP_SELECT_VALID: /* We have a valid widget selection, now let's look for a registered help * callback to invoke. */ while (selWidget != NULL) { if ((XtHasCallbacks(selWidget, XmNhelpCallback) == XtCallbackHasSome)) { /* Found a help callback, so just call it */ XtCallCallbacks((Widget)selWidget, XmNhelpCallback,NULL); break; } else /* No help callback on current widget, so try the widget's parent */ selWidget = XtParent(selWidget); } break; case DtHELP_SELECT_ABORT: printf("Selection Aborted by user.¥n"); break; case DtHELP_SELECT_INVALID: printf("You must select a component within your app.¥n"); break; } }