この章では、アプリケーションが処理するヘルプ・ダイアログ・イベントについて説明します。
アプリケーション内の他のウィジェットと同様に、ヘルプ・ウィンドウにはアプリケーションがサポートしなければならない動作がいくつかあります。
標準ハイパーリンク・イベントのほとんどは、ヘルプ・システムによって内部的に処理されます。しかし、アプリケーションが処理するハイパーリンクは、次の 4 種類があります。
新規ウィンドウ表示ハイパーリンク
アプリケーションは新規のヘルプ・ダイアログを作成し、設計者の要求に応えて新規ヘルプ・ウィンドウにトピックを表示します。
マニュアル・ページ・リンク
アプリケーションは、新規の簡易ヘルプ・ダイアログを作成し (またはキャッシュから取り出し)、マニュアル・ページを表示します。通常、マニュアル・ページ・ウィンドウのサイズは、他のヘルプ・ウィンドウとは異なります。
アプリケーション定義リンク
アプリケーションは、これらのリンクに関連付けられているデータを解釈します。アプリケーション定義リンクは、アプリケーションの開発者とヘルプの設計者が、このリンクの作成のために共同で作業をした場合にだけ存在します。
テキスト・ファイル・リンク
アプリケーションは簡易ヘルプ・ダイアログを作成し (またはキャッシュから取り出し)、テキスト・ファイルを表示します。
ユーザがヘルプ・ダイアログを閉じる場合、そのキャッシュ内にダイアログを格納するかまたは破棄するかを認識している必要があります。一般ヘルプ・ダイアログでは、ヘルプ・クローズ・コールバックをサポートしています。簡易ダイアログの終了を検出するには、 [閉じる] ボタンにコールバックを追加してください。
簡易ヘルプ・ダイアログにあるいくつかのボタンの動作は、アプリケーションによって処理されなければなりません。これらのボタンは、必要に応じて管理することも管理しないことも可能です。起動コールバックを使用して、他のプッシュボタンのように動作を追加できます。
「ハイパーリンクの作成」では、ヘルプ・システムがサポートしているリンクの種類を記述し、リンクの作成方法について説明しています。
アプリケーションは、表示されるヘルプ・ボリューム内で使用されるハイパーリンクの種類だけは少なくともサポートする必要があります。一般的には、すべてのリンクの種類をサポートするようにしてください。
ハイパーリンクが選択されたときにアプリケーションに通知する場合、ハイパーリンク・コールバックをヘルプ・ダイアログに追加します。適切にハイパーリンクを処理するコールバック関数を指定しなければなりません。
次のようにしてハイパーリンク・コールバックを各ヘルプ・ダイアログに追加します。
XtAddCallback (helpDialog, DtNhyperlLinkCallback, HyperlinkCB, (XtPointer)NULL);
helpDialog はヘルプ・ダイアログのウィジェット ID で、HyperlinkCB はハイパーリンクを処理するコールバック関数名です。
ダイアログ内で発生する可能性があるハイパーリンク・イベントを処理するための 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 つの方法のどちらかでヘルプへのパスを提供することです。
段階を追って情報を検索できます。これは、しばしば段階的な表示と呼ばれます。この場合、デフォルト・ボタン・ラベル (More) が適切です。
アプリケーションのヘルプ・ボリュームを通常どおりブラウズするために一般ヘルプ・ダイアログを開くことができます。この場合、Browse... が最も適切なボタン・ラベルになります。
次のコード・セグメントはボタンの ID を獲得し、コールバックを割り当て、ボタンを管理します。quickHelpDialog が作成されたばかりであると想定しています。
Widget moreButton; moreButton = DtHelpQuickDialogGetChild (quickHelpDialog, DtHELP_QUICK_MORE_BUTTON); XtAddCallback (moreButton, XmNactivateCallback, MoreHelpCB, NULL); XtManageChild (moreButton);
DtHelpDialog(3) のマニュアル・ページ
DtHelpQuickDialog(3) のマニュアル・ページ