Oracle Help for Java開発者ガイド Previous topic
前へ
Next topic
次へ

状況依存ヘルプの有効化

状況依存ヘルプでは、ユーザー・インタフェースでの特定の状況に関連付けられたヘルプ・トピックが起動されます。一般的には、メニューやダイアログ・ボックスなどユーザー・インタフェースのコントロールを説明するヘルプ・トピックがこれに該当します。ユーザーが、ユーザー・インタフェースのコントロールに関するヘルプを要求する(たとえば、「ヘルプ」ボタンをクリックする)と、その状況(コントロール)に関する適切なトピックが表示されます。

次の各項では、Oracle Help for Javaを使用して状況依存ヘルプを実装する方法を説明します。

ユーザー・インタフェースでの状況に対するヘルプ・トピックの関連付け

Oracle Help for Javaでは、ヘルプ・トピックをユーザー・インタフェースのコントロールに関連付け、エンド・ユーザーが[F1]キーを押すか、またはポップアップ・メニューの「ヘルプ」をクリックしたときに状況依存ヘルプを起動するメカニズムが提供されます。また、あるコンポーネントに関連付けられたヘルプ・トピックの表示を明示的に要求するためのAPIも用意されています。

状況依存ヘルプでは、作成者が作成したヘルプのコンテンツに、トピックIDとヘルプ・トピックを関連付けるマップ・ファイルが含まれている必要があります。HelpBookの場合、マップ・ファイルはOHTファイル形式であり、ヘルプセットの場合、マップ・ファイルはXMLファイル形式です(OHJのファイル形式の仕様を参照してください)。

プログラミングにおいて、Help.showTopic()メソッドをコールする際、またはヘルプ・トピックをJavaユーザー・インタフェースのコントロールに関連付ける際には、作成者によるマップ・ファイルで指定されたトピックIDを使用する必要があります。したがって、プログラミングにはヘルプの作成者との共同作業が必要です。

必要に応じて、アプリケーション・コード内で、マップ・ファイル内に定義されたトピックIDに対応する一連のJava定数を定義することも検討してください。ヘルプのトピックIDが必要なOHJメソッドを使用する場合、作成者の定義したトピックIDをハードコードするかわりに、定数の変数名を使用できます。こうすることによって、作成者が後でトピックIDを変更しても、複数の箇所でコードを変更する必要はなくなります。

OHJのCSHManagerクラスの使用方法

OHJのCSHManager(Context Sensitive Help Manager)クラスは、ヘルプ・トピックとJavaユーザー・インタフェースのコンポーネントを関連付け、[F1]キーおよび右クリックによる状況依存ヘルプを有効にする方法を提供します。Javaソフトウェアのツールキット(AWTおよびSwing)には、ヘルプ・トピックとコンポーネントを関連付ける組込みの方法はないため、OHJのCSHManagerのような外部メカニズムが必要です。次の各項では、CSHManagerを使用して状況依存ヘルプを有効にする方法を説明します。

CSHManagerの構築

ユーザー・インタフェースのコンポーネントを作成する前に、CSHManagerのインスタンスを構築する必要があります。CSHManagerコンストラクタにより、アプリケーション用のHelpインスタンスが構築されます。

コンストラクタの詳細
CSHManager(Help help)

CSHManagerクラスの新規インスタンスを構築します。このマネージャ・オブジェクトに対する後続のすべてのコールでは、指定したHelpオブジェクトを使用します。

パラメータ: 
help - ヘルプの表示に使用されるHelpオブジェクト。

setDefaultBook()メソッド

ヘルプのコンテンツのBookが1つのみの場合、CSHManagerのsetDefaultBook()メソッドを使用して、それを状況依存ヘルプのデフォルトのBookとして定義することができます。これによって、addComponent()メソッドをコールする際に、bookパラメータの入力が不要になります。

メソッドの詳細
setDefaultBook(Book book)

指定したbookを、デフォルトのBookとして定義します。このbookは、Bookを指定せずに登録されたコンポーネントのデフォルトのBookとして使用されます。

パラメータ: 
book - 設定するBook。

複数のBookがある場合は、特定のBookを割り当てていないコンポーネントに対してのみ、デフォルトのBookが使用されます。複数のBookがあるヘルプ・システムでは、通常、特定のBookをコンポーネントに割り当ててください。

addComponent()メソッドの使用方法

addComponent()メソッドは、トピックID(マップ・ファイルで定義)をJavaユーザー・インタフェースのコンポーネントに関連付けるために使用します。状況依存ヘルプが必要な各コンポーネントに対して、次のいずれかのメソッドをコールします。

メソッドの詳細
addComponent(Component component, String topicId)

ヘルプ・マネージャにコンポーネントを登録します。

topicIdの検索には、デフォルトのBookが使用されます。このメソッドをコールした時点でデフォルトのBookが登録されていない場合には、コンポーネントがヘルプ・マネージャに登録されないため、このコンポーネントに対して後でshowHelpForComponent()をコールしてもヘルプは表示されません。

このメソッドを使用して登録されたコンポーネントに対して、[F1]キーまたは右クリックによるイベントが発生しても、CSHManagerはヘルプを表示しません。

パラメータ: 
component - 追加するコンポーネント。
topicId - このコンポーネントに関連付ける、作成者定義のトピックID。
addComponent(Component component, Book book, String topicId)

