test

共通デスクトップ環境 プログラマーズ・ガイド (ヘルプ・システム編)

パート III プログラマが行う作業

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

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

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

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

標準 Xt 活用例

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

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

注 -

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

一般ヘルプ・ダイアログ

一般ヘルプ・ダイアログには、トピック・ツリーとトピック表示領域の 2 つの表示領域があります。トピック・ツリーは、スクロールできるヘルプ・トピックのリストを提供しています。常にホーム・トピックのタイトルが 1 番目の項目になります。ユーザがタイトルを選択すると、そのタイトルに矢印 (=>) が付き、そのヘルプ情報がトピック表示領域に表示されます。図 9-1 に、一般ヘルプ・ウィンドウのトピック・ツリーとトピック表示領域を示します。現在のトピック「To select a palette」が表示されます。

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

図 9-1 一般ヘルプ・ダイアログ

Graphic

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

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

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

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

    DtCreateHelpDialog() 簡易関数

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

  3. ダイアログ内で発生するハイパーリンク・イベントを処理するためのコールバックを追加します (詳細は、「ハイパーリンク・イベントへの応答」を参照してください)。

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

例

次のコード・セグメントは、簡易関数を使用して一般ヘルプ・ダイアログを (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);

次の 2 つの呼び出しは、ダイアログにハイパーリンクとクローズ・コールバックを追加します。通常、関数 HyperlinkCB() と CLoseHelpCB はアプリケーションのどこかで宣言されます。

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

関連項目

簡易ヘルプ・ダイアログ

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

図 9-2 標準ボタンが 4 つある簡易ヘルプ・ダイアログ

Graphic

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

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

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

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

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

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

    DtCreateHelpQuickDialog() 簡易関数

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

  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);

次の 2 つの呼び出しは、ダイアログにハイパーリンクとクローズ・コールバックを追加します。通常、関数 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);

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

関連項目

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

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

第 10 章 ヘルプ要求への応答

この章では、ヘルプ・ダイアログ・ウィジェットのリソースの設定によってさまざまなヘルプ情報を表示する方法を説明します。

ヘルプの要求

アプリケーションの使用中にユーザがヘルプを要求したときは、どのヘルプ・トピックを表示するべきか、アプリケーション側で決定します。

コンテキストの検知

「バージョン」のヘルプ (通常は著作権のトピックが表示されます) など、特定の情報を明示的に要求するヘルプ要求もあります。ただしそれ以外のヘルプ要求では、コンテキストを要求します。つまり、アプリケーションにおけるユーザの現在のコンテキストに基づいて適切なヘルプ・トピックを選ぶ処理が必要です。

たとえばアプリケーションは、適切なヘルプ・トピックを判断するため、モードや設定のステータスをテストすることがあります。あるいは、入力フィールドの値をテストし、その値が有効でなければ詳細ヘルプを、有効であれば一般ヘルプを表示することもあります。

エントリ・ポイント

エントリ・ポイントとはヘルプ・ボリューム内の特定の場所のことで、通常はトピックの先頭です。アプリケーション内でヘルプを要求すると、エントリ・ポイントに直接アクセスできます。

設計者の見地から言えば、エントリ・ポイントはヘルプ・ボリュームの適切な場所に ID を指定することにより設定されます。プログラマの見地から言えば、ユーザがヘルプを要求できるようにし、特定のヘルプが要求されたときに適切な ID を使用することでエントリ・ポイントが作成されます。

ユーザがヘルプを要求する方法には次の 4 つがあります。

ヘルプ・トピックの表示

ヘルプが要求されると、アプリケーションが表示するヘルプ・トピックを決定します。次にヘルプ・ダイアログを (必要であれば) 作成し、管理して、ヘルプ・トピックを表示するのに適切なリソースを設定します。

ほとんどの要求については、アプリケーションのヘルプ・ボリュームの一部であるヘルプ・トピックが表示されます。しかしヘルプ・システムのヘルプ・ダイアログは、マニュアル・ページ、テキスト・ファイル、単一テキスト文字列を表示することもできます。

ヘルプ・システムのヘルプ・ダイアログは Xt イントリンシクスと OSF/Motif プログラミングに明示的に基づいているので、他のウィジェットと同じように、リソースを設定することによりヘルプ・ダイアログ内で値を変更できます。

DtNhelpType リソースは、表示するべき情報の種類を決定します。次のいずれかの値が設定されます。

上記の値は Help.h ファイルで定義されています。

関連項目

ヘルプ・トピックを表示するには

  1. ヘルプ・ダイアログを作成します。

  2. 次のようなヘルプ・ダイアログのリソースを設定します。

    DtNhelpType

    DtHELP_TYPE_TOPIC を設定します。

    DtNhelpVolume

    アプリケーションのボリューム名を設定します。

    DtNlocationId

    表示するトピックの ID を設定します。

    サイズやタイトルなど、その他の値も設定できます。

  3. XtManageChild() を使用してダイアログを管理します。

