[ 前のページ ] [ 次のページ ] [ 目次 ] [ 索引 ]

# 4 Helpウィジェットの使用

DECwindows for OpenVMSのアプリケーションはHelpウィジェットを使用することにより， ユーザからの補助の要求に応じて，一般情報およびコンテキスト依存情報を表示できます。 この章では，アプリケーションにHelpウィジェットを組み込む方法について説明します。 ここで説明するトピックは， 次のとおりです。

- Helpウィジェットの概要

- ヘルプ・ライブラリ情報

- Helpウィジェットの作成

- Helpウィジェットの使用

『OSF/Motifスタイル・ガイド(DECwindows 追補版)』(日本語)，『DECwindows Companion to the OSF/Motif Style Guide』(英語)で，Helpウィジェットの推奨する見た目と動作内容について説明しています。

注意
  DECwindowsヘルプ・システムを使用しても， ユーザの要求に応答じて一般情報およびコンテキスト依存情報を表示できます。DECwindows ヘルプ・システムについては，第5章で説明しています。

# 4.1 Helpウィジェットの概要

Helpウィジェットはモードなしのウィジェットであり，プログラマはこれを使用することによって， ユーザの問い合わせに応じて適切なコンテキスト依存ヘルプのテキストを表示させることができます。 図 4-1は，DECburgerサンプル・ プログラムから引用したサンプルのHelp ウィジェットを示しています。

### 図 4-1 サンプルのHelpウィジェット

Helpウィジェットは，プログラマの作成したアプリケーションがヘルプ機能を提供するために呼び出す， 独立したアプリケーションとして表示できます。Help ウィジェットを使用すると，1つ以上のヘルプ・ウィンドウを作成および管理して， ユーザに表示する最初のトピックを決定できます。 Helpウィジェットの動作はモードなしのため，アプリケーションは1つ以上のHelp ウィジェットを同時にサポートすることができます。

アプリケーションは，プログラマが選択したヘルプ・トピックに対するPush Button ウィジェット(またはガジェット)をもつ「ヘルプ」Pull-Down Menuウィジェットを呼び出すことができなければなりません。また，プッシュ・ ボタンのラベルは，利用できるヘルプの種類を示していなければなりません。

『OSF/Motifスタイル・ガイド』には， アプリケーションが該当する場合，「ヘルプ」Pull-Down Menuウィジェットに次のトピックを含めるように示されています。

- 「コンテキスト」-コンテキスト依存情報を提供する。

- 「ヘルプ」-アプリケーションのヘルプ機能の使用方法に関する情報を提供する。

- 「ウィンドウ」-そのウィンドウに関する概要を提供する。

- 「キー」-アプリケーションのキー，ニーモニック，キーボード・ アクセラレータの使用に関する情報を提供する。

- 「索引」-アプリケーション内のすべてのヘルプ情報に関して， 検索機能のある索引を提供する。Helpウィジェットは独自の検索機能を備えている。

- 「学習」-アプリケーションの学習がある場合，その学習へのアクセスを提供する。

- 「バージョン」-正式名やバージョン番号など，アプリケーションに関する情報を提供する。

アプリケーション固有のヘルプ・トピックも追加できます。

## 4.1.1 Helpウィジェットの呼び出し

ユーザは次の4通りの方法でHelpウィジェットを呼び出すことができます。

- ユーザが「ヘルプ」プルダウン・メニューでプッシュ・ボタンをクリックすると， アプリケーションはHelpウィジェットを呼び出して， ヘルプ・ウィンドウを作成します。アプリケーションはUILまたはツールキットのヘルプ・ ルーチンのいずれを使用しても，Helpウィジェットを呼び出すことができます。

- ユーザが「ヘルプ」プルダウン・メニューで「コンテキスト」プッシュ・ ボタンをクリックすると，アプリケーションはコンテキスト依存ヘルプ・ モードに入ります。次にユーザは特定のオブジェクトにポインタを移動して，MB1 をクリックします。アプリケーションはルーチンを呼び出して， そのオブジェクト，またはコンテキスト依存ヘルプが利用できる， そのオブジェクトの一番近い先祖に関するコンテキスト依存ヘルプを表示します。

  ヘルプ・コールバック・ルーチンを使用すれば，Helpウィジェットを作成( または既存のHelpウィジェットを変更)して，適切なヘルプ・ テキストが表示できます。詳しくは第4.7.1 項を参照してください。

- ユーザがあるオブジェクトに入力位置を移動してキーボードのHelp キーを押すと，Helpキーは入力フォーカスを持っているオブジェクトのコンテキスト依存ヘルプを表示します。 ただし，そのオブジェクトではコンテキスト依存ヘルプを使用できない場合は， コンテキスト依存ヘルプが利用できる一番近い先祖のコンテキスト依存ヘルプを表示します。XmLabel ウィジェットのような入力フォーカスを受け付けないウィジェットについては， ユーザがHelpキーを使用して， コンテキスト依存ヘルプを生成することはできません。

- ユーザがCommand Windowウィジェットでヘルプ・トピック・コマンド文字列をタイプします。 このメカニズムをサポートするためには， アプリケーションにCommand Windowウィジェットを組み込んでいなければなりません。

アプリケーションの開発者として，プログラマはどのヘルプの呼び出し方法をサポートするかを決定しなければなりません。DECwindows のほとんどのアプリケーションは，Help ウィジェットの呼び出し方法として，メニュー・ バーで「ヘルプ」オプションをクリックする方法と，コンテキスト依存ヘルプを使用する方法をサポートしています。

## 4.1.2 Helpウィジェットの用語

この章では表 4-1に定義する用語を使用して，Help ウィジェットについて説明します。

### 表 4-1 Helpウィジェットの用語

用語 | 定義
--- | ---
Help ウィジェット | そのウィジェットを構成するすべてのモジュールの総称。
ヘルプ・ウィンドウ | すべてのヘルプ情報が入っているウィンドウ。各Help ウィジェットにつき1つのヘルプ・ウィンドウがある。ヘルプ・ディスプレイはヘルプ・ ウィンドウと同意語である。
ヘルプ・セッション | アプリケーションの実行中に起こるすべてのヘルプの会話( 要求，応答など)。複数のHelpウィジェットから構成される場合がある。

# 4.2 ヘルプ・ライブラリ情報

UNIXおよびWindows NTシステムのいずれもライブラリアン・ユーティリティを持っていません。 これらのシステムでは，ヘルプ・ウィジェットは.HLP ファイル・ディレクトリを読み込みます。

この節では，Helpウィジェットでヘルプ・ライブラリを使用する方法について説明します。 ライブラリアン・ユーティリティについては，『VMS Librarian Utility Manual』を参照してください。

Helpウィジェットを作成するとき，Helpウィジェット作成ルーチンにヘルプ・ ライブラリ指定を渡します。Helpウィジェットはこの指定を使用して， ヘルプ・ファイルの検索と読み込みを行います。DECwindows for OpenVMSアプリケーションのヘルプ・ライブラリは，従来のVMSヘルプ・ライブラリです。 次のようなコマンドを使用して，ヘルプ・ライブラリを作成できます。

         $ LIBRARY/HELP/CREATE DECBURGER.HLB DECBURGER.HLP

Helpウィジェットには，ヘルプ・ライブラリとそのタイプを指定するために使用する2 つのリソースがあります。DXmNlibrarySpecリソースはヘルプ・ ライブラリのファイル指定を指定します。ヘルプ・ライブラリはHLB という省略時のファイル・タイプを持ち，入力ファイルのファイル・ タイプが省略されたときにはHLBに設定します。

DXmNlibraryTypeリソースは，DXmTextLibraryというあらかじめ定義された値を持ちます。

Helpウィジェットはこれらのリソースを使用して，ヘルプ・トピック・データベースの位置とタイプを識別します。 一度Helpウィジェットを呼び出すと， 選択したヘルプ・ライブラリ内でしかナビゲートできません。

HelpウィジェットにはDXmNcacheHelpLibraryリソースで指定するヘルプ・ ライブラリ・キャッシュがあります。DXmNcacheHelpLibraryリソースは， ヘルプ・ライブラリのテキストを，Helpウィジェットのキャッシュ・メモリに格納するかどうかを指定する論理値の属性です。TRUE の場合，ライブラリは最初にオープンされるときに初期化され， アプリケーションが終了するまでキャッシュ・ メモリに格納されます。

DXmNcacheHelpLibraryがFALSEの場合は，テキストはキャッシュ・メモリに格納されません。 省略時の設定はFALSEです。

## 4.2.1 ヘルプ・ライブラリ・モジュール

ヘルプ・ライブラリに挿入するファイルは，プログラムまたはテキスト・ エディタを使用して作成するテキスト・ファイルです。各ヘルプ入力ファイルには，1 つ以上のモジュールを入れることができます。各モジュールにはキー1 からキー9までの番号が付いた，関連するキーのグループが入っています。 各キーはモジュール内の階層レベルを表しています。

