# ヘルプ・ダイアログのイベント処理

この章では、アプリケーションが処理するヘルプ・ダイアログのイベントについて説明します。

HRDC.DiaEv.mkr.2
HRDC.DiaEv.mkr.3
HRDC.DiaEv.mkr.5
HRDC.DiaEv.mkr.6

## ヘルプ・ダイアログ・イベントのサポート

アプリケーション内の他のウィジェットと同様に、ヘルプ・ウィンドウには、アプリケーションがサポートしなければならない動作がいくつかあります。

### ハイパーリンク・イベント

標準ハイパーリンク・イベントのほとんどは、ヘルプ・システムによって内部的に処理されます。しかし、次に示す４種類のアプリケーションが処理しなければならないハイパーリンクがあります。

- 新規ウィンドウ表示ハイパーリンク 新規ヘルプ・ウィンドウにトピックを表示するという設計者の要求に応じて、アプリケーションは新規のヘルプ・ダイアログを作成しなければなりません。

- マニュアル・ページ・リンク アプリケーションは、新規の簡易ヘルプ・ダイアログを作成し（またはキャッシュから取り出し）、マニュアル・ページを表示しなければなりません。通常、マニュアル・ページ・ウィンドウのサイズは、他のすべてのヘルプ・ウィンドウと異なります。

- アプリケーション定義リンク アプリケーションは、これらのリンクに関連付けられているデータを解釈しなければなりません。アプリケーション定義リンクは、アプリケーションの開発者とヘルプの設計者が、このリンクの作成のために共同で作業をした場合にだけ存在します。

- テキスト・ファイル・リンク アプリケーションは簡易ヘルプ・ダイアログを作成し（またはキャッシュから取り出し）、テキスト・ファイルを表示しなければなりません。

### ダイアログを終了する場合

ユーザがヘルプ・ダイアログを閉じる場合、そのキャッシュ内にダイアログを格納するか、または破棄するかを認識している必要があります。一般ヘルプ・ダイアログでは、ヘルプ・クローズ・コールバックをサポートしています。簡易ダイアログの終了を検知するには、[閉じる]ボタンにコールバックを追加してください。

### 簡易ヘルプ・ボタン

簡易ヘルプ・ダイアログにあるいくつかのボタンの動作は、アプリケーションによって処理されなければなりません。これらのボタンは、必要に応じて管理することも管理しないことも可能です。起動コールバックを使用して、他のプッシュボタンのように動作を追加することができます。

#### 関連項目

- は、ヘルプ・システムがサポートしているリンクの種類を記述し、リンクの作成方法について説明しています。

## ハイパーリンク・イベントへの応答

アプリケーションは、表示されるヘルプ・ボリューム内で使用されるハイパーリンクの種類だけは、少なくともサポートする必要があります。一般的には、すべてのリンクの種類をサポートするようにしてください。

ハイパーリンクが選択されたときに、アプリケーションに通知する場合、ハイパーリンク・コールバックをヘルプ・ダイアログに追加します。適切にハイパーリンクを処理するコールバック関数を指定しなければなりません。

### ハイパーリンク・コールバックを指定するには

1. 次のようにしてハイパーリンク・コールバックを各ヘルプ・ダイアログに追加します。

       XtAddCallback ( helpDialog, DtNhyperlLinkCallback,
       HyperlinkCB, (XtPointer)NULL);

   helpDialog は、ヘルプ・ダイアログのウィジェットIDで、HyperlinkCB は、ハイパーリンクを処理するコールバック関数の名前です。

2. ダイアログ内で発生する可能性があるハイパーリンク・イベントを処理するための HyperlinkCB 関数を指定します。

ハイパーリンク・コールバック内で、次のコールバック構造体（`<Dt/Help.h>` で宣言されます）にアクセスしなければなりません。

    typedef struct
     {
    int      reason;
    XEvent  *event;
    char    *locationId;
    char    *helpVolume;
    char    *specification;
    int      hyperType;
    int      windowHint;
    } DtHelpDialogCallbackStruct;

`hyperType` 要素は、実行されたリンクの種類を示します。指定可能な値は、`DtHELP_LINK_TOPIC` `、` `DtHELP_LINK_MAN_PAGE``、` `DtHELP_LINK_APP_DEFINE``、および` `DtHELP_LINK_TEXT_FILE` `です。別の種類に対して、どの構造体要素が有効かということについては、` `DtHelpDialog`(3) のマニュアル・ページを参照してください。

`windowHint` 要素は、ウィンドウの種類を示します。その指定可能な値は、`DtHELP_CURRENT_WINDOW`、`DtHELP_POPUP_WINDOW`、および`DtHELP_NEW_WINDOW` です。

#### 例

