test

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

第 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