ライブラリアン・ユーティリティは，モジュール名としてキー1の名前を格納します。 キー2からキー9までの名前は，キー1の名前に関連するサブトピックを識別します。HLP ファイルの保守を容易にするため，最上位のヘルプ・ トピックをキー1の名前と関連付けることをお勧めしますが，そうしなければならないわけではありません。

### 4.2.1.1 ヘルプ・ライブラリ・モジュールのアクセス

アプリケーションはキー1の名前，またはモジュール内のどのキーからでも， そのモジュールをアクセスすることができます。たとえば， 「ウィンドウ」，「バージョン」，「ヘルプ」という最上位トピックを持つ「ヘルプ」Push Button ウィジェットがある場合，ヘルプ・ ライブラリをAPPLICATION.HLPという1つのファイルとして保持し， APPLICATION.HLBというOpenVMSヘルプ・ライブラリを作成することもできます。APPLICATION.HLP ファイルは各最上位トピックに対し，キー1の名前によって識別される別個のモジュールを含んでいます。 また，複数のHLP ファイルにヘルプ・ライブラリ・モジュールを保持することもできます。

ユーザが「ウィンドウ」のトピックについてヘルプを要求すると，アプリケーションはPush Button ウィジェットのアクティベート・コールバックから， ユーザが概要のヘルプを要求したことを判断します。すると，アプリケーションはHelp ウィジェットを作成し，DXmNfirstTopicリソースを通して， 正しいヘルプ・トピックを識別する文字列をHelpウィジェットに渡します。 この文字列はキー1の名前またはモジュール内の別のキーを識別します。

Helpウィジェットはキー名の階層を使用して，ヘルプ・トピックを見つけます。 たとえば，キー3の名前で識別されるヘルプ・トピックを直接アクセスしたい場合には， キー3の名前へのパスを構成するキー1およびキー2 の名前も指定しなければなりません。

Helpウィジェットは指定されたライブラリを検索し，文字列によって定義されているモジュールを探して， そのテキストを表示します。文字列がキー1 の名前を識別すると，概要モジュール内のすべてのキー2のサブエントリが， 追加トピックとして自動的に表示されます。

次に，ユーザがキー2のサブエントリについてヘルプを要求すると，Help ウィジェットはキー2のテキストを表示し，追加トピックとしてキー3のサブエントリを表示する， というように続きます。

### 4.2.1.2 ヘルプ・ライブラリのキー名の指定

ヘルプ・ライブラリのキー名を指定する方法は2通りあります。

- DXmNfirstTopicでヘルプ・トピックのキー名を直接指定できます。 この方法の欠点は，DXmNfirstTopicで指定したキー名がヘルプ・ ライブラリにおけるキー名と一致しなければならないことです。 多数のウィジェットについてヘルプをサポートしている場合， 一致させることは保守の面から困難です。

- リソース名としてキー名を指定できます。リソース名をヘルプ・ トピックのキー名にマップするUILモジュールを作成してください。 ヘルプ・トピックのキー名を変更すれば，アプリケーションのコードを変更する必要がありません。

## 4.2.2 OpenVMSヘルプ・ライブラリの強化

HelpウィジェットにはOpenVMSライブラリアン・ユーティリティに対する拡張機能がいくつかあります。 これらの拡張機能によって，Helpウィジェットはより高度な検索機能を持ち， 従来のOpenVMSヘルプ・トピックにおけるHelp ウィジェット・コマンドの形式(特殊なテキスト行)をとります。 これらコマンドの形式は次のとおりです。

         =name operand(s)

次の構文規則は，すべてのコマンドに適用されます。

- コマンドはヘルプ・トピックにおけるテキストの最初の行でなければならない。

- コマンド行の最初の文字は等号(=)でなければならない。

- コマンド名は等号のすぐ後に続かなければならない。

- コマンド名は大文字と小文字を区別せず，また省略できない。

- コマンド・オペランドの前には1つ以上のスペースが必要である。

- 行の残りの部分はコマンド・オペランドである。

OpenVMSライブラリアン・ユーティリティに対する拡張機能について，表 4-2 に説明します。

### 表 4-2 OpenVMSライブラリアン・ユーティリティの拡張機能

コマンド名 | 説明
--- | ---
=TITLE | 大文字と小文字を区別するタイトルを，ヘルプ・ トピックに関連付けることができる。このタイトルはトピックが識別されている状況で表示される。 たとえば，Overview of the Help Widget。 タイトルが与えられてない場合には，ヘルプ・ライブラリのトピック・キーがトピック・ タイトルになる。Helpウィジェットの「検索」メニューを使用すると， ユーザはキーワードとタイトルで検索できる。
=KEYWORD | 大文字と小文字を区別する1 つ以上のキーワードを，ヘルプ・トピックに関連付けることができる。 複数のキーワードを指定する場合，個々のキーワードはコンマまたは1 つ以上のスペースで区切らなければならない。Helpウィジェットの「検索」メニューを使用すると， ユーザはキーワードとタイトルで検索できる。
=NOSEARCH | 特定のトピックに関して，タイトルとキーワードでの検索操作が使用できない。
=INCLUDE | 1つのヘルプ・ライブラリ内のモジュール間で，ヘルプ・トピックを共有できる。INCLUDE コマンドのオペランドは，ヘルプ・トピックのキー名である。 ヘルプ・トピックのキー名についての詳しい説明は第4.6節を参照。 取り込まれたトピックのタイトルは， 追加トピックとして自動的に追加される。

例 4-1はDECBURGER.HLPヘルプ・ ファイルの一部を示しています。DECBURGER.HLP ファイルは単なる一例であるため， 推奨するヘルプ・ファイルの内容とスタイルについては『OSF/Motifスタイル・ ガイド(DECwindows 追補版)』(日本語)，『DECwindows Companion to the OSF /Motif Style Guide』(英語)を参照してください。

### 例 4-1 サンプルのヘルプ・ファイル

    【1】
    1 overview
    【2】
    =Title Overview of the Help Widget
    【3】
    =Keyword overview
    【4】
    =Include programming creating create_help_widget

     A help widget is a modeless widget that allows you
     to display appropriate, context-sensitive help text
     in response to a user query.   The help widget can
     be viewed as an independent application that your
     application calls to provide help functions.

     The help widget creates and manages one or more
     help windows and determines the first topic to be
     displayed to the user.

    【5】
    2 functions_1
    =Title Using the help widget
    =Keyword overview functions
     To use the help widget, you perform the following
     steps:

     1. Use the VMS Librarian Utility (LIBRARIAN) to
        create a help library.

     2. Create a Help menu bar item for your
        application.  The Help menu item should be
        located at the right of the menu bar.  If the
        menu bar is wider than a line, the Help menu
        item should be located at the bottom right.

    1 about
    =Title About the Help Widget
    =Keyword about
    =Include programming creating create_help_widget

     This topic provides version
     information.

    1 onhelp
    =Title Help Widget On Help
    =Keyword on-help
    =Include programming creating create_help_widget

     This topic provides help-on-using-help
     information.

    1 menu_bar
    =Title Menu Bar Context Sensitive Help
    =Keyword menu

    1 file_menu
    =Title File Menu Context Sensitive Help
    =Keyword file

    1 edit_menu
    =Title Edit Menu Context Sensitive Help
    =Keyword edit

    1 not_implemented
    =Title Not Yet Implemented
    =Keyword

    1 order_menu
    =Title Order Menu Context Sensitive Help
    =Keyword order

    1 order
    =Title Order Context Sensitive Help
    =Keyword order
    =Include programming creating create_help_widget

     Order menu context-sensitive help

    2 burgers
    =Title Burgers For Us
    =Keyword burger

    3 burgers_rare
    =Title Burgers For Us
    =Keyword burger rare

    3 burgers_medium
    =Title Burgers Medium For Us
    =Keyword burger medium

    3 burgers_well
    =Title Burgers Well For Us
    =Keyword burger well

       .
       .
       .

    1 options
    =Title Help on Custom Colors
    =Keyword options

    1 print
    =Title Help on Print Order
    =Keyword print

    1 programming
    =Title Programming Help
    =Keyword proramming

     Programming help.

    2 creating
    =Title Creating a Help widget
    =Keyword programming

     Creating a help widget.

    3 create_help_widget
    =Title Creating a Help widget
    =Keyword programming

     Programming help for creating
     a help widget.

    1 glossary
    =Title Help Widget Glossary
    =Keyword glossary
    =Include programming creating create_help_widget

     This topic provides glossary
     information.

       .
       .
       .

1. キー1のモジュールの名前はoverviewです。プログラマは文字列 overviewをHelpウィジェットに渡します。すると， Helpウィジェットはヘルプ・ライブラリを検索してこの名前のモジュールを探し出し， そのテキストを表示します。1つのモジュールは別のキー1 名，またはファイル終端レコードのいずれかによって終了します。

