test

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

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

関連項目