# ヘルプ・ダイアログ・ボックスの作成と管理

この章では、ヘルプ・ダイアログ・ウィジェットとその作成方法を説明します。

HRDC.CrDia.mkr.2
HRDC.CrDia.mkr.3
HRDC.CrDia.mkr.5
HRDC.CrDia.mkr.6
HRDC.CrDia.mkr.7
HRDC.CrDia.mkr.8

## ヘルプ・ダイアログ・ボックス

ヘルプ・システムは、アプリケーション・プログラマに対して、ヘルプ・ダイアログ・ボックスをすべての Motif アプリケーションに追加するプログラミング・ライブラリを提供します。ライブラリは、２種類のダイアログ・ボックスを提供します。

- 一般ヘルプ・ダイアログ には、メニューバー、トピック・ツリー、ヘルプ・トピック表示領域があります。トピック・ツリーには、ヘルプ・ボリュームのトピックとサブトピックが表示されます。ユーザは、表示するトピックを選択したり、使用可能なトピックをブラウズしたり、トピックがヘルプ・ボリュームのどこにあるかをみつけるために、トピック・ツリーを使用します。

- 簡易ヘルプ・ダイアログ には、トピック表示領域と、下部にひとつ以上のダイアログ・ボタンがあります。

### 標準の Xt パラダイム

プログラミングの観点からみると、ユーザは、アプリケーション内の他の Motif ウィジェットと対話するのと同じようにヘルプ・ダイアログと対話します。２種類のヘルプ・ダイアログ・ボックスは、２つの新しいウィジェット・クラス（`DtHelpDialog` と `DtHelpQuickDialog`）として定義されます。

ボリューム名、トピックIDなどのヘルプ・ウィンドウの属性のほとんどは、ウィジェット・リソースとして処理されます。たとえば、新しいトピックを表示するには、`DtNhelpVolume`、`DtNlocationId`、および `DtNhelpType` の各リソースを設定するために `XtSetValues()` の呼び出しを実行するだけです。詳細については、HRDC.HReq.mkr.3 を参照してください。

ヘルプ・システムをアプリケーションに統合するには、Ｃプログラミング言語、Motif プログラマーズ・ツールキット、Xt イントリンシクス・ツールキットに関する実用的な知識が必要です。

## 一般ヘルプ・ダイアログ

一般ヘルプ・ダイアログには、トピック・ツリーとトピック表示領域の２つの表示領域があります。トピック・ツリーは、スクロール可能なヘルプ・トピックのリストを提供しています。常にホーム・トピックのタイトルが１番目の項目になります。ユーザがタイトルを選択すると、そのタイトルに矢印 (→) が付き、そのヘルプ情報がトピック表示領域に表示されます。 hrdc.crdia.mkr.4 に、一般ヘルプ・ウィンドウのトピック・ツリーとトピック表示領域を示します。現在のトピック「パレットを選択するには」が表示されています。

一般ヘルプ・ダイアログには、[前のトピックへ]、[ヒストリ]、[索引] の３つのダイアログ・ボタンがあります。これらのコマンドは、ヘルプ・メニューでも使用できます。ヘルプ・ダイアログとグラフィカル・ユーザ・インタフェースの概要については、 HRDC.Intro.mkr.7 を参照してください。

### 一般ヘルプ・ダイアログ

### 一般ヘルプ・ダイアログを作成するには

1. 適切なヘッダ・ファイルを指定します。

       #include <Help.h>
       #include <HelpDialog.h>

2. 一般ヘルプ・ダイアログ・ウィジェットのインスタンスを作成します。

   `DtCreateHelpDialog()` 簡易関数を使用します。

   または `XtCreateManagedWidget()` 関数を使用します。

3. ダイアログ内で発生するハイパーリンク・イベントを処理するためのコールバックを追加します。（詳細については、HRDC.DiaEv.mkr.3 を参照してください。）

4. [閉じる]コマンドを処理するためのクローズ・コールバックを追加します。

#### 例

次のコード・セグメントは、簡易関数を使用して一般ヘルプ・ダイアログを（parent の子として）作成します。ダイアログは管理されていません。ヘルプが要求された時点で、アプリケーションによって管理されます。

    Widget   mainHelpDialog, moreButton, helpButton;
    ac = 0;
    XtSetArg (al[ac], XmNtitle,  "My Application - Help");  ac++;
    XtSetArg (al[ac], DtNhelpVolume,  "My Help Volume");  ac++;
    XtSetArg (al[ac], DtNlocationId,  "Getting Started");  ac++;
    XtSetArg (al[ac], DtNhelpType,  "DtHELP_TYPE_TOPIC");  ac++;
    mainHelpDialog =
      DtCreateHelpDialog (parent, "mainHelpDialog", al, ac);

次の２つの呼び出しは、ダイアログにハイパーリンクとクローズ・コールバックを追加します。関数 `HyperlinkCB()` と `CloseHelpCB()` は、ここには示されていないアプリケーションの別の場所で宣言しています。

    XtAddCallback (mainHelpDialog, DtNhyperLinkCallback,
                            HyperlinkCB, (XtPointer)NULL);
    XtAddCallback (mainHelpDialog, DtNcloseCallback,
                   CloseHelpCB, (XtPointer)NULL);

#### 関連項目

- HRDC.H4Hlp.mkr.1

- HRDC.DiaEv.mkr.7

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

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

## 簡易ヘルプ・ダイアログ

簡易ヘルプ・ダイアログ・ボックスは、オンライン・ヘルプの第一目標であるユーザができるだけ早く、また正常に作業に戻れることが実現できるように設計されています。このシンプルなユーザ・インタフェースによって、ユーザは情報に集中しつづけることができます。ダイアログの情報は、ユーザが読んだ後に消してしまっても作業が続けられるように、有用なものでなければなりません。