例

次のプログラム・セグメントは、ID である getting-started が付いたトピックを、ボリューム MyVolume に表示します。

ac = 0;
XtSetArg (al[ac], DtNhelpType,   DtHELP_TYPE_TOPIC);  ac++;
 XtSetArg (al[ac], DtNhelpVolume,  "MyVolume");         ac++;
 XtSetArg (al[ac], DtNlocationId,  "getting-started");  ac++;
 XtSetArg (al[ac], DtNcolumns,    40);                  ac++;
 XtSetArg (al[ac], DtNrows,       12);                  ac++;
 XtSetValues (helpDialog, al, ac);
 XtManageChild (helpDialog);

ヘルプ・ボリューム MyVolume が登録されていない場合、DtNhelpVolume の値を指定するためには、MyVolume.sdl ファイルへの絶対パスが必要です。

テキスト文字列を表示するには

  1. 簡易ヘルプ・ダイアログを作成します。

    一般ヘルプ・ダイアログも使用できますが、このダイアログの機能は文字列データにほとんど適用されないので、使用しないようにしてください。

  2. 次のようなヘルプ・ダイアログのリソースを設定します。

    DtNhelpType

    DtHELP_TYPE_DYNAMIC_STRING (行の折り返しを使用する場合) または DtHELP_TYPE_STRING (改行を有効にしたい場合) を設定します。

    DtNstringData

    表示する文字列を設定します。文字列のコピーは内部的に保持されるので、保存する必要はありません。

    サイズやタイトルなど、その他の値も設定できます。

  3. XtManageChild() を使用してダイアログを管理します。

例

次のプログラム・セグメントは、変数 descriptionString に格納された文字列を表示します。

ac = 0;
 XtSetArg (al[ac], DtNhelpType,   DtHELP_TYPE_DYNAMIC_STRING); ac++;
 XtSetArg (al[ac], DtNstringData, (char *)descriptionString);   ac++;
 XtSetValues (quickHelpDialog, al, ac);
 XtManageChild (quickHelpDialog);

ヘルプ・ダイアログはデータのコピーを自身で作成するので、文字列が不要になった場合はメモリを解放できます。

XtFree (descriptionString);

テキスト・ファイルを表示するには

  1. 簡易ヘルプ・ダイアログを作成するか、ダイアログ・キャッシュの 1 つを取り出します。

    一般ヘルプ・ダイアログも使用できますが、このダイアログの機能のほとんどが標準ヘルプ・トピックについてのみ有効なので、使用しないようにしてください。

  2. 次のようなヘルプ・ダイアログのリソースを設定します。

    DtNhelpType

    DtHELP_TYPE_FILE を設定します。

    DtNhelpFile

    表示するファイル名を設定します。アプリケーションの現在のディレクトリにファイルがない場合は、ファイルへのパスを指定してください。

    サイズやタイトルなど、その他の値も設定できます。特に幅はテキスト・ファイルの標準である 80 に設定します。

  3. XtManageChild() を使用してダイアログを管理します。

例

次のプログラム・セグメントは、ファイル /tmp/printer.list を表示します。ダイアログのサイズもテキスト・ファイルにより適応するように設定します。

ac = 0;
 XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_FILE);      ac++;
 XtSetArg (al[ac], DtNhelpFile,  "/tmp/printer.list");  ac++;
 XtSetArg (al[ac], DtNcolumns,  80);                    ac++;
 XtSetArg (al[ac], DtNrows,     20);                    ac++;
 XtSetValues (quickHelpDialog, al, ac);
 XtManageChild (quickHelpDialog);

マニュアル・ページを表示するには

  1. 簡易ヘルプ・ダイアログを作成します。

    一般ヘルプ・ダイアログも使用できますが、このダイアログの機能のほとんどが標準ヘルプ・トピックについてのみ有効なので、使用しないようにしてください。

  2. 次のようなヘルプ・ダイアログのリソースを設定します。

    DtNhelpType

    DtHELP_TYPE_MAN_PAGE を設定します。

    DtNmanPage

    マニュアル・ページ名を設定します。このリソースの値は、システムの man コマンドへ直接渡されます。したがって特定のセクションを指定するときは、通常 man コマンドを入力するときのように、セクション番号の前にマニュアル・ページ名を付けてください。

    サイズやタイトルなど、その他の値も設定できます。

  3. XtManageChild() を使用してダイアログを管理します。

例

次のプログラム・セグメントは、grep コマンドのマニュアル・ページを表示します。ダイアログのサイズもマニュアル・ページに適応するように設定します。