2. 「ウィンドウ」トピックとしてHelpウィジェットが表示するタイトルは Overview of the Help Widgetです。

3. Helpウィジェットの検索機能を使用して検索するキーワード・ トピックの名前は overviewです。

4. プログラミング・モジュールから取り込まれるトピック・ キーの名前は programming creating create_help_widgetです。=INCLUDE タグによって識別されるキーのタイトルは，追加トピックとして表示されます。

5. Overviewモジュールにおけるキー2のサブエントリの名前は functions_1です。追加トピックとして，functions_ 1サブエントリが表示されます。

# 4.3 Helpウィジェットの構成要素

Helpウィジェットは，サブウィジェットと呼ばれる子ウィジェットを組み込むように， あらかじめ構成されているポップアップ・ダイアログ・ ボックスです。この機能は必ず実現する必要があります。図 4-2 はHelpウィジェットの構成要素を示しています。

### 図 4-2 Helpウィジェットの構成要素

# 4.4 Helpウィジェットの見た目の変更

次のHelpウィジェットのリソースを使用すると，Helpウィジェットの見た目を変更することができます。

- XmNbuttonFontList

- XmNlabelFontList

- XmNtextFontList

- DXmNcols

- DXmNrows

- DXmNdefaultPosition

たとえばDXmNcolsリソースは，Helpウィジェットによって表示されるヘルプ・ テキストの幅を文字数で指定します。省略時の値は言語によって異なり， アメリカ英語の場合は55文字です。

次のUILコードはDXmNcolsリソースの値を50桁に減らします。

         object main_help : DXmHelpDialog
                     {
                     arguments
                        {
                        DXmNapplicationName = compound_string("Help Example");
                        DXmNglossaryTopic   = compound_string("glossary");
                        DXmNoverviewTopic = compound_string("overview");
                        DXmNcols  = 50;
                        };

                     };

Helpウィジェットの見た目のリソースについては，『日本語DECwindows Motif for OpenVMS拡張機能説明書』(日本語)，『DECwindows Extensions to Motif』(英語)で説明しています。

## 4.4.1 Helpウィジェットのラベルとニーモニックの変更

『日本語DECwindows Motif for OpenVMS拡張機能説明書』(日本語)，『DECwindows Extensions to Motif』(英語)で説明しているHelpウィジェットのラベル・リソースを使用すれば，Help ウィジェットのラベルを変更できます。

たとえばDXmNapplicationNameリソースは，Helpウィジェットの「ヘルプ」タイトル・ バーで使用されるアプリケーション名を指定します。省略時の設定はNULL です。

次のUILコードはDXmNapplicationNameリソースを"Help on Help Example"に設定します。

         object main_help : DXmHelpDialog
                     {
                     arguments
                        {
                        DXmNapplicationName = compound_string("Help Example");
                        DXmNglossaryTopic   = compound_string("glossary");
                        DXmNoverviewTopic = compound_string("overview");
                        };
                     };

ニーモニック・リソースを使用すれば，ユーザがHelpウィジェットのメニュー項目をアクティブ化するために押すキーを変更できます。 たとえば， DXmNhelpLabelMnemリソースは，ユーザが「ヘルプ」プルダウン・メニューをアクティブ化するために(MB1 をクリックする代わりに)押すことができるキーを指定します。 省略時の設定は文字Uです。

次のUILコードはDXmNhelpLabelMnemリソースを"H"に設定します。

         object main_help : DXmHelpDialog
                     {
                     arguments
                        {
                        DXmNapplicationName = compound_string("Help Example");
                        DXmNglossaryTopic   = compound_string("glossary");
                        DXmNoverviewTopic = compound_string("overview");
                        DXmNhelpLabelMnem = keysym("H");
                        };
                     };

Helpウィジェットのニーモニック・リソースについては『日本語DECwindows Motif for OpenVMS拡張機能説明書』(日本語)，『DECwindows Extensions to Motif』(英語)で説明しています。

Helpウィジェットのラベルおよびニーモニック・リソースを変更するもっとも一般的な理由は， 各国語対応のためです。

## 4.4.2 Helpウィジェットのメッセージ

Helpウィジェットはメッセージを使用して，ユーザにステータス情報を提供します。Help ウィジェットのリソースを使用すれば，これらのメッセージのテキストを変更できます。Help ウィジェットのメッセージ・リソースについては『日本語DECwindows Motif for OpenVMS拡張機能説明書』(日本語)，『DECwindows Extensions to Motif』(英語)に説明があります。実際のメッセージでは，変数!CS が適切なコンパウンド・ストリングで置き換えられていることに注意してください。

たとえば，次のUILコードはDXmNbadlibMessageリソースの値を， "Couldn't open library !CS"から"TEST_HELP.HLB is missing"に変更します。

         object main_help : DXmHelpDialog
                     {
                     arguments
                        {
                        DXmNapplicationName = compound_string("Help Example");
                        DXmNglossaryTopic   = compound_string("glossary");
                        DXmNoverviewTopic = compound_string("overview");
                        DXmNlibrarySpec  = compound_string("test_help.hlb");
                        DXmNbadlibMessage = compound_string("TEST_HELP.HLB is missing");
                        };

                     };

# 4.5 Helpウィジェットのコールバック

Helpウィジェットは表 4-3に示すコールバックをサポートします。

### 表 4-3 Helpウィジェットのコールバック

コールバック | 説明
--- | ---
DXmNunmapCallback | Helpウィジェットがアンマップされると呼び出される1 つまたは複数のコールバック・ルーチン。このコールバック・ ルーチンについて，条件はUnmapである。省略時の設定はNULL 。Helpウィジェットはユーザがヘルプ・セッションを終了すると自動的に自分自身の管理を解除するため，DXmNunmapCallback コールバックがこれを行なう必要はない。DXmNunmapCallback コールバックを使用すると， ユーザがヘルプ・セッションを終了するときに，ほかの機能を実行できる。
DXmNmapCallback | Helpウィジェットがマップされると呼び出される1つまたは複数のコールバック・ ルーチン。省略時の設定はNULLである。

# 4.6 Helpウィジェットのトピックの指定

表 4-4に説明しているHelpウィジェットのリソースを使用すると，Help ウィジェットのトピックを指定できます。

サブキー名によって識別するヘルプ・トピックを指定する場合は，そのサブキー名へのパスを構成するキー名も指定しなければなりません。 キー名は1 つ以上のスペースで区切ります。

たとえば，次のようなモジュールがあるとします。 1 programming
2 creating
3 create_help_widget

Helpウィジェットにおける最初のトピックとしてcreate_help_widgetというキー3 のヘルプ・テキストを表示したい場合には，コンパウンド・ストリング" programming creating create_help_widget" を渡します。

### 表 4-4 Helpウィジェットのトピック・ リソース

リソース | 説明
--- | ---
DXmNfirstTopic | 表示する最初のヘルプ・トピックを指定する。 DXmNfirstTopicリソースが指定されていない(NULLに設定されている) 場合，Helpウィジェットは追加トピックのリスト・ボックスに，レベル1 のトピックのリストをもつ空のウィンドウを表示する。 DXmNfirstTopicを使用してコンテキスト依存ヘルプを指定する方法については， 第4.7.1項を参照。
DXmNoverviewTopic | 表示する概要(Overview) トピックを指定する。概要トピックは，「表示」メニューから「概要へ」メニュー項目を選択すると表示される。 第4.2節で説明したように，アプリケーションは DXmNoverviewTopicリソースを使用して，Help ウィジェットにOverviewモジュールのキー名を識別する文字列を渡す。Overview は通常，キー1名である。
DXmNglossaryTopic | 表示する用語集(Glossary) トピックを指定する。アプリケーションはDXmNglossaryTopicリソースを使用して，Help ウィジェットにGlossaryモジュールのキー名を識別する文字列を渡す。Glossary は通常，キー1名である。 ヌル文字列(省略時)を渡すと，「表示」プルダウン・メニューに「用語集を表示」メニュー項目が表示されない。 アプリケーションが用語ヘルプをサポートしない場合には， DXmNglossaryTopicをNULLに設定する。

# 4.7 Helpウィジェットの使用

この節では，Helpウィジェットを使用するための，プログラミング上の一般的な注意事項について説明します。

Helpウィジェットを使用する際のもっとも基本的なアプローチは，まずHelp ウィジェットを作成して，ヘルプ・ウィンドウが表示されるよう管理し， ユーザがヘルプを終了したら，アンマップ・コールバック・ルーチンを使用して， そのウィジェットを破壊することです。ただし，ウィジェットが破壊されるとき， サイズ変更などのヘルプ・ウィンドウに対する変更は失われます。