### ４つの標準ボタンを備えた簡易ヘルプ・ダイアログ

簡易ヘルプ・ダイアログには５つのボタンがあり、そのうち４つが管理されています。残りのダイアログ・ボタンは構成可能なので、このボタンは希望に合わせて使用することができます。しかし、その目的としては、次の２つの方法のどちらかでヘルプへのパスを提供することです。

- ユーザがより詳細な情報を探せるようにします。この場合、デフォルトのボタン・ラベル ([詳細]) が適切です。これは段階的な表示と呼ばれます。

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

開発者用ツールキットには、簡易関数 `DtHelpQuickDialogGetChild()` が含まれています。この関数は、どの簡易ヘルプ・ダイアログ・ボタンにも対応するウィジェットIDを決定します。

### 簡易ヘルプ・ダイアログを作成するには

1. 適切なヘッダ・ファイルを指定します。

       #include <Help.h>
       #include <HelpQuickD.h>

2. 簡易ヘルプ・ダイアログ・ウィジェットのインスタンスを作成します。

   - `DtCreateHelpQuickDialog()` 簡易関数を使用します。

   - または `XtCreateManagedWidget()` 関数を使用します。

3. ダイアログ内で発生するハイパーリンク・イベントを処理するためのコールバックを追加します（詳細については、HRDC.DiaEv.mkr.3 を参照してください）。

4. [了解] ボタンを処理するためのクローズ・コールバックを追加します。

5. 使用したいダイアログ・ボタンを構成します。

   - アプリケーション定義のボタンを使用するには、それを管理して起動コールバックを追加します。

   - 印刷を許可しないようにするには、[印刷]ボタンの管理を解除します。

   - ユーザが「ヘルプの使い方」を使用できるように、[ヘルプ]ボタンを管理し、ダイアログにヘルプ・コールバックを追加します。

#### 例

次のコード・セグメントは、簡易関数を使用して簡易ヘルプ・ダイアログを（parent の子として）作成します。ダイアログは管理されていません。ヘルプが要求された時点で、アプリケーションの別の場所で管理されます。この例では、アプリケーション定義のボタンが使用可能になっており、ヘルプをさらに要求するために使用しています。

    Widget   quickHelpDialog, moreButton, helpButton;
    ac = 0;
    XtSetArg (al[ac], XmNtitle,  "My Application - Help");  ac++;
    XtSetArg (al[ac], DtNhelpVolume,  "My Help Volume");  ac++;
    XtSetArg (al[ac], DtNlocationId,  "Getting Started");  ac++;
    XtSetArg (al[ac], DtNhelpType,  "DtHELP;_TYPE_TOPIC"); ac++;

    quickHelpDialog =
      DtCreateHelpQuickDialog (parent, "quickHelpDialog", al, ac);

次の２つの呼び出しは、ダイアログにハイパーリンクとクローズ・コールバックを追加します。関数 `HyperlinkCB()` と `CloseHelpCB()` は、この例には示されていないアプリケーションの別の場所で宣言されています。

    XtAddCallback (quickHelpDialog, DtNhyperLinkCallback,
                   HyperlinkCB, (XtPointer)NULL);
    XtAddCallback (quickHelpDialog, DtNcloseCallback,
                   CloseHelpCB, (XtPointer)NULL);

ここで、アプリケーション定義のボタンが管理され、アプリケーションの `MoreHelpCB()` 関数を起動する起動コールバックが割り当てられます。

    moreButton = DtHelpQuickDialogGetChild (quickHelpDialog,
                                 DT_HELP_QUICK_MORE_BUTTON);
    XtManageChild (moreButton);
    XtAddCallback (moreButton, XmNactivateCallback,
                   MoreHelpCB, (XtPointer)NULL);

「ヘルプの使い方」を提供するために、ダイアログの[ヘルプ]ボタンが管理され、ダイアログにヘルプ・コールバックが追加されます。

    helpButton = DtHelpQuickDialogGetChild (quickHelpDialog,
                                 DT_HELP_QUICK_HELP_BUTTON);
    XtManageChild (helpButton);
    XtAddCallback (quickHelpDialog,DtNhelpCallback,
                   HelpRequestCB, USING_HELP);

他の Motif ダイアログと同じように、簡易ヘルプ・ダイアログにヘルプ・コールバックを追加すると、[F1]キーと[ヘルプ]ボタンのどちらからでも簡易ヘルプ・ダイアログを使用することができます。

#### 関連項目

- HRDC.DiaEv.mkr.7

- HRDC.H4Hlp.mkr.1

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

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

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

## アプリケーション・プログラム・インタフェースの要約

ヘルプ・システムに関連するマニュアル・ページは次のとおりです。

- ダイアログの作成と操作のための関数

  - `DtHelp(5)`

  - `DtHelpDialog(5)`

  - `DtHelpQuickD(5)`

  - `DtCreateHelpDialog()`

  - `DtCreateHelpQUickDialog()`

  - `DtHelpQuickDialogGetChild()`

- 項目ヘルプ・モードの実現のための関数

  - `DtHelpReturnSelectedWidgetId()`

- ヘルプ・ライブラリにメッセージ・カタログを指定するための関数

  - `DtHelpSetCatalogName()`

- ヘルプ・ボリュームの作成および表示のためのアプリケーションとアクション

  - `dtdocbook`(1)

  - `dthelpview`(1)

  - `dthelpgen`(1)

  - `dthelpaction(5)`

  - `dtmanaction(5)`

- 文書型定義

  - `dtdocbookdtd(4)`

  - `dtsdldtd(4)`