ac = 0;
 XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_MAN_PAGE);  ac++;
 XtSetArg (al[ac], DtNmanPage,   "grep");                ac++;
 XtSetArg (al[ac], DtNcolumns,  80);                     ac++;
 XtSetArg (al[ac], DtNrows,     20);                     ac++;
 XtSetValues (quickHelpDialog, al, ac);
 XtManageChild (quickHelpDialog);

ヘルプ・キー ([F1] キー) を使用可能にする

ヘルプ・キー機能は、すべての OSF/Motif マネージャ・ウィジェットとプリミティブ・ウィジェットに組み込まれています。ヘルプ・キーをアクティブにしたいウィジェットにヘルプ・コールバックを追加すると、ヘルプ・キーが使用可能になります。

アプリケーション内では、ヘルプに固有のエントリ・ポイントが必要なウィジェットすべてに、それぞれヘルプ・コールバックを追加してください。そのコールバックを呼び出すまで、ヘルプ・コールバック機能は自動的にウィジェット階層を (シェル・ウィジェットまで) 上ります。

ヘルプ・コールバックをマネージャ・ウィジェットに追加する場合、ヘルプ・キーを任意の子のために押すと、(子ウィジェットに独自のヘルプ・コールバックがなければ) マネージャのヘルプ・コールバックが呼び出されます。

ヘルプ・コールバックを追加するには

    XtAddCallback() 関数を次のように使用します。

XtAddCallback (
       Widget          widget,
       String          DtNhelpCallback,
       XtCallbackProc  HelpRequestCB,
       XtPointer       clientData );
widget

ヘルプ・キーをアクティブにする場所のウィジェット

HelpRequestCB()

ユーザがヘルプ・キーを押したときにヘルプ要求を処理するアプリケーションの関数

clientData

HelpRequestCB() 関数に渡すデータ。通常は表示するトピックを示します。

ユーザがヘルプ・キーを押すと、ウィジェットのヘルプ・コールバックが現在のキーボード・フォーカスと共に呼び出されます。ウィジェットにヘルプ・コールバックがない場合、ヘルプ・コールバックを持つ最も近い先祖のコールバックが呼び出されます。

ヘルプ・コールバックが見つからない場合は何も処理されません。この場合、ヘルプ・コールバックをアプリケーションの各シェルに追加するようにしてください。こうすると、ユーザのヘルプ要求が失われることがありません。

ヘルプ・コールバックをダイアログ・シェルに追加すると、自動的にダイアログの [ヘルプ] ボタンでヘルプ・コールバックを呼び出せるようになります。

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

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

[ヘルプ] メニューの提供

『共通デスクトップ環境 スタイル・ガイド』では、各メニュー・バーに [ヘルプ] メニューを含むことを推奨しています。[ヘルプ] メニューには、ユーザがアプリケーションでさまざまなオンライン・ヘルプにアクセスできるように多数のコマンドが入っています。

最も重要なコマンドは次のとおりです。

関連項目

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

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

便利な関数に 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;
     }
 }

第 11 章 ヘルプ・ダイアログのイベント処理

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

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

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

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

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

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

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

簡易ヘルプ・ボタン

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

関連項目

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

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

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

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

  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_WNIDOW です。

例

次の関数 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 はダイアログのクローズを処理するために指定したコールバック・プロシージャ名です。

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

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

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

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

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

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

例

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

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

関連項目

第 12 章 「ヘルプの使い方」の作成

この章では、ヘルプ・システムの機能とその使用方法を記述するヘルプ・ボリュームをアプリケーションに組み込む方法について説明します。このヘルプ・ボリュームは、ヘルプ・ダイアログ・ボックスの使い方に関するヘルプを提供します。

「ヘルプの使い方」の作成

「ヘルプの使い方」はヘルプ・システムの使用方法を通知します。特に、ハイパーリンクの使用、トピックのナビゲート、索引の使用、およびヘルプ・トピックの印刷などの作業について説明しています。通常は、「ヘルプの使い方」は Help4Help という名前の個別のヘルプ・ボリュームとして提供されます。

Help4Help ボリュームとそのソース・ファイルは、開発者用ツールキットに組み込まれます。デフォルト・ボリュームを使用するかアプリケーションの設計に合わせて変更できます。

アプリケーション・ヘルプの場合

アプリケーション特定のヘルプを記述する場合、アプリケーションのヘルプ・ダイアログに [ヘルプの使い方] を追加する方法が次の 2 つあります。

スタンドアロン・ヘルプの場合

スタンドアロン・ヘルプを記述する場合、すでにインストール済みで使用準備ができているヘルプビューア・プログラムを使用します。この場合、ヘルプビューアはデフォルトとして標準の Help4Help ボリュームにアクセスするので、「ヘルプの使い方」について心配する必要はありません。

