[ 前のページ ] [ 次のページ ] [ 目次 ] [ 索引 ]
第4章で説明したHelpウィジェットのほかに，VMS DECwindows Motif アプリケーションはDECwindows Motifヘルプ・ システムを使用して，ユーザの要求に応じて一般情報およびコンテキスト依存情報を表示することもできます。 ヘルプ・システムはブックリーダとリンクワークスを使用して表示を行ったり，decw_book （UNIX）あるいはDECW$BOOK （OpenVMS）フォーマットのヘルプ・テキストとグラフィックの中をナビゲートします。OpenVMS システムではさらに，VAX DOCUMENT を使用して，ハイパーヘルプ・ファイルを作成することもできます（ブックリーダはWindows NT では提供されません。したがって，本章の内容はWindows NT でのみ動作するアプリケーションには適用されません）。
この章では，アプリケーションでヘルプ・システムを使用する方法について説明します。 ここで説明するトピックは次の通りです。
DECburgerデモ用プログラムはヘルプ・システムを使用して，「注文」制御ボックスのウィジェットに対するコンテキスト依存ヘルプを実現します。 ヘルプ・システムの操作に慣れるため，DECburgerを実行し，「注文」制御ボックス内のいずれかの項目について， コンテキスト依存ヘルプを要求してください。
ヘルプ・システムはディスプレイ・ウィンドウとして，DECwindowsブックリーダを使用します。 ヘルプ・システムのルーチンを使用すると，アプリケーションはブックリーダを呼び出して， 最初に表示する本，およびその本のなかの特定のトピックまたはディレクトリを指定することができます。 さらに，一度ヘルプ・システムからブックリーダを呼び出すと，ユーザがそれを明示的にクローズするかDECwindows セッションを終了するまで， そのブックリーダを利用できます。
ヘルプ・システムを使用すると，アプリケーションのユーザは，次のようなブックリーダの機能を利用できます。
図 5-1はHelpウィジェットとヘルプ・ システムを比較したものです。
ヘルプ・システムを実現するには，次の手順を実行してください。
ヘルプ・システムを実現するために必要な「ヘルプ」メニューは， Helpウィジェットで必要な「ヘルプ」メニューと同じです。Helpウィジェットの「ヘルプ」メニューをすでに実現している場合には， ヘルプ・ コールバックを多少変更するだけで，このメニューを使用できます。
プッシュ・ボタンのラベルは，利用できるヘルプの種類を示していなければなりません。 『OSF /Motifスタイル・ガイド』に，「ヘルプ」Pull-Down Menuウィジェットには， アプリケーションが該当する場合，次のトピックを含めるように示されています。
アプリケーション固有のヘルプ・トピックも追加できます。
DXmHelpSystemDisplayは，「ヘルプ」メニューにおけるプッシュ・ ボタンのアクティベート・コールバックの結果として，またはウィジェットのコンテキスト依存ヘルプのコールバックの結果として呼び出されます。
ユーザは次の4通りの方法でヘルプ・システムを呼び出すことができます。
XmLabelウィジェットなどの入力フォーカスを受け付けないウィジェットについては， ユーザがHelpキーを使用して，コンテキスト依存ヘルプを生成することはできません。
アプリケーションを開発する際，プログラマはどのヘルプの呼び出し方法をサポートするかを決定しなければなりません。DECwindows のほとんどのアプリケーションは， ヘルプの呼び出し方法として，メニュー・バーで「ヘルプ」オプションをクリックする方法と， コンテキスト依存ヘルプを使用する方法をサポートしています。
OpenVMS VAXシステム上のVAX DOCUMENTまたはDECwriteを使用すると，ヘルプ・ システムのブックリーダ・ファイルを作成できます。これ以降では例として，VAX DOCUMENT を使用して作成したヘルプ・ファイルを使用します。
VAX DOCUMENTを使用して作成されたヘルプ・システムのヘルプ・ファイルは， ブックリーダ出力用としてSOFTWARE.ONLINEドキュメント・タイプで処理された標準の.SDML ファイルです。
どの標準のセクション・タグ(<HEADn>)も，ヘルプ・トピックとして使用できます。 タグ<HEADn\symbolic_name>に関連付けられたシンボル名は， UILファイルで指定されたトピック識別子と一致していなければなりません。
例 5-1にVAX DOCUMENTのDECBURGER_ HELP.SDMLファイルとしてDECBURGER.HLPファイルを示します。.HLPファイルにおいてINCLUDE コマンドによって識別されるトピックは，.SDMLファイルでは<HOTSPOT> タグによって識別されることに注意してください。また， ヘルプ・システムでは，トピック識別子だけをシンボル名で指定する必要があることにも注意してください(Help ウィジェットは，ヘルプ・トピックを見つけるためにキー名の階層を使用し， そのトピックへのパスを構成するキー名を必要とします)。
【1】
<FRONT_MATTER>(dwhlp_front)
<TITLE_PAGE><TITLE>
(Help on DECburger)
<ENDTITLE_PAGE>
<CONTENTS_FILE>
<ENDFRONT_MATTER>
<HEAD1>(Overview of the Help Widget\overview)
<P>
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.
<P>
The help widget creates and manages one or more
help windows and determines the first topic to be
displayed to the user.
<P>
Additional topics:
<LIST>(UNNUMBERED)
【2】
<LE><HOTSPOT>(functions_1)
<LE><HOTSPOT>(create_help_widget)
<ENDLIST>
<HEAD2>(Using the Help widget\functions_1)
<P>
To use the help widget, you perform the following steps:
<LIST>(NUMBERED\1)
<LE>Use the VMS Librarian Utility (LIBRARIAN) to create a help library.
<LE>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.
<ENDLIST>
<HEAD1>(About the Help Widget\about)
<P>
This topic provides version information.
<P>
Additional topics:
<LIST>(UNNUMBERED)
<LE><HOTSPOT>(create_help_widget)
<ENDLIST>
<HEAD1>(Help Widget On Help\onhelp)
<P>
This topic provides help-on-using-help information.
<P>
Additional topics:
<LIST>(UNNUMBERED)
<LE><HOTSPOT>(create_help_widget)
<ENDLIST>
<HEAD1>(Menu Bar Context Sensitive Help\menu_bar)
<HEAD1>(File Menu Context Sensitive Help\file_menu)
<HEAD1>(Edit Menu Context Sensitive Help\edit_menu)
<HEAD1>(Not Yet Implemented\not_implemented)
<HEAD1>(Order Menu Context Sensitive Help\order_menu)
<HEAD1>(Order Context Sensitive Help\order)
<P>
Order menu context-sensitive help
<P>
Additional topics:
<LIST>(UNNUMBERED)
<LE><HOTSPOT>(burgers)
<LE><HOTSPOT>(fries)
<LE><HOTSPOT>(drink)
<LE><HOTSPOT>(apply)
<LE><HOTSPOT>(dismiss)
<LE><HOTSPOT>(create_help_widget)
<ENDLIST>
<HEAD2>(Burgers For Us\burgers)
<P>
Additional topics:
<LIST>(UNNUMBERED)
<LE><HOTSPOT>(burgers_rare)
<LE><HOTSPOT>(burgers_medium)
<LE><HOTSPOT>(burgers_well)
<LE><HOTSPOT>(burgers_ketchup)
<LE><HOTSPOT>(burgers_mustard)
<LE><HOTSPOT>(burgers_onion)
<LE><HOTSPOT>(burgers_mayo)
<LE><HOTSPOT>(burgers_pickle)
<LE><HOTSPOT>(burgers_quantity)
<ENDLIST>
<HEAD3>(Burgers For Us\burgers_rare)
<HEAD3>(Burgers Medium For Us\burgers_medium)
<HEAD3>(Burgers Well For Us\burgers_well)
<HEAD3>(Burgers Ketchup For Us\burgers_ketchup)
<HEAD3>(Burgers Mustard For Us\burgers_mustard)
<HEAD3>(Burgers Onion For Us\burgers_onion)
<HEAD3>(Burgers Mayo For Us\burgers_mayo)
<HEAD3>(Burgers Pickle For Us\burgers_pickle)
<HEAD3>(Burgers Quantity\burgers_quantity)
<HEAD2>(Fries For Us\fries)
<P>
Additional topics:
<LIST>(UNNUMBERED)
<LE><HOTSPOT>(fries_tiny)
<LE><HOTSPOT>(fries_small)
<LE><HOTSPOT>(fries_medium)
<LE><HOTSPOT>(fries_large)
<LE><HOTSPOT>(fries_huge)
<LE><HOTSPOT>(fries_quantity)
<ENDLIST>
<HEAD3>(Tiny Fries\fries_tiny)
<HEAD3>(Small Fries\fries_small)
<HEAD3>(Medium Fries\fries_medium)
<HEAD3>(Large Fries\fries_large)
<HEAD3>(Huge Fries\fries_huge)
<HEAD3>(Fries Quantity\fries_quantity)
<HEAD2>(Drink Choices\drink)
<P>
Additional topics:
<LIST>(UNNUMBERED)
<LE><HOTSPOT>(drink_list)
<LE><HOTSPOT>(drink_quantity)
<LE><HOTSPOT>(drink_add)
<LE><HOTSPOT>(drink_sub)
<ENDLIST>
<HEAD3>(Drink List\drink_list)
<HEAD3>(Drink Quantity\drink_quantity)
<HEAD3>(Drink Add\drink_add)
<HEAD3>(Drink Subtract\drink_sub)
<HEAD2>(Help on Apply\apply)
<P>
This topic provides information on both Apply and Reset.
<HEAD2>(Help on Dismiss\dismiss)
<HEAD1>(Help on Custom Colors\customize)
<HEAD1>(Help on Print Order\print)
<HEAD1>(Programming Help\programming)
<P>
Programming help.
<P>
Additional topics:
<LIST>(UNNUMBERED)
<LE><HOTSPOT>(creating)
<ENDLIST>
<HEAD2>(Creating a Help widget\creating)
<P>
Creating a help widget.
<P>
Additional topics:
<LIST>(UNNUMBERED)
<LE><HOTSPOT>(create_help_widget)
<ENDLIST>
<HEAD3>(Creating a Help widget\create_help_widget)
<P>
Programming help for creating a help widget.
<HEAD1>(Help Widget Glossary\glossary)
<P>
This topic provides glossary information.
<P>
Additional topics:
<LIST>(UNNUMBERED)
<LE><HOTSPOT>(create_help_widget)
<ENDLIST>
ヘルプ・システムを呼び出すときは，DXmHelpSystemOpenルーチンにヘルプ・ ファイル指定を渡します。省略時のディレクトリ位置はSYS$HELPで， 省略時のファイル・タイプはDECW$BOOKですが，ヘルプ・ファイル名と一緒に独自のディレクトリやファイル・ タイプを指定することもできます。 ヘルプ・システムはこのヘルプ・ファイル指定を使用して，ヘルプ・ファイルを検索して読み込みます。
たとえば，ヘルプ・ファイル指定に次のようなシンボル名を定義します。
#define my_help "sys$login:my_help.decw$book"
その後，このシンボル名をヘルプ・ファイル指定として渡すことができます。
DXmHelpSystemOpen(&help_context, toplevel_widget, decburger_help,
help_error, "Help System Error");
コンテキスト依存ヘルプでは，アプリケーションがヘルプ階層を上位レベルから下位レベルに順番に進むのでなく， 現在のトピックに関するヘルプを直接提示します。 ユーザは必要な情報を見つけるために，ヘルプのいくつかの層をナビゲートしなくてもすみます。
XmPrimitiveまたはXmManagerウィジェット・クラスのサブクラスであるすべてのウィジェットは，XmCR_HELP という条件でヘルプ・コールバックをサポートします。 その他のウィジェットでもヘルプ・コールバックをサポートすることはできます。 アプリケーションはこのヘルプ・コールバックを使用して， ヘルプ・コールバック・ルーチンと，ヘルプを付与したいウィジェットを関連付けることにより， コンテキスト依存ヘルプを実現します。
ツールキットにはDXmHelpOnContextというルーチンがあり，アプリケーションはこのルーチンを使用して， コンテキスト依存ヘルプ・モードに入ることができます。
『OSF/Motifスタイル・ガイド』の勧告に準拠するため， ヘルプ・コールバックはダイアログ・ボックス自身にのみ付与し， ダイアログ・ボックス内のオブジェクトに関して付与してはなりません。DXmHelpOnContext ルーチンは関連付けられたヘルプ・ コールバック・ルーチンを持つウィジェットが見つかるまでウィジェットに一番近い先祖を探すため， ユーザはダイアログ・ボックス内のどこでクリックしても， そのダイアログ・ボックスに関するコンテキスト依存ヘルプを得ることができます。
例 5-4に，ヘルプ・コールバック・ ルーチンの例を示します。
ここからは，コンテキスト依存ヘルプを実現する方法について説明します。
例 5-2は，「ヘルプ」プルダウン・ メニューの「コンテキスト」プッシュ・ ボタンを作成する方法を示しています。
.
.
.
object help_menu_entry : XmCascadeButton {
arguments {
XmNlabelString = k_help_label_text;
XmNmnemonic = keysym("H");
};
controls {
XmPulldownMenu help_menu;
};
callbacks
{
XmNhelpCallback = procedure help_system_proc(k_help_help);
};
};
object help_menu : XmPulldownMenu
{
controls
{
XmPushButton help_sensitive;
XmPushButton help_window;
XmPushButton help_version;
XmPushButton help_onhelp;
};
callbacks
{
XmNhelpCallback = procedure help_system_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 help_system_proc(k_sensitive_help);
};
};
.
.
.
「コンテキスト」プッシュ・ボタンのアクティベート・コールバックは， 例 5-3に示すように，コンテキスト依存ヘルプ・ モードに入るためのルーチンを呼び出します。DECburgerのすべてのプッシュ・ ボタンは，activate_procルーチンへコールバックします。 ただし，アプリケーションは「コンテキスト」プッシュ・ボタンから， コンテキスト依存ヘルプのコールバックを直接呼び出すことも可能です。
.
.
.
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);
}
.
.
.
選択したウィジェットがヘルプ・コールバックを持つ場合，そのヘルプ・ コールバックが呼び出されます。選択したウィジェットがヘルプ・ コールバックを持たない場合は，ヘルプ・コールバックが見つかるか， またはウィジェット階層の一番上に到達するまで，そのウィジェットの先祖を検索します。
アプリケーションの最上位のウィジェットの名前と，検索処理をそのウィジェットに制限したいかどうかを示す論理値を指定して， DXmHelpOnContextルーチンが呼び出されます。
ヘルプ・ポインタ・カーソルをアプリケーションの最上位のウィジェットに制限すると( 論理値TRUE)，ユーザはヘルプ・ポインタ・カーソルをメイン・ ウィンドウの境界外に移動することはできません。つまり， ユーザは最上位ウィジェットの境界を越えるポップアップ・ウィジェットに関して， コンテキスト依存ヘルプを得られないということです。
ヘルプ・ポインタ・カーソルをアプリケーションの最上位ウィジェットに制限しなければ( 論理値FALSE)，ユーザはアプリケーションのいずれのウィジェットに関しても， コンテキスト依存ヘルプを得ることが可能になります。
この例はヘルプ・ポインタ・カーソルを制限していません。
アプリケーションはXmNhelpCallbackリソースを使用して，コンテキスト依存ヘルプ・ コールバック・ルーチンと，ヘルプを提供したいウィジェットを関連付けます。
アプリケーションはコールバックのtag引数を使用すると，ヘルプ・ トピック固有のデータを与えることができます。ヘルプ・システムのDXmHelpSystemDisplay ルーチンは，表示するヘルプ・トピックの指定に文字列の値を使用します。 このため，例 5-4に示すように， アプリケーションはヘルプ・コールバック・ ルーチンに，ヘルプ・トピックを指定する文字列の値を与えなければなりません。
.
.
.
!String value to use for the help system callback
value
helpsys_order_help : 'order';
.
.
.
object ! The control panel. All order entry
! is done through this dialog box.
control_box : XmFormDialog {
arguments {
XmNdialogTitle = k_decburger_title;
XmNdialogStyle = XmDIALOG_MODELESS;
XmNnoResize = true;
XmNdefaultPosition = false;
XmNx = 525;
XmNy = 100;
XmNautoUnmanage = false;
XmNallowOverlap = false;
XmNdefaultButton = XmPushButton ok_button;
XmNcancelButton = XmPushButton cancel_button;
XmNhorizontalSpacing = 10;
XmNverticalSpacing = 10;
XmNnavigationType = XmEXCLUSIVE_TAB_GROUP;
};
controls {
XmForm burger_form;
XmForm fries_form;
XmForm drinks_form;
XmSeparator button_separator;
XmPushButton ok_button;
XmPushButton apply_button;
XmPushButton reset_button;
XmPushButton cancel_button;
XmSeparator button_separator2;
};
callbacks {
MrmNcreateCallback = procedure create_proc (k_order_box);
【1】XmNhelpCallback = procedure help_system_proc (helpsys_order_help);
};
};
.
.
.
.
.
.
/* Creates a help system session */
static void help_system_proc(w, tag, reason)
Widget w;
char *tag;
XmAnyCallbackStruct *reason;
{
DXmHelpSystemOpen(&help_context, toplevel_widget, decburger_help,
help_error, "Help System Error");
}
.
.
.
keyword引数に"dir"を使用する場合，name引数は，オープンするブックリーダのディレクトリを識別する文字列を指定しなければなりません。 この機能を使用すると， ユーザに例のリストを直接提示したり，索引でヘルプ・ ファイルをオープンすることができます。次の例に示すように， ブックリーダのディレクトリは，"Contents"，"Index"，"Examples"， "Figures"，"Tables"のいずれかです。
DXmHelpSystemDisplay(help_context, decburger_help, "dir", "Contents",
help_error, "Help System Error");
例 5-6はDECburgerにヘルプ・ システムを実現する例です。 実際のDECburgerのコードとは異なり，このコードはヘルプ・ システムだけを実現して，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】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';
.
.
.
!String value to use for the Help System callbacks
【3】
value
k_order_help : 'order';
k_print_help : 'print';
k_options_help : 'options';
k_menu_bar_help : 'menu_bar';
k_file_help : 'file_menu';
k_edit_help : 'edit_menu';
k_order_menu_help : 'order_menu';
k_help_help : 'help';
k_sensitive_help : 'sensitive';
k_onhelp_help : 'onhelp';
k_about_help : 'about';
k_overview_help : 'overview';
k_nyi_help : 'not_implemented';
.
.
.
object
s_menu_bar : XmMenuBar {
arguments {
XmNorientation = XmHORIZONTAL;
【4】XmNmenuHelpWidget = XmCascadeButton help_menu_entry;
};
controls {
XmCascadeButton file_menu_entry;
XmCascadeButton edit_menu_entry;
XmCascadeButton order_menu_entry;
XmCascadeButton options_menu_entry;
【5】XmCascadeButton help_menu_entry;
};
callbacks {
MrmNcreateCallback = procedure create_proc (k_menu_bar);
XmNhelpCallback = procedure help_system_proc(k_menu_bar_help);
};
};
.
.
.
【6】
object help_menu_entry : XmCascadeButton {
arguments {
XmNlabelString = k_help_label_text;
XmNmnemonic = keysym("H");
};
controls {
XmPulldownMenu help_menu;
};
callbacks
{
XmNhelpCallback = procedure help_system_proc(k_help_help);
};
};
【7】
object help_menu : XmPulldownMenu
{
controls
{
XmPushButton help_sensitive;
XmPushButton help_window;
XmPushButton help_version;
XmPushButton help_onhelp;
};
callbacks
{
XmNhelpCallback = procedure help_system_proc(k_help_help);
};
};
object help_sensitive : XmPushButton
{
arguments
{
XmNlabelString = k_sensitive_label_text;
XmNmnemonic = keysym("C");
};
callbacks
{
XmNactivateCallback = procedure activate_proc (k_help_sensitive);
XmNhelpCallback = procedure help_system_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 help_system_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 help_system_proc(k_about_help);
};
};
object help_window : XmPushButton
{
arguments
{
XmNlabelString = k_overview_label_text;
XmNmnemonic = keysym("W");
};
callbacks
{
【8】XmNactivateCallback = procedure activate_proc (k_help_overview);
XmNhelpCallback = procedure help_system_proc(k_overview_help);
};
};
object ! The control panel. All order entry
! is done through this dialog box.
control_box : XmFormDialog {
arguments {
XmNdialogTitle = k_decburger_title;
XmNdialogStyle = XmDIALOG_MODELESS;
XmNnoResize = true;
XmNdefaultPosition = false;
XmNx = 375;
XmNy = 100;
XmNautoUnmanage = false;
XmNallowOverlap = false;
XmNdefaultButton = XmPushButton ok_button;
XmNcancelButton = XmPushButton cancel_button;
XmNhorizontalSpacing = 10;
XmNverticalSpacing = 10;
XmNnavigationType = XmEXCLUSIVE_TAB_GROUP;
};
controls {
XmForm burger_form;
XmForm fries_form;
XmForm drinks_form;
XmSeparator button_separator;
XmPushButton ok_button;
XmPushButton apply_button;
XmPushButton reset_button;
XmPushButton cancel_button;
XmSeparator button_separator2;
};
callbacks {
MrmNcreateCallback = procedure create_proc (k_order_box);
【9】XmNhelpCallback = procedure help_system_proc (k_order_help);
};
};
.
.
.
例 5-7は，例 5-6 で作成されたヘルプ・システムを実現するC 言語のコードを示しています。DECburgerアプリケーションの完全なC ソース・コードはDECW$EXAMPLESに入っています。
.
.
.
#include <stdio.h> /* For printf and so on. */
#include <Xm/text.h>
#include <Mrm/mrmappl.h>
#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>
.
.
.
/*
* Global data
*/
/* Book file for help system */
【1】
#define decburger_help "decw$examples:decburger_help.decw$book"
/* Global help system context */
【2】
Opaque help_context;
.
.
.
/*
* Forward declarations
*/
static void s_error();
static void help_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();
static void tracking_help();
【3】
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},
【4】{"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. */
【5】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);
/* Set up Help System environment */
【6】DXmHelpSystemOpen(&help_context, toplevel_widget, decburger_help,
help_error, "Help System Error");
/* Sit around forever waiting to process X-events. We never leave
* XtAppMainLoop. From here on, we only execute our callback routines. */
XtAppMainLoop(app_context);
}
.
.
.
/*
* Help System errors are also fatal.
*/
【7】
static void help_error(problem_string, status)
char *problem_string;
int status;
{
printf("%s, %x\n", problem_string, status);
exit(0);
}
.
.
.
/*
* 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;
.
.
.
【8】case k_help_overview:
DXmHelpSystemDisplay(help_context, decburger_help, "topic",
"overview", help_error, "Help System Error");
break;
case k_help_about:
DXmHelpSystemDisplay(help_context, decburger_help, "topic",
"about", help_error, "Help System Error");
break;
case k_help_onhelp:
DXmHelpSystemDisplay(help_context, decburger_help, "topic",
"onhelp", help_error, "Help System Error");
break;
case k_help_sensitive:
tracking_help();
break;
.
.
.
/* Switches DECburger into context-sensitive mode and calls the selected
** widget's context-sensitive help callback
*/
static void tracking_help()
{
DXmHelpOnContext(toplevel_widget, FALSE);
}
/* Help system callback. Creates a help system session */
【9】
static void help_system_proc(w, tag, reason)
Widget w;
int *tag;
XmAnyCallbackStruct *reason;
{
DXmHelpSystemDisplay(help_context, decburger_help, "topic", tag,
help_error, "Help System Error");
}
.
.
.
/*
* The user pushed the exit button, so the application exits.
*/
【10】
static void exit_proc(w, tag, reason)
Widget w;
char *tag;
XmAnyCallbackStruct *reason;
{
if (tag != NULL)
printf("Exit - %s\n", tag);
DXmHelpSystemClose(help_context, help_error, "Help System Error");
exit(1);
}
ヘルプ・システムは次のように，整数，すなわちstatusを渡して，エラー処理操作のステータスを示します。
| 値 | 説明 |
|---|---|
| 1 | ヘルプ・システムがリンクワークスの共用可能イメージを見つけることができなかった。 |
| 2 | ヘルプ・システムが指定された値を有効なファイル指定に変換できなかった。 |
エラー・メッセージを指定するためのtag引数(この場合problem_ string)の使用例。アプリケーションはtag引数を使用して，エラーが発生した場所を示すこともできます。 たとえば，tagに1つの値を渡して，DXmHelpSystemOpen ルーチンへの呼び出しの結果としてエラーが発生したことを示し， その後DXmHelpSystemDisplayおよびDXmHelpSystemClose の各ルーチンに別の値を渡すことができます。
activate_callbackルーチンは適切なname引数を指定してDXmHelpSystemDisplay ルーチンを呼び出します。
name引数(この場合はtag)は，表示するヘルプ・トピックを識別するUIL からの文字列の値です。keyword引数の値は"topic"です。
keyword引数に"dir"を使用する場合，name引数は，オープンするブックリーダのディレクトリを識別する文字列を指定しなければなりません。 ブックリーダのディレクトリは"Contents"，"Index"， "Examples"，"Figures"，"Tables"のいずれかです。