アプリケーションがHelpウィジェットを破壊してから再作成する場合，アプリケーションはそのHelp ウィジェットの作成をオーバヘッドとみなします。 ただし，ヘルプ・ライブラリはHelpウィジェットによって最初にオープンされるときに初期化され， アプリケーションが終了するまでキャッシュ・ メモリに格納されます。Helpウィジェットがアプリケーションに代わってヘルプ・ ライブラリを初期化すると，そのライブラリはアプリケーションを再起動するまで， 再び初期化されることはありません。

好ましいアプローチは，一度Helpウィジェットを作成し，ユーザがヘルプを要求するたびにその同じHelp ウィジェットを使用することです。これは，DXmNfirstTopic リソースで新しい最初のトピックを指定(XtSetValues ルーチンの使用)し，ヘルプ・ウィンドウが表示されるようにそのウィジェットを管理(XtManageChild ルーチンの使用)することによって行います。

注意
  アプリケーションはまだアクティブなウィジェットを再使用してはなりません。Help ウィジェットはモードなしであるため， ユーザはHelpウィジェットがアクティブであってもアプリケーションに戻り， もう一度Helpを呼び出すことができます。このような状況では， アプリケーションは新規のHelpウィジェットを作成しなければなりません。

  Helpウィジェットがアクティブかどうかを判断する方法の1つは，そのウィジェットが管理されているかどうかを調べることです。Help ウィジェットはユーザがヘルプ・ セッションを終了すると，自動的に自分自身の管理を解除します。 このため，Helpウィジェットがすでに管理されている場合には，Help ウィジェットの新規のインスタンスを作成しなければなりません。

Helpウィジェットを使用するには，次の手順を実行します。

1. VMSライブラリアン・ユーティリティを使用して，ヘルプ・ライブラリを作成する。 詳しい説明については第4.2節を参照。

2. アプリケーションに「ヘルプ」メニュー・バー項目を作成する。 『OSF/Motifスタイル・ ガイド』のガイドラインに準拠させるため，Menu Barウィジェットのmenu_help_widget リソースを使用して，「ヘルプ」メニュー項目をメニュー・ バーの右端に配置する。Menu Barウィジェットが自動改行して複数行になる場合には， 「ヘルプ」メニュー項目をメニュー・ バーの右下に配置する。

3. 「コンテキスト」，「ウィンドウ」，「バージョン」，「ヘルプ」などの項目を持つ「ヘルプ」Pull-Down Menu ウィジェットを作成する。

   特定の「ヘルプ」メニュー項目をサポートしないアプリケーションでは， 「ヘルプ」Pull-Down Menuウィジェットにその項目を含んでいてはならない。

4. Pull-Down Menuウィジェットの「ヘルプ」ボタンを作成する。 「ヘルプ」Pull-Down Menuウィジェットの各トピックに対して，1つのPush Button ウィジェットを作成する。Push Buttonウィジェットは， ボタンを押すと呼び出されるルーチンに関連付けられている。

5. 表 4-5のいずれかのウィジェット作成ルーチンを使用して，Help ウィジェットのインスタンスを作成する。

   ### 表 4-5 Helpウィジェット作成ルーチン

   UILオブジェクト・タイプ | DXmHelpDialogオブジェクト・ タイプ識別子を使用して，UILモジュールにHelpウィジェットを作成する。
   ツールキット・ルーチン | DXmCreateHelpDialogルーチンを使用して，Helpウィジェットを作成する。

6. オプションとして，Helpウィジェットがアンマップされると呼び出されるコールバック・ ルーチンを指定する。

## 4.7.1 コンテキスト依存ヘルプ

コンテキスト依存ヘルプでは，アプリケーションはヘルプ階層を上位レベルから下位レベルへ順番に進むのではなく， 現在のトピックに関するヘルプを直接提示します。 ユーザは必要な情報を見つけるために，ヘルプのいくつかの層をナビゲートしなくてもすみます。

XmPrimitiveまたはXmManagerウィジェット・クラスのサブクラスであるすべてのウィジェットは， XmCR_HELPという条件でヘルプ・コールバックをサポートします。 その他のウィジェットでもヘルプ・コールバックをサポートすることはできます。 アプリケーションはこのヘルプ・コールバックを使用して， ヘルプ・コールバック・ルーチンとヘルプを付与したいウィジェットを関連付けることにより， コンテキスト依存ヘルプを実現します。

ツールキットにはDXmHelpOnContextというルーチンがあり，アプリケーションはこのルーチンを使用してコンテキスト依存ヘルプ・ モードへ入ることができます。

注意
  『OSF/Motifスタイル・ガイド』に， ダイアログ・ボックス内では，コンテキスト依存ヘルプをダイアログ・ ボックス全体として付与するように示されています。最初のヘルプ枠をダイアログ・ ボックスの概要とし，ダイアログ・ボックスの各オブジェクトについては追加トピックとして示します。

  『OSF/Motifスタイル・ガイド』の勧告に準拠するため， ヘルプ・コールバックはダイアログ・ボックス自身にのみ付与し， ダイアログ・ボックス内のオブジェクトに関して付与してはなりません。DXmHelpOnContext ルーチンは，関連付けられたヘルプ・ コールバック・ルーチンを持つウィジェットが見つかるまでウィジェットに一番近い先祖を探すため， ユーザはダイアログ・ボックス内のどこでクリックしても， そのダイアログ・ボックスに関するコンテキスト依存ヘルプを得ることができなければなりません。

例 4-5に，ヘルプ・コールバック・ ルーチンの例(sens_help_proc) を示します。

この節の以降の部分では，コンテキスト依存ヘルプを実現する方法について説明します。

### 4.7.1.1 UILによる「コンテキスト」プッシュ・ ボタンの作成

例 4-2は，「ヘルプ」プルダウン・ メニューの「コンテキスト」プッシュ・ ボタンを作成する方法を示しています。

### 例 4-2 UILにおける「コンテキスト」プッシュ・ ボタン

       .
       .
       .

    object help_menu_entry : XmCascadeButton {
                arguments {
                    XmNlabelString = k_help_label_text;
                    XmNmnemonic = keysym("H");
                    };
                controls {
                    XmPulldownMenu help_menu;
                    };
                callbacks
                    {
                    XmNhelpCallback = procedure sens_help_proc(k_help_help);
                    };
                };

    object help_menu : XmPulldownMenu
                {
                controls
                    {
                    XmPushButton help_sensitive;
                    XmPushButton help_window;
                    XmPushButton help_version;
                    XmPushButton help_onhelp;
                    };
                callbacks
                    {
                    XmNhelpCallback = procedure sens_help_proc(k_help_help);
                    };
                };

    object help_sensitive : XmPushButton
                {
                arguments
                    {
                    XmNlabelString = k_sensitive_label_text;
                    XmNmnemonic = keysym("C");
                    };
                callbacks
                    {
             【1】XmNactivateCallback = procedure activate_proc (k_help_sensitive);
                  XmNhelpCallback = procedure sens_help_proc(k_sensitive_help);
                    };
                };

       .
       .
       .

1. ユーザが「コンテキスト」プッシュ・ボタンをクリックすると， コンテキスト依存ヘルプ・モードに入るためのルーチンをアクティベート・ コールバックが呼び出します。「コンテキスト」プッシュ・ ボタンには，コンテキスト依存ヘルプ・コールバックもあります。

### 4.7.1.2 コンテキスト依存ヘルプ・モードに入る

「コンテキスト」プッシュ・ボタンのアクティベート・コールバックは， 例 4-3に示すように，コンテキスト依存ヘルプ・ モードに入るためのルーチンを呼び出します。DECburgerのすべてのプッシュ・ ボタンは，activate_procルーチンへコールバックします。 ただし，アプリケーションは「コンテキスト」プッシュ・ボタンから， コンテキスト依存ヘルプのコールバックを直接呼び出すこともできます。