「ヘルプの使い方」の検索方法

ヘルプ・システム (ヘルプビューアを含む) を使用する各アプリケーションは、「ヘルプの使い方」トピックのためにアクセスされるヘルプ・ボリュームを識別する helpOnHelpVolume リソースを持っています。ヘルプビューアの場合、このリソースは次のように設定されます。

DtHelpview*helpOnHelpVolume:  Help4Help

独自の「ヘルプの使い方」ボリュームを作成する場合、システムにインストールされる可能性のある別の「ヘルプの使い方」ボリュームと競合しないように固有の名前を付けるようにしてください。

アプリケーションの「ヘルプの使い方」へのアクセス

アプリケーションは「ヘルプの使い方」をサポートするために次の作業を実行します。

helpOnHelpVolume リソースを設定するには

    アプリケーションのデフォルトのリソース・ファイルに次のような 1 行を追加します。

       
App-class*helpOnHelpVolume:  volume

    App-class はアプリケーションのクラス名、volume はアクセスしたい「ヘルプの使い方」ボリューム名です。

    またアプリケーション内で、作成した各ヘルプ・ダイアログ helpOnHelpVolume リソースを設定します。

例

[ヘルプの使い方] コマンドを指定するには

  1. [ヘルプ] メニューに [ヘルプの使い方] というラベルのボタンを追加します。また、必要な起動コールバックを起動して、HelpRequestCB() 関数を呼び出します。

  2. HelpRequestCB() 関数にサポートを追加し、「ヘルプの使い方」を表示します。特に次の作業を実行します。

    • 簡易ヘルプ・ダイアログを作成します。

    • ダイアログのタイトルを「ヘルプの使い方」に設定します。

    • 「ヘルプの使い方」ボリュームのホーム・トピックを表示します。

    • 簡易ヘルプ・ダイアログを管理します。

例

次の行は、HelpRequestCB() 関数を呼び出す [ヘルプの使い方] というラベルのメニュー・ボタンを作成します。

/* Create the ` Using Help ...' button. */
labelStr = XmStringCreateLtoR ("Using Help ...",  XmSTRING_DEFAULT_CHARSET);
 ac = 0;
 XtSetArg (al[ac], XmNlabelString, labelStr);     ac++;
 button = XmCreatePushButtonGadget (parent, "usingHelpButton", al,  ac);
    XtManageChild (button);
    XmStringFree (labelStr);
    /* Add a callback to the button. */
   XtAddCallback (button,XmNactivateCallback,HelpRequestCB,
    USING_HELP);

USING_HELP は、ユーザがメニュー・ボタンを選択したときに HelpRequestCB() 関数に渡されるクライアント・データです。通常、アプリケーションのどこか (Help.h ファイルなど) で固有の整数として定義されています。

#define USING_HELP  47

HelpRequestCB() 関数の USING_HELP の処理方法を確認するには、次の「ヘルプの使い方」を表示するには」にある例を参照してください。

「ヘルプの使い方」を表示するには

  1. 簡易ヘルプ・ダイアログを作成します (またはキャッシュから取り出します)。

  2. ダイアログに「ヘルプの使い方」ボリュームのホーム・トピックを表示します。

「ヘルプの使い方」は一般ヘルプ・ウィンドウに表示できます。しかし、簡易ヘルプ・ダイアログのユーザ・インタフェースはもっと単純なので、簡易ヘルプ・ダイアログを使用してください。このダイアログは、通常「ヘルプの使い方」を必要とする新しいユーザでも簡単に使用できます。

例

次のプログラム・セグメントは、HelpRequestCB() 関数の一部です。通常、ユーザは、アプリケーションの [ヘルプ] メニューから [ヘルプの使い方] を選択するか簡易ヘルプ・ダイアログの [ヘルプ] ボタンを選択するため、USING_HELP 定数はその関数に渡されます。

次の例は、アプリケーションが [ヘルプの使い方] ダイアログを 1 つしか作成せず、そのウィジェット ID を onHelpDialog と呼ばれる変数に保持するものと仮定しています。

