アイテムヘルプ・モードのサポート

一部のアプリケーションは、[ヘルプ] メニューに [アイテムヘルプ] コマンドまたは [ヘルプ・モード] コマンドを備えています。このコマンドはマウス・ポインタを一時的に ? (クエスチョン・マーク) として再定義し、ユーザに画面の項目を選択するようプロンプト要求します。項目を選択すると、その項目の説明をアプリケーションが表示します。

便利な関数に DtHelpReturnSelectedWidgetId() がありますが、これはポインタをクエスチョン・マークに変更してユーザがウィジェットを選択するのを待ちます。選択したウィジェットの ID が返されます。この関数は XmTrackingLocate() に似ていますが、ユーザがエスケープ・キーを押してオペレーションを取り消すと NULL を返す点が異なります。

選択した項目のヘルプを表示するには、単に返されたウィジェットのヘルプ・コールバックを呼び出すだけです。これはウィジェットの使用中にユーザが [F1] キーを押すのと同じことです。

アイテムヘルプと F1 ヘルプとを区別させる場合は、ウィジェットのヘルプ・コールバックを呼び出す前にフラグを設定します。こうすると、アイテムヘルプの結果として呼び出すコールバックを判別するのにそのフラグを使用し、それに従って応答するようになります。

アイテムヘルプのサポートを追加するには

1. DtHelpReturnSelectedWidgetId() 関数を使用して関数を記述します。この関数では、選択したウィジェットのヘルプ・コールバックを呼び出します。次のステップではこの関数を ProcessOnItemHelp() と呼びますが、他の名前を付けることもできます。

2. [ヘルプ] メニューに [アイテムヘルプ] というラベルの付いたコマンドを追加します。ProcessOnItemHelp() 関数を呼び出すアクティブ・コールバックを追加します。

3. アイテム・ヘルプを使用するアプリケーションの各ウィジェットに、ヘルプ・コールバックを追加します。

選択したウィジェットにヘルプ・コールバックがない場合、アプリケーションはその親ウィジェットの検索を試みます。同様に、親ウィジェットにない場合はその上の階層を検索し、ヘルプ・コールバックが見つかるまで試行を繰り返します。

例

次のプロシージャは 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;
     }
 }