### 例 4-3 DXmHelpOnContextルーチンの呼び出し

       .
       .
       .
    static void activate_proc(w, tag, reason)
        Widget              w;
        int                 *tag;
        XmAnyCallbackStruct *reason;
    {
        int      widget_num = *tag;       /* Convert tag to widget number. */
        int      i, value;
        XmString topic;

        switch (widget_num) {
        .
        .
        .

       【1】case k_help_sensitive:
                tracking_help();
                break;

       .
       .
       .
    static void tracking_help()

    {
     【2】DXmHelpOnContext(toplevel_widget, FALSE);
    }

       .
       .
       .

1. 「コンテキスト」プッシュ・ボタンを識別するタグを指定してactivate_proc ルーチンを呼び出すと，コンテキスト依存ヘルプ・ルーチン(tracking_help) が呼び出されます。

2. DXmHelpOnContextはポインタ・カーソルをヘルプ・カーソルに変更し( このときアプリケーションはコンテキスト依存ヘルプ・モードです) ，ユーザがコンテキスト依存ヘルプが必要なオブジェクトへポインタ・ カーソルを移動してMB1をクリックするのを待ちます。

   選択したウィジェットがヘルプ・コールバックを持つ場合，そのヘルプ・ コールバックが呼び出されます。選択したウィジェットがヘルプ・ コールバックを持たない場合は，ヘルプ・コールバックが見つかるか， またはウィジェット階層の一番上に到達するまで，そのウィジェットの先祖を検索します。

   アプリケーションの最上位のウィジェットの名前と，検索処理をそのウィジェットに制限したいかどうかを示す論理値を指定して， DXmHelpOnContextルーチンが呼び出されます。

   ヘルプ・ポインタ・カーソルをアプリケーションの最上位のウィジェットに制限すると( 論理値TRUE)，ユーザはヘルプ・ポインタ・カーソルをメイン・ ウィンドウの境界外に移動することはできません。つまり， ユーザは最上位ウィジェットの境界を越えるポップアップ・ウィジェットに関して， コンテキスト依存ヘルプを得られないということです。

   ヘルプ・ポインタ・カーソルをアプリケーションの最上位ウィジェットに制限しなければ( 論理値FALSE)，ユーザはアプリケーションのいずれのウィジェットに関しても， コンテキスト依存ヘルプを得ることが可能になります。

   前述の例はヘルプ・ポインタ・カーソルを制限していません。

## 4.7.2 ヘルプ・コールバックの指定

アプリケーションはXmNhelpCallbackリソースを使用して，ヘルプ・コールバック・ ルーチンと，ヘルプを付与したいウィジェットを関連付けます。

アプリケーションはコールバックのtag引数を使用すると，アプリケーション固有のデータを与えることができます。 たとえば例 4-4に示すように，DECburger アプリケーションのウィジェットは， ヘルプ・コールバック・ルーチンに，ヘルプ・ トピックを指定するコンパウンド・ストリング値を与えます。

ヘルプ・システム・コールバックの文字列の値については，第5章で説明します。

### 例 4-4 ヘルプ・コールバックの指定- UILモジュール

       .
       .
       .
    !Compound strings to use for context-sensitive help callbacks

    value
            k_order_help            :  compound_string ("order");
            k_print_help            :  compound_string ("print");
            k_options_help          :  compound_string ("options");
            k_menu_bar_help         :  compound_string ("menu_bar");
            k_file_help             :  compound_string ("file_menu");
            k_edit_help             :  compound_string ("edit_menu");
            k_order_menu_help       :  compound_string ("order_menu");
            k_help_help             :  compound_string ("help");
            k_sensitive_help        :  compound_string ("sensitive");
            k_onhelp_help           :  compound_string ("onhelp");
            k_about_help            :  compound_string ("about");
            k_overview_help         :  compound_string ("overview");
            k_nyi_help              :  compound_string ("not_implemented");

    !String value to use for the Help System callback

    value
            helpsys_order_help            :  'order';

       .
       .
       .

    object
        s_menu_bar : XmMenuBar {

            arguments {
                XmNorientation = XmHORIZONTAL;
                XmNmenuHelpWidget = XmCascadeButton help_menu_entry;
            };

            controls {
                XmCascadeButton file_menu_entry;
                XmCascadeButton edit_menu_entry;
                XmCascadeButton order_menu_entry;
                XmCascadeButton options_menu_entry;
                XmCascadeButton help_menu_entry;
            };
            callbacks {
                MrmNcreateCallback = procedure create_proc (k_menu_bar);
           【1】XmNhelpCallback    = procedure sens_help_proc(k_menu_bar_help);
            };
        };
       .
       .
       .

1. ヘルプ・コールバック・ルーチンはこのコンパウンド・ストリングを使用して， DXmNfirstTopicリソースを設定します。

例 4-5はDECburgerアプリケーションのヘルプ・ コールバック・ルーチンが，DXmNfirstTopicリソースを設定するために作成ルーチン(create_help) を呼び出す方法を示しています。create_help についての詳細は，例 4-7を参照してください。

### 例 4-5 ヘルプ・コールバックの指定- Cモジュール

       .
       .
       .
    static void sens_help_proc(w, tag, reason)
        Widget              w;
        XmString            *tag;
        XmAnyCallbackStruct *reason;
    {
         create_help(tag);
    }

       .
       .
       .

# 4.8 UILによるHelpウィジェットの作成

例 4-6は，DECburgerサンプル・ アプリケーションにHelp ウィジェットを実現するコードを示しています。 DECburgerアプリケーションの完全なUILソース・コードはDECW$EXAMPLES に入っています。

### 例 4-6 UILによるHelpウィジェットの実現

       .
       .
       .
    !module DECburger_demo

    module decburger
            version = 'v1.1.1'
            names = case_sensitive

            objects = {
                    XmSeparator = gadget ;
                    XmLabel = gadget ;
                    XmPushButton = gadget ;
                    XmToggleButton = gadget ;
                    }

    procedure
            toggle_proc   (integer);
            activate_proc (integer);
            create_proc   (integer);
            scale_proc    (integer);
            list_proc     (integer);
            exit_proc     (string);
            show_hide_proc (integer);
            pull_proc       (integer);
       【1】sens_help_proc (compound_string);
            help_system_proc (string);
            ok_color_proc   ();
            apply_color_proc ();
            cancel_color_proc ();

    value
        k_create_order          : 1;
        k_order_pdme            : 2;
        k_file_pdme             : 3;
        k_edit_pdme             : 4;
        k_nyi                   : 5;
        k_ok                    : 6;  ! NOTE: ok, apply, reset, cancel
        k_apply                 : 7;  ! must be sequential
        k_reset                 : 8;
        k_cancel                : 9;
        k_cancel_order          : 10;
        k_submit_order          : 11;
        k_order_box             : 12;
        k_burger_min            : 13;
        k_burger_rare           : 13;
        k_burger_medium         : 14;
        k_burger_well           : 15;
        k_burger_ketchup        : 16;
        k_burger_mustard        : 17;
        k_burger_onion          : 18;
        k_burger_mayo           : 19;
        k_burger_pickle         : 20;
        k_burger_max            : 20;
        k_burger_quantity       : 21;
        k_fries_tiny            : 22;
        k_fries_small           : 23;
        k_fries_medium          : 24;
        k_fries_large           : 25;
        k_fries_huge            : 26;
        k_fries_quantity        : 27;
        k_drink_list            : 28;
        k_drink_add             : 29;
        k_drink_sub             : 30;
        k_drink_quantity        : 31;
        k_total_order           : 32;
        k_burger_label          : 33;
        k_fries_label           : 34;

        k_drink_label           : 35;
        k_menu_bar              : 36;
        k_file_menu             : 37;
        k_edit_menu             : 38;
        k_order_menu            : 39;
        k_help_pdme             : 40;
        k_help_menu             : 41;
        k_help_overview         : 42;
        k_help_about            : 43;
        k_help_onhelp           : 44;
        k_help_sensitive        : 45;
        k_print                 : 46;
        k_options_pdme          : 47;
        k_options_menu          : 48;
        k_create_options        : 49;
        k_fries_optionmenu      : 50;

    value
            k_decburger_title               : 'DECburger: Order Entry Box';
            k_nyi_label_text                : 'This feature is not yet implemented.';
            k_file_label_text               : 'File';
                k_print_label_text          :   'Print Order..';
                k_exit_label_text           :   'Exit';
            k_edit_label_text               : 'Edit';
                k_cut_dot_label_text        :   'Cut';
                k_copy_dot_label_text       :   'Copy';
                k_paste_dot_label_text      :   'Paste';
                k_clear_dot_label_text      :   'Clear';
                k_select_all_label_text     :   'Select All';
            k_order_label_text              : 'Order';
                k_cancel_order_label_text   :   'Cancel Order';
                k_submit_order_label_text   :   'Submit Order';
            k_options_label_text            : 'Options';
                k_options_color_label_text  :   'Background Color...';
       【2】k_help_label_text               : 'Help';
                k_sensitive_label_text      :   'On Context';
                k_overview_label_text       :   'On Window';
                k_about_label_text          :   'On Version';
                k_onhelp_label_text         :   'On Help';
            k_hamburgers_label_text         : 'Hamburgers';
                k_rare_label_text           :   'Rare';
                k_medium_label_text         :   'Medium';
                k_well_done_label_text      :   'Well Done';
                k_ketchup_label_text        :   'Ketchup';
                k_mustard_label_text        :   'Mustard';
                k_onion_label_text          :   'Onion';
                k_mayonnaise_label_text     :   'Mayonnaise';
                k_pickle_label_text         :   'Pickle';
                k_quantity_label_text       : 'Quantity';
            k_fries_label_text              : 'Fries';
                k_size_label_text           : 'Size';
                k_tiny_label_text           :   'Tiny';
                k_small_label_text          :   'Small';
                k_large_label_text          :   'Large';
                k_huge_label_text           :   'Huge';
            k_drinks_label_text             : 'Drinks';
                k_0_label_text              : ' 0';
                k_drink_list_text           :
                        string_table (      'Apple Juice',
                                            'Orange Juice',
                                            'Grape Juice',
                                            'Cola',
                                            'Punch',
                                            'Root beer',
                                            'Water',
                                            'Ginger Ale',
                                            'Milk',
                                            'Coffee',
                                            'Tea');
                k_drink_list_select         : string_table('Apple Juice');
            k_ok_label_text                 : 'OK';
            k_apply_label_text              : 'Apply';
            k_reset_label_text              : 'Reset';
            k_cancel_label_text             : 'Cancel';

    !Compound strings to use for context-sensitive help callbacks
    【3】
    value
            k_order_help            :  compound_string ("order");
            k_print_help            :  compound_string ("print");
            k_options_help          :  compound_string ("options");
            k_menu_bar_help         :  compound_string ("menu_bar");
            k_file_help             :  compound_string ("file_menu");
            k_edit_help             :  compound_string ("edit_menu");
            k_order_menu_help       :  compound_string ("order_menu");
            k_help_help             :  compound_string ("help");
            k_sensitive_help        :  compound_string ("sensitive");
            k_onhelp_help           :  compound_string ("onhelp");
            k_about_help            :  compound_string ("about");
            k_overview_help         :  compound_string ("overview");
            k_nyi_help              :  compound_string ("not_implemented");

       .
       .
       .
    【4】
    object
           main_help : DXmHelpDialog {
               arguments
                    {
                    DXmNapplicationName = compound_string("Help Example");
                    DXmNglossaryTopic   = compound_string("glossary");
                    DXmNoverviewTopic   = compound_string("overview");
                    DXmNlibrarySpec     = compound_string("decburger.hlb");
                    };

                };

       .
       .
       .
    object
        s_menu_bar : XmMenuBar {

            arguments {
                XmNorientation         = XmHORIZONTAL;
           【5】XmNmenuHelpWidget  = XmCascadeButton help_menu_entry;
            };

            controls {
                XmCascadeButton        file_menu_entry;
                XmCascadeButton        edit_menu_entry;
                XmCascadeButton        order_menu_entry;
                XmCascadeButton        options_menu_entry;
           【6】XmCascadeButton        help_menu_entry;
            };
            callbacks {
                MrmNcreateCallback     = procedure create_proc (k_menu_bar);
           【7】XmNhelpCallback    = procedure sens_help_proc(k_menu_bar_help);
            };
        };

       .
       .
       .
    【8】
    object help_menu_entry : XmCascadeButton {
                arguments {
                    XmNlabelString     = k_help_label_text;
                    XmNmnemonic        = keysym("H");
                    };
                controls {
                    XmPulldownMenu     help_menu;
                    };
                callbacks
                    {
                    XmNhelpCallback    = procedure sens_help_proc(k_help_help);
                    };
                };
    【9】
    object help_menu : XmPulldownMenu
                {
                controls
                    {
                    XmPushButton       help_sensitive;
                    XmPushButton       help_window;
                    XmPushButton       help_version;
                    XmPushButton       help_onhelp;
                    };

                callbacks
                    {
                    XmNhelpCallback    = procedure sens_help_proc(k_help_help);
                    };
                };

    object help_sensitive : XmPushButton
                {
                arguments
                    {
                    XmNlabelString     = k_sensitive_label_text;
                    XmNmnemonic        = keysym("C");
                    };
                callbacks
                    {
            【10】XmNactivateCallback  = procedure activate_proc (k_help_sensitive);
                  XmNhelpCallback      = procedure sens_help_proc(k_sensitive_help);
                    };
                };

    object help_onhelp : XmPushButton
                {
                arguments
                    {
                    XmNlabelString     = k_onhelp_label_text;
                    XmNmnemonic        = keysym("H");
                    };
                callbacks
                    {
                    XmNactivateCallback = procedure activate_proc (k_help_onhelp);
                    XmNhelpCallback     = procedure sens_help_proc(k_onhelp_help);
                    };
                };

    object help_version : XmPushButton
                {
                arguments
                    {
                    XmNlabelString      = k_about_label_text;
                    XmNmnemonic         = keysym("V");
                    };
                callbacks
                    {
                    XmNactivateCallback = procedure activate_proc (k_help_about);
                    XmNhelpCallback     = procedure sens_help_proc(k_about_help);
                   };
                };

    object help_window : XmPushButton
                 {
                 arguments
                    {
                    XmNlabelString      = k_overview_label_text;
                    XmNmnemonic         = keysym("W");
                    };
                 callbacks
                    {
                    XmNactivateCallback = procedure activate_proc (k_help_overview);
                    XmNhelpCallback     = procedure sens_help_proc(k_overview_help);
                    };
                };

       .
       .
       .

1. DECburgerのウィジェットはsens_help_procプロシージャを呼び出して， コンテキスト依存ヘルプを実現します。DECburgerはコールバックのtag 引数で，使用するコンパウンド・ストリング値を割り当てます。

2. 「ヘルプ」プッシュ・ボタン・ラベルのためのコンパウンド・ ストリング値の宣言。ウィジェットのラベルに値を使用すると，インターフェイスの変更が容易になります。 ラベル定義をすべてモジュールの初めに配置すると， あとでラベルを変更したいとき，容易に見つけることができます。

3. ヘルプ・コールバックのためのコンパウンド・ストリング値の宣言。 すべての定義をモジュールの初めに配置すると，あとでコンパウンド・ ストリング値を変更したいとき，容易に見つけることができます。

4. Helpウィジェットのインスタンスを作成します。この例はDXmNapplicationName ，DXmNglossaryTopic，DXmNoverview， DXmNlibrarySpecというHelpウィジェットのリソースに値を割り当てます。

5. メニュー・バーがXmNmenuHelpWidgetリソースを取り込みます。 このリソースは「ヘルプ」メニュー項目をメニュー・バーの右端に配置します。Menu Bar ウィジェットが自動改行して複数行になる場合には， 「ヘルプ」メニュー項目をメニュー・バーの右下に配置します。

6. メニュー・バーは「ヘルプ」メニュー項目のカスケード・ボタンを制御します。

7. sens_help_procプロシージャはメニュー・バーのコンテキスト依存ヘルプを実現します。 プログラマはこのコールバックを使用して， 特定のトピックに関するコンテキスト依存ヘルプを表示します。

8. 「ヘルプ」メニュー項目は「ヘルプ」プルダウン・メニューを制御するカスケード・ ボタンです。

9. 「ヘルプ」プルダウン・メニューは，コンテキスト依存ヘルプ， 「概要」，「バージョン」，「ヘルプ」メニュー項目のPush Buttonガジェットを含んでいます。

10. アクティブ化されると，「ヘルプ」Push Buttonガジェットは識別のための整数値を指定して，activate_proc コールバック・ルーチンを呼び出します。activate_proc コールバックはこの整数値(コールバックのtag 引数)を使用して，どのウィジェットから呼び出されたかを判断します。

# 4.9 Helpウィジェットの実現- C言語モジュール

例 4_7と例 4-8 は，例 4-9で作成されるHelp ウィジェットを実現するC言語のコードを示しています。DECburgerアプリケーションの完全なC ソース・コードは，DECW$EXAMPLESに入っています。

### 例 4-7 Helpウィジェットの実現- C言語モジュール

       .
       .
       .
    #include <stdio.h>                              /* For printf and so on. */

    #include   <Xm/text.h>
    #include   <Mrm/mrmappl.h>
    【1】
    #include  <DXm/dxmhelpb.h>
    #include   <DXm/dxmprint.h>
    #include   <X11/xlib.h>
    #include   <X11/xutil.h>
    #include   <DXm/dxmcolor.h>
    #include   <DXm/DECspecific.h>
    #include   <sys$library/DECw$Cursor.h>

    /*
     * These numbers are matched with corresponding numbers in the DECburger
     * UIL module.
     */

    #define k_create_order          1
    #define k_order_pdme            2
    #define k_file_pdme             3
    #define k_edit_pdme             4
    #define k_nyi                   5
    #define k_ok                    6          /* NOTE: ok, apply, reset, cancel */
    #define k_apply                 7          /* must be sequential */
    #define k_reset                 8
    #define k_cancel                9
    #define k_cancel_order          10
    #define k_submit_order          11
    #define k_order_box             12
    #define k_burger_min            13
    #define k_burger_rare           13
    #define k_burger_medium         14
    #define k_burger_well           15
    #define k_burger_ketchup        16
    #define k_burger_mustard        17
    #define k_burger_onion          18
    #define k_burger_mayo           19
    #define k_burger_pickle         20
    #define k_burger_max            20
    #define k_burger_quantity       21
    #define k_fries_tiny            22
    #define k_fries_small           23
    #define k_fries_medium          24
    #define k_fries_large           25
    #define k_fries_huge            26
    #define k_fries_quantity        27
    #define k_drink_list            28
    #define k_drink_add             29
    #define k_drink_sub             30
    #define k_drink_quantity        31
    #define k_total_order           32
    #define k_burger_label          33
    #define k_fries_label           34
    #define k_drink_label           35
    #define k_menu_bar              36
    #define k_file_menu             37
    #define k_edit_menu             38
    #define k_order_menu            39

    【2】
    #define k_help_pdme             40
    #define k_help_menu             41
    #define k_help_overview         42
    #define k_help_about            43
    #define k_help_onhelp           44
    #define k_help_sensitive        45
    #define k_print                 46
    #define k_custom_pdme           47
    #define k_custom_menu           48
    #define k_create_custom         49
    #define k_fries_optionmenu      50

    #define k_max_widget            50

    #define MAX_WIDGETS (k_max_widget + 1)

    #define NUM_BOOLEAN (k_burger_max - k_burger_min + 1)

    #define k_burger_index   0
    #define k_fries_index    1
    #define k_drinks_index   2
    #define k_index_count    3

    /*
     * Global data
     */

    static Cursor watch = NULL;

    static Widget
        toplevel_widget = (Widget)NULL,     /* Root widget ID of our application. */
        main_window_widget = (Widget)NULL,  /* Root widget ID of main MRM fetch   */
        widget_array[MAX_WIDGETS],          /* Place to keep all other widget IDs */
    【3】main_help_widget = (Widget)NULL,   /* Primary help widget             */
    【4】help_widget[MAX_WIDGETS],           /* Array of help widgets              */
        print_widget = (Widget)NULL,        /* Print widget                       */
        color_widget = (Widget)NULL;        /* Color Mix widget                   */

    static Screen   *the_screen;            /* Pointer to screen data*/
    static Display  *the_display;           /* Pointer to display data */
    static XColor  savecolor;

    static int help_num = 0;                /* make sure it starts zero */

       .
       .
       .

    /*
     * Forward declarations
     */

    static void s_error();
    static void get_something();
    static void set_something();

    static void activate_proc();
    static void create_proc();
    static void list_proc();
    static void exit_proc();
    static void pull_proc();
    static void scale_proc();
    static void show_hide_proc();
    static void show_label_proc();
    static void toggle_proc();
    【5】
    static void create_help();
    static void tracking_help();
    static void sens_help_proc();
    static void help_system_proc();
    static void create_print();
    static void activate_print();
    static void create_color();
    static void ok_color_proc();
    static void apply_color_proc();
    static void cancel_color_proc();
    static void xmstring_append();
    static void start_watch();
    static void stop_watch();

    /* The names and addresses of things that Mrm. has to bind.  The names do
     * not have to be in alphabetical order.  */

    static MrmRegisterArg reglist[] = {
        {"activate_proc", (caddr_t) activate_proc},
        {"create_proc", (caddr_t) create_proc},
        {"list_proc", (caddr_t) list_proc},
        {"pull_proc", (caddr_t) pull_proc},
        {"exit_proc", (caddr_t) exit_proc},
        {"scale_proc", (caddr_t) scale_proc},
        {"show_hide_proc", (caddr_t) show_hide_proc},
        {"show_label_proc", (caddr_t) show_label_proc},
        {"toggle_proc", (caddr_t) toggle_proc},
    【6】{"sens_help_proc", (caddr_t) sens_help_proc},
        {"help_system_proc", (caddr_t) help_system_proc},
        {"cancel_color_proc", (caddr_t) cancel_color_proc},
        {"apply_color_proc", (caddr_t) apply_color_proc},
        {"ok_color_proc", (caddr_t) ok_color_proc}
    };

    static int reglist_num = (sizeof reglist / sizeof reglist [0]);
    static font_unit = 400;

    /*
     * OS transfer point.  The main routine does all the one-time setup and
     * then calls XtMainLoop.
     */

    static String fallback =
              "DECburger.title: DECburger\nDECburger.x: 100\nDECburger.y: 100";

    unsigned int main(argc, argv)
        unsigned int argc;                  /* Command line argument count. */
        char *argv[];                       /* Pointers to command line args. */
    {
        XtAppContext app_context;

        MrmInitialize();                    /* Initialize MRM before initializing
                                            /* the X Toolkit. */

    【7】DXmInitialize();                 /* Initialize DXm widgets */

        /* If we had user-defined widgets, we would register them with Mrm.here. */

        /* Initialize the X Toolkit. We get back a top level shell widget. */

          toplevel_widget = XtAppInitialize(
              &app_context,                   /* App. context is returned */
              "DECburger",                    /* Root class name. */
               NULL,                          /* No option list. */
               0,                             /* Number of options. */
               &argc,                         /* Address of argc */
               argv,                          /* argv */
               &fallback,                     /* Fallback resources */
               NULL,                          /* No override resources */
               0);                            /* No override resources */

        /* Open the UID files (the output of the UIL compiler) in the hierarchy*/

        if (MrmOpenHierarchy(
            db_filename_num,                    /* Number of files. */
            db_filename_vec,                    /* Array of file names.  */
            NULL,                               /* Default OS extenstion. */
            &s_MrmHierarchy)                    /* Pointer to returned MRM ID */
          !=MrmSUCCESS)
            s_error("can't open hierarchy");

        init_application();

        /* Register the items MRM needs to bind for us. */

        MrmRegisterNames(reglist, reglist_num);

        /* Go get the main part of the application. */
        if (MrmFetchWidget(s_MrmHierarchy, "S_MAIN_WINDOW", toplevel_widget,
          &main_window_widget, &dummy_class) != MrmSUCCESS)
            s_error("can't fetch main window");

        /* Save some frequently used values */
        the_screen = XtScreen(toplevel_widget);
        the_display = XtDisplay(toplevel_widget);

        /* If it's a color display, map customize color menu entry */

        if ((XDefaultVisualOfScreen(the_screen))->class == TrueColor
            ||  (XDefaultVisualOfScreen(the_screen))->class == PseudoColor
            ||  (XDefaultVisualOfScreen(the_screen))->class == DirectColor
            ||  (XDefaultVisualOfScreen(the_screen))->class == StaticColor)

              XtSetMappedWhenManaged(widget_array[k_custom_pdme], TRUE);

        /* Manage the main part and realize everything.  The interface comes up
         * on the display now. */

        XtManageChild(main_window_widget);
        XtRealizeWidget(toplevel_widget);

       .
       .
       .

        /* Sit around forever waiting to process X-events.  We never leave
         * XtAppMainLoop. From here on, we only execute our callback routines. */
        XtAppMainLoop(app_context);
    }

    /*
     * One-time initialization of application data structures.
     */

    static int init_application()
    {
        int k;
        int i;

        /* Initialize the application data structures. */
        for (k = 0; k < MAX_WIDGETS; k++)
            widget_array[k] = NULL;
        for (k = 0; k < NUM_BOOLEAN; k++)
            toggle_array[k] = FALSE;

        /* Initialize CS help widgets. */

    【8】for (i = 0; i < MAX_WIDGETS; i++)
            help_widget[i] = NULL;

       .
       .
       .

1. Helpウィジェットのリソースを定義するために，UNIXではDXmHelpB.h ，OpenVMSではDXMHELPB.Hファイルを取り込みます。

2. ヘルプに関係するウィジェットに整数値を割り当てて，コールバック・ ルーチンがどのウィジェットから呼び出されたかを識別できるようにします。 この整数値は，UNIXではdecburger.uil，OpenVMSではDECBURGER.UIL ファイルに割り当てられた値と一致していなければなりません。

3. main_help_widget変数をNULLに初期化して，無効なデータが入らないようにします。

4. HelpウィジェットのIDを格納するために使用するMAX_NUMBERウィジェットの配列を宣言します。

5. ヘルプ・ルーチンの宣言を転送します。

6. sens_help_procコールバックはUILから呼び出されるため， 引数リストに登録されます。DECburgerは，MRMルーチンのMrmRegisterNames によってあとで使用できるように，コールバック・ ルーチンの名前とアドレスを格納します。

7. DECが提供する拡張ツールキットのウィジェットを初期化します。

8. Helpウィジェットの配列をNULLに初期化して，無効なデータが入らないようにします。

### 例 4-8 Helpウィジェットの実現- C言語モジュール

       .
       .
       .

    /*
     * All push buttons in this application call back to this routine.  We
     * use the tag to tell us what widget it is, then react accordingly.
     */

    static void activate_proc(w, tag, reason)
        Widget               w;
        int                  *tag;
        XmAnyCallbackStruct  *reason;
    {
        int         widget_num = *tag;              /* Convert tag to widget number. */
        int         i, value;
        XmString    topic;

        switch (widget_num) {
            case k_nyi:

                /* The user activated a 'not yet implemented' push button.  Send
                 * the user a message. */
                if (widget_array[k_nyi] == NULL) {
                     /* The first time, fetch from  the data base. */
                    if (MrmFetchWidget(s_MrmHierarchy, "nyi", toplevel_widget,
                      &widget_array[k_nyi], &dummy_class) != MrmSUCCESS) {
                        s_error("can't fetch nyi widget");
                    }
                }
                /*  Put up the message box saying 'not yet implemented'. */
                XtManageChild(widget_array[k_nyi]);
                break;

            case k_submit_order:
                /*  This would send the order off to the kitchen. In this case,
                 *  we just pretend the order was submitted. */
                clear_order();
                break;

       .
       .
       .

        【1】case k_help_overview:
                topic = XmStringCreateLtoR("overview",XmSTRING_ISO8859_1);
                create_help(topic);
                XmStringFree(topic);
                break;

              case k_help_about:
                topic = XmStringCreateLtoR("about",XmSTRING_ISO8859_1);
                create_help(topic);
                XmStringFree(topic);
                break;

              case k_help_onhelp:
                topic = XmStringCreateLtoR("onhelp",XmSTRING_ISO8859_1);
                create_help(topic);
                XmStringFree(topic);
                break;

              case k_help_sensitive:
                tracking_help();
                break;

             case k_print:
                create_print();
                break;

             case k_create_custom:
                create_color();
                break;

             default:
                break;
        }
    }

       .
       .
       .

    /*
     * Context sensitive help callback.
     */
    【2】
    static void sens_help_proc(w, tag, reason)
        Widget              w;
        XmString           *tag;
        XmAnyCallbackStruct *reason;
    {
         create_help(tag);
    }

    /* Creates an instance of the help widget for the push buttons in the help
    pull-down menu and for context-sensitive help callbacks. */
    【3】
    static void create_help (help_topic)
        XmString   help_topic;

    {
        Arg             arglist[1];

        start_watch();
        if (!main_help_widget) {
            if (MrmFetchWidget (s_MrmHierarchy, "main_help", toplevel_widget,
                                &main_help_widget, &dummy_class) != MrmSUCCESS)
            s_error ("can't fetch help widget");
        }

        if (XtIsManaged(main_help_widget)) {

            if (MrmFetchWidget (s_MrmHierarchy, "main_help", toplevel_widget,
                                &help_widget[help_num], &dummy_class) != MrmSUCCESS)
            s_error ("can't fetch help widget");

            XtSetArg (arglist[0], DXmNfirstTopic, help_topic);
            XtSetValues (help_widget[help_num], arglist, 1);
            XtManageChild(help_widget[help_num]);
            help_num++;
            return;
        }

        XtSetArg (arglist[0], DXmNfirstTopic, help_topic);
        XtSetValues (main_help_widget, arglist, 1);
        XtManageChild(main_help_widget);
        stop_watch();
    }

       .
       .
       .

1. 「ヘルプ」プルダウン・メニューの「ウィンドウ」プッシュ・ ボタン。topic変数を使用して，ヘルプ・ライブラリのキー名を識別するコンパウンド・ ストリング(この場合"overview" )を格納します。 文字列はヘルプ・ライブラリにおけるキー名と一致していなければなりません。 このコンパウンド・ストリングは，あとでDXmNfirstTopic リソースの値として使用されます。

2. 第4.7.1項で説明したように， ヘルプ・コールバックの結果としてsens_help_procコールバックが呼び出されます。sens_help_proc は汎用のcreate_helpルーチンを呼び出します。

3. create_helpルーチンは，「ヘルプ」プルダウン・メニューのプッシュ・ ボタン，およびコンテキスト依存ヘルプのコールバックのために，Help ウィジェットのインスタンスを作成します。

   Helpウィジェットがまだ存在しない場合，create_helpはそのウィジェットをフェッチします。

   Helpウィジェットが存在し，すでに管理されている場合には，create_ helpは Helpウィジェットの新規のインスタンスをフェッチしなければなりません。 help_widget[help_num]変数は， DECburgerにおけるウィジェットの最大数に等しいHelpウィジェットの配列です。 指定されたコンパウンド・ストリングを使用してDXmNfirstTopic リソースを設定し，Helpウィジェットを管理してください。

   Helpウィジェットがすでに存在しているが，まだ管理されてない場合には， 指定されたコンパウンド・ストリングを使用してDXmNfirstTopic リソースを設定し，Helpウィジェットを管理してください。

# 4.10 ツールキットのHelpウィジェット作成ルーチンの使用

第4.7節で説明したように，Help ウィジェットの実現は，UIL またはツールキットのHelpウィジェット作成ルーチンのいずれを使用しても行うことができます。

例 4-9は，ツールキットのHelpウィジェット作成ルーチンを使用してHelp ウィジェットを作成する方法を示しています。

### 例 4-9 ツールキット・ルーチンによるHelpウィジェットの作成

       .
       .
       .

    /*
     * Context sensitive help callback.
     */
     */
    【1】
    static void sens_help_proc(w, tag, reason)
        Widget              w;
        XmString            *tag;
        XmAnyCallbackStruct *reason;
    {
         create_help(tag);
    }

       .
       .
       .
    /* Toolkit help creation routine */

    static void create_help (topic)
                XmString   topic;
    {

         unsigned int    ac;
         Arg             arglist[10];
         static Widget  help_widget;
         static int low_num;

    【2】if (!help_widget) {

          ac = 0;
            XtSetArg (arglist[ac], DXmNapplicationName,
                     XmStringCreateLtoR("Toolkit Help",XmSTRING_ISO8859_1));ac++;
            XtSetArg (arglist[ac], DXmNglossaryTopic,
                        XmStringCreateLtoR("glossary",XmSTRING_ISO8859_1)); ac++;
            XtSetArg (arglist[ac], DXmNoverviewTopic,
                        XmStringCreateLtoR("overview",XmSTRING_ISO8859_1)); ac++;
            XtSetArg (arglist[ac], DXmNlibrarySpec,
                     XmStringCreateLtoR("decburger.hlb",XmSTRING_ISO8859_1)); ac++;
            XtSetArg (arglist[ac], DXmNfirstTopic, topic); ac++;

            help_widget = DXmCreateHelpDialog (toplevel_widget,
                                             "Toolkit Help",
                                             arglist,
                                             ac);

            XtManageChild(help_widget);
            return;
        }

    【3】if (XtIsManaged(help_widget)) {

            ac = 0;
            XtSetArg (arglist[ac], DXmNapplicationName,
                     XmStringCreateLtoR("Toolkit Help",XmSTRING_ISO8859_1));ac++;
            XtSetArg (arglist[ac], DXmNglossaryTopic,
                        XmStringCreateLtoR("glossary",XmSTRING_ISO8859_1)); ac++;
            XtSetArg (arglist[ac], DXmNoverviewTopic,
                        XmStringCreateLtoR("overview",XmSTRING_ISO8859_1)); ac++;
            XtSetArg (arglist[ac], DXmNlibrarySpec,
                    XmStringCreateLtoR("decburger.hlb",XmSTRING_ISO8859_1)); ac++;
            XtSetArg (arglist[ac], DXmNfirstTopic, topic); ac++;

            help_array[low_num] = DXmCreateHelpDialog (toplevel_widget,
                                                       "Toolkit Help",
                                                        arglist, ac);

            XtManageChild(help_array[low_num]);
            low_num++;
            return;
        }

    【4】ac = 0;
        XtSetArg (arglist[ac], DXmNfirstTopic, topic); ac++;
        XtSetValues (help_widget, arglist, ac);

        XtManageChild(help_widget);
    }

       .
       .
       .

1. ヘルプ・コールバック・ルーチン(sens_help_proc)は， create_helpルーチンを呼び出してHelpウィジェットを作成します。

2. create_helpルーチンはHelpウィジェットがすでに存在するかどうかを検査します。 まだ存在しない場合，create_helpはDXmNapplicationName ，DXmNglossaryTopic，DXmNoverviewTopic， DXmNlibrarySpec，DXmNfirstTopicの各リソースを設定し， DXmCreateHelpDialogルーチンを呼び出します。その後create_helpルーチンはXtManageChild を呼び出して，Helpウィジェットを管理します。

3. Helpウィジェットがすでに存在し，管理されている場合， create_helpルーチンはHelpウィジェットの別のインスタンスを作成しなければなりません。help_array 配列は，DECburgerアプリケーションにおけるウィジェットの最大数に等しいHelp ウィジェットの配列です。

4. Helpウィジェットが存在しているが管理されてない場合には，DXmNfirstTopic リソースを設定して，それを管理します。

[ 前のページ ] [ 次のページ ] [ 目次 ] [ 索引 ]