case USING_HELP:
   if (onHelpDialog == (Widget)NULL)
      {
         /* Get a quick help dialog for use as the ` help on help' dialog. */
         onHelpDialog = FetchHelpDialog (True);
 
        if (onHelpDialog == (Widget)NULL)
           /* We didn't get a dialog! Add your error handling code here. */
      }
 
   /* Set the proper volume and ID to display the home topic of
       the help on help volume. Also, set the dialog's title.   */
    ac = 0;   XtSetArg (al[ac], XmNtitle,  "Help On Help");     ac++;
    XtSetArg (al[ac], XmNhelpType,   DT_HELP_TYPE_TOPIC); ac++;
    XtSetArg (al[ac], XmNhelpVolume, "Help4Help");        ac++;
    XtSetArg (al[ac], XmNlocationId, "_hometopic");       ac++;
    XtSetValues (onHelpDialog, al, ac);
 
   /*  If the ` help on help' dialog is already managed, it might
        be in another workspace, so unmanage it.  */
    if (XtIsManaged (onHelpDialog))
      XtUnmanageChild (onHelpDialog);
 
   /* Manage the ` help on help' dialog. */
    XtManageChild (onHelpDialog);
 
   break;

HelpRequestCB() 関数の残りが構成される方法を確認するには、「ヘルプ・コールバックを追加するには」にある例を参照してください。

関連項目

独自の「ヘルプの使い方」ボリュームを記述する

独自の「ヘルプの使い方」ボリュームを作成する必要がある場合、既存の Help4Help ボリュームで開始し、必要な変更を行なってください。Help4Help ボリュームを記述するのに使用されるソース・ファイルはすべて、/usr/dt/dthelp/help4help/lang ディレクトリに用意されています。

インストールの重複を避けるには、「ヘルプの使い方」ボリュームに Help4Help 以外の名前を付けます。自分のプロダクトに固有の名前を付けてください。たとえば、アプリケーションのヘルプ・ボリュームが Netwapp の場合は、「ヘルプの使い方」ボリュームは NetwappH4H という名前にします。

必須のエントリ・ポイント

ヘルプ・ダイアログのコンテキスト・ヘルプを正しく動作させるには、「ヘルプの使い方」ボリュームに次のエントリ・ポイント (ID) を作成しなければなりません。(これらはすでに Help4Help ソース・ファイルにあります。)

ID  

トピック記述 

_hometopic

ヘルプ・システムの使い方に関するイントロダクションを表示します。このトピックは一般ヘルプ・ダイアログの [ヘルプ] メニューから [ヘルプの使い方] を選択するか、簡易ヘルプ・ダイアログの [F1] を押すと表示されます。(ID_hometopic は、<hometopic> 要素によって自動的に作成されます。)

_copyright

「ヘルプの使い方」ボリュームに関する商標とバージョン情報を表示します。このトピックは一般ヘルプ・ダイアログの [ヘルプ] メニューから [バージョン] を選択すると表示されます。(ID_copyright は、<copyright> 要素によって自動的に作成されます。)

history

[ヒストリ] ダイアログの使用方法を記述しているトピックを表示します。このトピックは、[ヘルプ] を選択するか [ヒストリ] ダイアログの [F1] を押すと表示されます。 

printing

[印刷] ダイアログの使用方法を記述しているトピックを表示します。このトピックは、[ヘルプ] を選択するか [印刷] ダイアログの [F1] を押すと表示されます。 

index-search

[索引検索] ダイアログの使用方法を記述しているトピックを表示します。このトピックは、[ヘルプ] を選択するか [索引検索] ダイアログの [F1] を押すと表示されます。 

volume-select

[検索ボリューム選択] ダイアログの使用方法を記述しているトピックを表示します。このトピックは、[ヘルプ] を選択するか [検索ボリューム選択] ダイアログの [F1] を押すと表示されます。 

Help4Help ソース・ファイルをコピーするには

  1. 次のようにコマンドを使用して、/usr/dt/dthelp/help4help/lang ディレクトリ全体を新しい作業ディレクトリ (new-dir) にコピーします。lang にはロケール名が入ります。

    cp -r /usr/dt/dthelp/help4help/lang new-dir

    これは new-dir を作成し、すべてのファイルとディレクトリをその中にコピーします。

  2. ファイル (読み取り専用としてコピーされる) の編集をできるようにするには、次のようにコマンドを使用してアクセス権を変更します。

     chmod -R u+w new-dir

Help4Help ボリュームは、これらのヘルプタグ・ソース・ファイルを使用します。

また、control ディレクトリも含まれており、ここでヘルプタグを実行して実行時のヘルプ・ファイルを作成します。グラフィック・ファイルは、control/graphics サブディレクトリに保存されます。

ヘルプタグを実行する前に Help4help.htg のファイル名が変更されていることを確認してください。「ヘルプの使い方」ボリューム名は、他の「ヘルプの使い方」ボリュームと重複しないように固有の名前でなければなりません。

例

次のコマンドは「ヘルプの使い方」ボリュームのコピーを作成し、そのファイルを書き込み可能にします。(通常は projects サブディレクトリはすでに存在します。)

cp -r /usr/dt/dthelp/help4help/C /users/dex/projects/NewHelp4Help
 chmod -R u+w /users/dex/projects/NewHelp4Help

