クライアント・データの重要性

追加したそれぞれのヘルプ・コールバックで 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 が別の場所で宣言されたものと見なしています。