次の関数 `HyperlinkCB()` は、ハイパーリンク・コールバックを処理するために必要な一般構造体を示しています。

    XtCallbackProc
    HyperlinkCB (widget, clientData, callData)
         Widget     widget;
         XtPointer  clientData;
         XtPointer  callData;
      {
         DtHelpDialogCallbackStruct *hyperData =
            (DtHelpDialogCallbackStruct *) callData;
         switch ((int)hyperData-> hyperType)
            {
               case DtHELP_LINK_TOPIC:
                 /* Handles  “jump new view”hyperlinks. */
                 break;
               case DtHELP_LINK_MAN_PAGE:
                 /* Handles  “man page” hyperlinks. */
                 break;
               case DtHELP_LINK_APP_DEFINE:
                 /* Handles “application-defined” hyperlinks. */
                 break;
               case DtHELP_LINK_TEXT_FILE:
                 /* Handles “text file” hyperlinks. */
                 break;
               default:
                 break;
       }

## ヘルプ・ダイアログの終了の検出

一般ヘルプ・ダイアログのクローズを検出するには、次のコールバックをダイアログに追加します。

    XtAddCallback (helpDialog, DtNcloseCallback,
                   HelpCloseCB, (XtPointer)NULL);

helpDialog はヘルプ・ダイアログのウィジェットIDで、HelpCloseCB はダイアログのクローズを処理するために指定したコールバック手続きの名前です。

簡易ヘルプ・ダイアログのクローズを検出するには、次のコールバックをダイアログの[了解]ボタンに追加します。

    XtAddCallback (DtHelpQuickDialogGetChild ( helpDialog,
    DtHELP_QUICK_OK_BUTTON), XmNactivateCallback, HelpCloseCB,
    (XtPointer)NULL);

helpDialog はヘルプ・ダイアログのウィジェットIDで、HelpCloseCB はダイアログのクローズを処理するために指定したコールバック手続きの名前です。

## アプリケーション構成ボタンの使い方

簡易ヘルプ・ダイアログのアプリケーション構成ボタンにより、カスタム動作を簡易ヘルプ・ダイアログに追加します。このボタンは、希望に合わせて使用できますが、その目的としては２つの方法のいずれかでヘルプへのパスを提供することです。

- 段階を追って情報を検索することができます。これは、しばしば段階的な表示と呼ばれます。この場合、デフォルトのボタン・ラベル（[詳細 …]）が適切です。

- アプリケーションのヘルプ・ボリュームを通常どおりブラウズするために、一般ヘルプ・ダイアログを開くことができるようにします。この場合、[ブラウズ …]がもっとも適切なボタン・ラベルになります。

### アプリケーション構成ボタンを使用可能にするには

1. ボタンのIDを取得します。

2. 起動コールバックをボタンに追加します。

3. ボタンを管理します。

#### 例

次のコード・セグメントは、ボタンのIDを取得し、コールバックを割り当て、ボタンを管理します。`quickHelpDialog` が作成されたばかりであることを想定しています。

    Widget  moreButton;
    moreButton = DtHelpQuickDialogGetChild (quickHelpDialog,
                                         DtHELP_QUICK_MORE_BUTTON);
    XtAddCallback (moreButton, XmNactivateCallback,
                   MoreHelpCB, NULL);
    XtManageChild (moreButton);

#### 関連項目

- HRDC.CrDia.mkr.7

- `DtHelpDialog`(3) マニュアル・ページ

- `DtHelpQuickDialog`(3) マニュアル・ページ

### [詳細 …]ボタンを使用して DtInfo にアクセスするには

デスクトップ DtHelp 機能の拡張機能として、アプリケーションは簡易ヘルプ・ダイアログの[詳細 …]ボタンにローカルなコールバックを追加することができます。これは、簡易ヘルプの表示内容と関連する追加情報のために dtinfo を引き続いて起動したり、詳細なヘルプ（「アプリケーションについて」や「ウィンドウについて」のような）のために DtInfo を直接起動します。

有用性に関する特定の見地から、ローカルな情報本体へのアクセスをユーザに提供する場合は、組み込みの関数 `DtActionInvoke()` を使用することができます。アンカー・ポイントは、ブックケースのトップと同じように広範囲か、あるいは、特定のセクションと同じように詳細か、どちらでも可能です。また、データの構築において、外部的に一意のリンクIDが与えられれば、セクション内のターゲットも可能です。

#### 例

次のセクションは、DtInfo を起動（または接続）する CDE デスクトップ・アクションの API の使用方法を説明しています。

`DtActionInvoke` を呼び出す前に、アプリケーションは、まずデスクトップ・サービス・ライブラリを初期化するために `DtInitialize` を、アクションとデータ型を読み込むために `DtDbLoad` を呼び出さなければなりません。DtInfo アクションおよびデータ型のエントリは CDE デスクトップの一部であるため、これらそれぞれについて `DtDbReloadNotify` 関数を使用する必要はありません。

    #include <Dt/Action.h>
    #include <limits.h>
    #include <locale.h>
       ...
    int info_bridge( char * infolib, char* uulocator)
    {
      char info_uuid[ MAXFQLOCATORBUFSIZE ];
      char exec_host[ MAXHOSTNAMESIZE ];
      DtActionArg* args = NULL;
      Xegetshorthostname(localhost, MAXHOSTNAMESIZE);
      args = (DtActionArg*) XtCalloc( 2, sizeof(DtActionArg) );
       ...
      args[0].argclass = DtACTION_BUFFER;
      args[0].u.buffer.bp = (void*) infolib;
      args[0].u.buffer.size = strlen( infolib) + 1;
      args[0].u.buffer.writable = False;
         ...
      sprintf( info_uuid, "%s%s", "mmdb:LOCATOR=", uulocator );
        args[1].argclass = DtACTION_BUFFER;
      args[1].u.buffer.bp = (void*) info_uuid;
      args[1].u.buffer.size = strlen( info_uuid) + 1;
      args[1].u.buffer.writable = False;

      actionId = DtActionInvoke(
        w,
        "DtShowInfoAtLOC",
        args,
        2,
        NULL,
        exec_host,
        NULL,
        True,
        NULL,
        NULL
      );
         ...
      XtFree( args );
    }