実行時のヘルプ・ファイルの新しいバージョンを作成するには、最初にディレクトリ /usr/dt/bin が検索パス内にあることを確認します。次に、新規ディレクトリに移動して Help4Help.htg のファイル名を変更し、ヘルプタグを実行します。

cd /users/dex/projects/NewHelp4Help
mv Help4Help.htg NewH4H.htg
 dthelptag NewH4H

ヘルプタグ・ソフトウェアを実行すると、次のコマンドを使用して新しい「ヘルプの使い方」ボリュームを表示できます。

dthelpview -helpVolume NewH4H

第 13 章 インストール・パッケージの準備

この章では、アプリケーションのインストール・パッケージにあるヘルプ・ファイルについて説明します。また、アプリケーションがデスクトップに登録されるときにヘルプ・ファイルが処理される方法についても説明しています。

概要

最後の製品を準備する段階になったら、すべてのヘルプ・ファイルが適切に作成され、インストールされていることを確認しなければなりません。製品パッケージには、実行時のヘルプ・ファイル (volume.sdl) とそのグラフィック・ファイルの両方が入っています。さらに、フロントパネルのヘルプ・ビューアを使用してボリュームの表示を可能にするヘルプ・ファミリ・ファイルを作成できます。

オンライン・ヘルプの配布

オンライン・ヘルプは、アプリケーションに完全に統合されるか、スタンドアロン・ヘルプ・ボリュームとして提供されます。完全に統合されたヘルプにより、[ヘルプ] メニューか [ヘルプ] キーを使用してアプリケーションからヘルプ情報に直接アクセスできます。スタンドアロン・ボリュームは一方で、デスクトップのヘルプ・ビューアを使用してしか表示できません。

システム管理者は、アプリケーションが統合されたヘルプを提供しない場合や、カスタマイズされた環境で補足的なヘルプ・ボリュームが作成されない場合に、スタンドアロン・ヘルプ・ボリュームをデスクトップに追加するように選択できます。デスクトップにスタンドアロン・ボリュームをインストールする手順については、「スタンドアロン・ヘルプ」を参照してください。

インストール・パッケージの作成

インストール・パッケージには次のヘルプ・ファイルが入っています。

オンライン・ヘルプで使用されている実行時のヘルプ・ファイルとグラフィックは、インストール・パッケージに入っています。ヘルプ・ファミリ・ファイルは、統合されたアプリケーション・ヘルプのオプションです。しかし、アプリケーション・ヘルプをデスクトップのヘルプ・ビューアを使用してブラウズ可能にしたい場合は、ファミリ・ファイルを作成しなければなりません。スタンドアロン・ヘルプ・ボリュームを配布中の場合は、ヘルプ・ファミリ・ファイルを作成しなければなりません。「ヘルプ・ファミリを作成するには」を参照してください。

アプリケーションのヘルプ・ボリュームに実行リンクがある場合、設計者はアプリケーションのデフォルトのリソース・ファイルに実行別名を定義してください。このためには、実行別名でリンクを自動的に実行するヘルプ・システムのデフォルトの実行ポリシーを利用します。しかし、ヘルプ・ボリュームが別の情報ビューアを使用して独立したボリュームとして表示される場合、ヘルプ・システムは実行リンクが選択された時点で確認ダイアログボックスを表示します。

図 13-1 は、アプリケーションとそのヘルプ・ファイルの典型的なインストール・パッケージを示しています。ヘルプ・ファイルは、デフォルトの言語ディレクトリ (C がデフォルト) がある別の help サブディレクトリにグループ化されます。実行時のヘルプ・ファイル、ファミリ・ファイル、およびグラフィック・ファイルは、このディレクトリにあります。

図 13-1 アプリケーション・インストール・パッケージ

Graphic

アプリケーションが複数の言語でオンライン・ヘルプを提供する場合、各言語を格納するための language サブディレクトリを作成してください (language はユーザの LANG 環境変数に一致します)。たとえば、英語ユーザ・インタフェースとドイツ語ユーザ・インタフェースの両方を提供するアプリケーションは、英語には C、ドイツ語には german というように 2 つのサブディレクトリにそれぞれ対応するオンライン・ヘルプを保存します。

実行時のヘルプ・ファイル

ヘルプタグは単一の実行時のヘルプ・ファイル volume.sdl を作成します。ベース名 volume は volume.htg ファイルのベース名と同じです。ヘルプ・ビューアはマスタ・ヘルプ・ファイルに保存されている情報を使用し、関連付けられたグラフィック・ファイルにもアクセスします。

ヘルプタグ・ソフトウェアによって作成された volume.htg ファイルや追加のファイルを出荷する必要はありません。

グラフィック・ファイル