ヘルプ・マネージャにコンポーネントを登録します。topicIdの検索には、指定したbookが使用されます。

このメソッドを使用して登録されたコンポーネントに対して、[F1]キーまたは右クリックによるイベントが発生しても、CSHManagerはヘルプを表示しません。

パラメータ: 
component - 追加するコンポーネント。
book - ヘルプ・トピックを含むBook。
topicId - このコンポーネントに関連付ける、作成者定義のトピックID。
addComponent(Component component, String topicId, boolean needF1Help, boolean needPopupHelp)

topicIdの検索には、デフォルトのBookが使用されます。このメソッドをコールした時点でデフォルトのBookが登録されていない場合には、コンポーネントがヘルプ・マネージャに登録されないため、このコンポーネントに対して後でshowHelpForComponent()をコールしてもヘルプは表示されません。

パラメータ: 
component - 追加するコンポーネント。
topicId - このコンポーネントに関連付ける、作成者定義のトピックID。
needF1Help - trueの場合、[F1]キーを押すと、このコンポーネントに対するヘルプが表示されます。
needPopupHelp - trueの場合、右クリックで「ヘルプ」のポップアップ・メニューが表示され、「ヘルプ」を選択すると状況依存ヘルプが起動します。
addComponent(Component component, Book book, String topicId, boolean needF1Help, boolean needPopupHelp)

ヘルプ・マネージャにコンポーネントを登録します。topicIdの検索には、指定したbookが使用されます。

パラメータ: 
component - 追加するコンポーネント。
book - ヘルプ・トピックを含むBook。
topicId - このコンポーネントに関連付ける、作成者定義のトピックID。
needF1Help - trueの場合、[F1]キーを押すと、このコンポーネントに対するヘルプが表示されます。
needPopupHelp - trueの場合、右クリックで「ヘルプ」のポップアップ・メニューが表示され、「ヘルプ」を選択すると状況依存ヘルプが起動します。

コンポーネントに対するヘルプの明示的な表示

特定のコンポーネントに関連付けられたヘルプ・トピックを明示的に表示する場合は、CSHManagerでshowHelpForComponent()メソッドをコールします。たとえば、あるボタンのクリックに対応して状況依存ヘルプを起動する場合、そのボタンのイベント・ハンドラでこのメソッドをコールします。

メソッドの詳細
showHelpForComponent(Component component)

指定したcomponentに対するヘルプを表示します。指定したcomponentが、addComponent()を介して登録されていない場合、ヘルプは表示されません。

モーダル・ウィンドウの問題点

非モーダル・ウィンドウからヘルプを要求した場合、ユーザーは、ヘルプを要求した元のウィンドウと、表示されたヘルプ・トピックの間を切り替えることができます(通常の動作)。

しかしJavaでは、モーダル・ウィンドウから、Java Virtual Machineで作成された他のウィンドウにはアクセスできません(他のモーダル・ウィンドウへのアクセスは可能です)。そのため、モーダル・ウィンドウからヘルプを要求する場合、OHJではモーダルのヘルプ・ウィンドウでヘルプを表示する必要があります。

OHJでの回避方法

ヘルプが要求されると、OHJはアクティブ・ウィンドウがモーダルであるかどうかを判断します。アクティブ・ウィンドウがモーダルである場合、OHJは通常のトピック・ウィンドウの親子関係を変更し、ナビゲータ・ウィンドウを新規のモーダル・ウィンドウにします。この新規ウィンドウは、画面の前面に表示されるため、ユーザーはこのウィンドウを操作できます。実際には、このウィンドウを操作するのは、ヘルプ・ウィンドウ(モーダル)を閉じるときのみです。Javaにおけるモダリティの実装は不十分なため、これがOHJでサポートされているすべてのJava Virtual Machineで有効な唯一の解決方法です。

Help.registerClientWindow()

モーダル・ウィンドウの問題点に対するOHJでの回避方法が機能するためには、OHJで現在アクティブなウィンドウを追跡できる必要があります。このプロセスを実現するには、registerClientWindow()メソッドを使用して、作成するすべてのウィンドウ(FrameまたはDialog)をHelpオブジェクトに登録します。

メソッドの詳細
registerClientWindow(Window aWindow)
Helpオブジェクトに登録されたWindowインスタンスを追跡します。アクティブ・ウィンドウがモーダル・ダイアログであり、そこからヘルプを要求した場合、Helpオブジェクトは、ヘルプ・ウィンドウがアクティブなモーダル・ダイアログにブロックされないように特別な動作をします。

パラメータ: 
aWindow - 登録するWindowインスタンス。

Help.unregisterClientWindow()

ウィンドウがアクティブでないことがわかっている場合、unregisterClientWindow()メソッドを使用して、そのウィンドウをHelpオブジェクトから登録解除する必要があります。Windowインスタンスを登録解除しないと、そのウィンドウはガベージ・コレクションの対象にならないので注意してください。

メソッドの詳細
unregisterClientWindow(Window aWindow)

ウィンドウがアクティブでなくなった場合、クライアントは、registerClientWindow()メソッドを使用して登録されたすべてのWindowインスタンスを登録解除する必要があります。Windowインスタンスを登録解除しないと、そのウィンドウはガベージ・コレクションの対象になりません。

パラメータ: 
aWindow - 登録解除するWindowインスタンス。


  Previous topic
前へ
Next topic
次へ