ヘルプ・ボリュームがグラフィックを使用している場合、イメージ・ファイルは便利なように通常別のディレクトリに保存されます。しかし、volume.htg ファイルと同じ場所に保存するように選択することも可能です。

実行時のヘルプ・ファイルには実際のグラフィック・イメージは入っていません。そのかわり、各グラフィック・ファイルの位置への「参照」が入っています。ヘルプタグを実行すると、dthelptag コンパイラはグラフィック・ファイルの相対パス名をヘルプ・ボリュームに組み込みます。

ヘルプ・ファイルがインストールされると、グラフィック・ファイルは実行時のファイルが作成されたときと同じ相対位置に位置付けられます。そうでない場合、ヘルプ・ボリュームはグラフィック・ファイルを位置付けることはできません。たとえば、グラフィック・ファイルが volume.htg ファイルより 1 つ下のレベルにある graphics という名前のサブディレクトリにある場合、インストール・パッケージはその相対位置を確保しておかなければなりません。グラフィック・ファイルは volume.sdl ファイルより 1 つ下のレベルにある graphics という名前のサブディレクトリに位置付けられなければなりません。

図 13-2 作成ディレクトリとインストール・パッケージの関係

Graphic

ヘルプ・ファミリ・ファイル

ヘルプ・ファミリ・ファイル (volume.hf) をオプションとして提供できます。ファミリ・ファイルには、ヘルプ・ボリュームについての簡単な記述と著作権情報があります。このファイルは、1 つ以上の関連のあるボリュームを 1 つの製品カテゴリにグループ化するのにも使用されます。

デスクトップ・ブラウザ・ボリュームからヘルプ・ボリュームへのアクセスを可能にしたい場合、インストール・パッケージにファミリ・ファイルを作成しなければなりません。ファミリ・ファイルを作成する方法については、「ヘルプ・ファミリを作成するには」を参照してください。

アプリケーションとそのヘルプの登録

デスクトップの統合ユーティリティ dtappintegrate は、インストールされたアプリケーション・ファイルと特定のデスクトップ・ディレクトリの間にシンボリック・リンクを作成することにより、アプリケーションとそのヘルプ・ファイルを登録します。アプリケーションの登録により、ヘルプ・システムが使用するディレクトリ検索パスにヘルプ・ファイルを確実に位置付けることができます。

登録により、ヘルプ・システムの重要な 2 つの機能が使用可能になります。

オンライン・ヘルプを登録すると、提供したヘルプにアクセスしやすくなります。設計者とプログラマにとっては、ボリュームの実際の位置を指定しなくても、ボリュームへの参照にはボリューム名だけを使用すればいいのでより簡単です。

1 つ以上のヘルプ・ボリュームがあるヘルプ・ファミリを登録する場合、フロントパネルの [ヘルプ・ビューア] からの一般的なブラウズにヘルプを使用できるようにします。これにより、アプリケーションを使用しないでアプリケーション固有のヘルプにアクセスできます。また、スタンドアロン・ヘルプを記述している場合は、この方法がヘルプにたどりつく唯一の方法です。

スタンドアロン・ヘルプ

アプリケーションのスタンドアロン・ヘルプ・ボリュームやカスタマイズされた環境はヘルプ・システムの開発者用キットを使用して作成できます。ヘルプ・ボリュームをデスクトップ・ブラウザ・ボリュームからアクセス可能にするには、システム管理者は実行時のヘルプ・ファイル、関連付けられたグラフィック、およびファミリ・ファイルを /etc/dt/appconfig/help/language ディレクトリにインストールしてください。

実行時のヘルプ・ファイルとそのグラフィック・ファイルは、ヘルプ・ボリュームが作成されたときと同じ相対位置にインストールされなければなりません。グラフィック・ファイルのインストールをレビューする方法については、「グラフィック・ファイル」を参照してください。

アプリケーションの登録時に発生すること

アプリケーションの登録により、app_root/dt/appconfig/help/language にある実行時のヘルプ・ファイルおよびファミリと、/etc/dt/appconfig/help/language ディレクトリの間にシンボリック・リンクが作成されます。

アプリケーションの登録手順の詳細は、『Solaris 共通デスクトップ環境 上級ユーザ及びシステム管理者ガイド』を参照してください。

ヘルプ・ボリュームの検索方法

ヘルプ・システムはデスクトップ検索パスを使用してヘルプ・ボリュームを位置付けます。ヘルプがアプリケーション内で要求されたり、ヘルプ・ボリュームがコマンド行に指定されたりする場合、ヘルプ・ボリュームは検索パス・ディレクトリのセットをチェックすることにより検索されます。いくつかの環境変数を変更して、ヘルプ・ボリューム のディレクトリ検索パスをコントロールできます。検索パスの指定の詳細は、『Solaris 共通デスクトップ環境 上級ユーザ及びシステム管理者ガイド』を参照してください。

製品準備チェックリスト

次のチェックリストは、製品が適切に準備されていることを確認するのに役立ちます。もちろん、ユーザが行うように製品をテストするのが一番いい方法です。

設計者の場合

  1. 最後のバージョンの実行時のヘルプ・ファイルが作成された。

    次の例は、実行時のファイルの作成の際に推奨するコマンドです。

       
dthelptag -clean volumedthelptag volume nomemo onerror=stop

    -clean オプションは、上記の dthelptag コマンドからファイルを削除します。nomemo オプションは、記述者のメモが表示されないようにします。onerror=stop オプションは、パーサ・エラーが発生した場合に処理を停止します。パーサ・エラーが発生したヘルプ・ボリュームを配布してはなりません。

  2. すべてのハイパーリンクをテストした。

    各ハイパーリンクは適切なトピックを表示し、正しいアクションを実行します。

  3. 実行別名が実行リンクに定義された。

    実行別名は、アプリケーションのアプリケーション・デフォルト・ファイルにあるリソースとして定義されます。実行別名は実行されるシェル・コマンドと名前とを関連付けます。ヘルプ・ボリュームで実行リンクを使用した場合は、アプリケーション開発者がこれらのリソースをアプリケーション・デフォルト・ファイルに追加するように調整してください。詳細は、「実行別名」を参照してください。

  4. すべてのグラフィックが受け入れ可能である。

    グラフィックは、カラー、グレースケール、およびモノクロ・ディスプレイでテストされました。

製品のインテグレータの場合

  1. 実行時のファイルがインストールされた。

  2. すべてのグラフィックが適切な位置にインストールされた。

    各グラフィック・ファイルは、ヘルプタグ・ソフトウェアが実行されたときに .htg ファイルとは相対的な位置にあった .sdl ファイルに対しても、同じ相対的な位置にインストールされなければなりません。

  3. ヘルプ・ボリュームが登録された。

    dtappintegrate スクリプトが、インストール・ディレクトリから登録ディレクトリにシンボリック・リンクを作成するために実行されました。

  4. 製品のファミリ・ファイルがインストールおよび登録された。

    ファミリ・ファイルは他のヘルプ・ファイルと共にインストールされます。dtappintegrate を実行すると、ファミリ・ファイルのシンボリック・リンクを作成します。ヘルプ・ボリュームのためにファミリ・ファイルを登録するのは任意です。しかし、ファミリ・ファイルを登録しないと、ヘルプ・ボリュームはフロントパネルの [ヘルプ・ビューア] からはアクセスできません。

プログラマの場合

  1. アプリケーションは、次の必須リソースに対して正しい値を設定している。

       

App-class*helpVolume:        volume
App-class*helpOnHelpVolume:  help-on-help-volume

    helpVolume リソースは、アプリケーションのためのヘルプ・ボリュームを識別します。helpOnHelpVolume は、ヘルプ・システムの使用に関するヘルプがあるヘルプ・ボリュームを識別します。

  2. 実行別名は、アプリケーションのデフォルトのリソース・ファイルにある。

    設計者は、アプリケーションのリソースとして実行別名を定義します。実行別名は、実行するシェル・コマンドと名前とを関連付けます。実行リンクがヘルプ・ボリュームで使用されていた場合は、追加の必要があるリソースを識別していることを設計者が確認するようにしてください。詳細は、「実行別名」を参照してください。

  3. アプリケーションが次のオプションのリソースに対して希望する値を設定している。

       
App-class*DtHelpDialogWidget*onHelpDialog*rows:     rows
App-class*DtHelpDialogWidget*onHelpDialog*columns:  columns
App-class*DtHelpDialogWidget*definitionBox*rows:    rows
App-class*DtHelpDialogWidget*definitionBox*columns: columns

    onHelpDialog リソースは、「ヘルプの使い方」を表示するのに使用される簡易ヘルプ・ダイアログのサイズをコントロールします。definitionBox リソースは、定義リンクに使用される簡易ヘルプ・ダイアログのサイズをコントロールします。

  4. アプリケーションは、デフォルトのフォント・リソースを使用するか、アプリケーションのデフォルトのリソース・ファイルにフォント・リソースを定義している。

    ほとんどの場合、アプリケーションはデフォルトのフォント・リソースを使用できます。しかし、カスタム・フォントが使用される場合、デフォルトのリソース・ファイルに定義されていなければなりません。サンプルのフォント・スキーマが /usr/dt/dthelp/fontschemes ディレクトリに用意されています。フォント・スキーマの詳細は、第 14 章「母国語のサポート」を参照してください。