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

アプリケーションへのOracle Help for Javaの追加

ここでは、製品アプリケーションにOracle Help for Javaを統合するプロセスについて説明します。最初にHelpオブジェクトを作成します。これがOracle Help for Javaへのエントリ・ポイントとなります。次に、Helpオブジェクトにアプリケーションのヘルプのコンテンツを移入します。そのためには、ヘルプ・データを表すBookオブジェクト(HelpBookまたはヘルプセット)を作成し、そのBookオブジェクトをHelpオブジェクトに追加します。OHJのナビゲータ・ウィンドウを表示する方法、および特定のヘルプ・トピックを表示する方法については後述します。最後に、アプリケーションのライフ・サイクルの終了とともにHelpオブジェクトを破棄する方法について説明します。

ここでは、次の項目について説明します。

Helpオブジェクトの構築

Helpオブジェクトは、Oracle Help for Javaへのエントリ・ポイントとなるものです。これには、ヘルプのコンテンツを追加する方法と、ナビゲータ・ウィンドウおよび特定のトピックを表示する方法が含まれます。Helpオブジェクトの作成時に設定できるいくつかのオプションがあります。

Helpオブジェクトのコンストラクタで設定されるオプションの1つによって、複数のヘルプ・ブック(HelpBookまたはヘルプセット)をOHJがどのように表示するかが決定されます。boolean combineBooksパラメータをtrueに設定した場合、作成者の定義した表示でtypeおよびlabelの同じものは、すべてマージされます。たとえば、複数のブックにラベルの同じ索引が含まれていると、キーワードのリストをマージおよびソートして、1つの索引がナビゲータに表示されます。combineBooksパラメータがfalseの場合は、各ブックの表示が別々に表示され、エンド・ユーザーはナビゲータ・ウィンドウのドロップダウン・リストを使用して、表示するブックを選択することができます。ヘルプのコンテンツを他のブックとマージするか、別々に表示するかは、ヘルプの作成者との間で確認する必要があります。

各種のHelpオブジェクトのコンストラクタとそのパラメータを、次の表にまとめます(詳細は、oracle.help.HelpのJavadocを参照してください)。

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

トピックを表示するHTMLBrowserコンポーネントとしてICEBrowserを使用するHelpオブジェクトのインスタンスを作成します。このコンストラクタでは、追加されたブックのすべての表示を1つのタブ・パネルに表示し、作成者定義のタブ・ラベルを無視して標準のタブ・ラベルを優先するようヘルプ・システムに指示します。

Help(boolean combineBooks, boolean useLabelInfo)

トピックを表示するHTMLBrowserコンポーネントとしてICEBrowserを使用するHelpオブジェクトのインスタンスを作成します。

パラメータ: 
combineBooks - trueの場合、ヘルプ・システムに追加されたブックのすべての表示を1つのタブ・パネルに表示します。falseの場合、ヘルプ・システムによりブックごとにタブ・パネルが作成され、エンド・ユーザーは表示するブックを選択できます。
useLabelInfo - trueの場合、表示およびマージの際に作成者定義のラベル情報を使用します。falseの場合、標準のナビゲータ・ラベルを使用します。

Help(Class htmlBrowserClass, boolean combineBooks, boolean useLabelInfo)

トピックを表示する際に、指定したHTMLBrowserコンポーネントを使用するHelpオブジェクトのインスタンスを作成します(注意: 現在、OHJに同梱されているHTMLBrowserサブクラスは、ICEBrowserのみです)。

パラメータ: 
htmlBrowserClass - トピック表示コンポーネントとして使用するHTMLBrowserサブクラス。
combineBooks - trueの場合、ヘルプ・システムに追加されたブックのすべての表示を1つのタブ・パネルに表示します。falseの場合、ヘルプ・システムによりブックごとにタブ・パネルが作成され、エンド・ユーザーは表示するブックを選択できます。
useLabelInfo - trueの場合、表示およびマージの際に作成者定義のラベル情報を使用します。falseの場合、標準のナビゲータ・ラベルを使用します。
Help(Class htmlBrowserClass, boolean combineBooks, boolean useLabelInfo, boolean standAloneMode)

トピックを表示する際に、指定したHTMLBrowserコンポーネントを使用するHelpオブジェクトのインスタンスを作成します(注意: 現在、OHJに同梱されているHTMLBrowserサブクラスは、ICEBrowserのみです)。このコンストラクタには、OHJのスタンドアロン・モードでの実行を有効にする追加のパラメータがあります。このモードでは、すべてのヘルプ・ウィンドウを閉じた時点で、HelpオブジェクトはSystem.exitを介してJVMを終了します。OHJをJavaアプリケーションから起動する場合は、standAloneModeパラメータをfalseに設定する必要があります(trueに設定した場合、ヘルプを閉じるとアプリケーションが終了します)。

パラメータ: 
htmlBrowserClass - トピック表示コンポーネントとして使用するHTMLBrowserサブクラス。
combineBooks - trueの場合、ヘルプ・システムに追加されたブックのすべての表示を1つのタブ・パネルに表示します。falseの場合、ヘルプ・システムによりブックごとにタブ・パネルが作成され、エンド・ユーザーは表示するブックを選択できます。
useLabelInfo - trueの場合、表示およびマージの際に作成者定義のラベル情報を使用します。falseの場合、標準のナビゲータ・ラベルを使用します。
standAloneMode - trueの場合、すべてのヘルプ・ウィンドウを閉じた時点で、ヘルプ・システムはJVMを終了します。OHJをJavaアプリケーションから起動する場合には、このパラメータをfalseに設定してください。

ヘルプ・データの追加

HelpBookとヘルプセットの相違点

OHJのBookオブジェクトは、ヘルプのコンテンツのブックをカプセル化します。Oracle Help for JavaのBookインタフェースには2種類の実装があり、それぞれ異なるファイル形式を扱います。

ヘルプセット。この実装では、Oracle Help for Javaで新しくデフォルトとなったファイル形式を扱います(OHJのファイル形式の仕様を参照してください)。ヘルプの作成者がヘルプセット・ファイル(通常の拡張子は .hs)を作成した場合、そのファイルを使用してヘルプセット・オブジェクトを構築します。

HelpBook。この実装では、従来のOHJ形式を扱います。HelpBookクラスは、ディレクトリを調べ、既知の拡張子を持つファイルを特定してそれらをヘルプ・システムに追加します。

ヘルプのコンテンツにどちらの形式を使用するかは、ヘルプの作成者との間で確認する必要があります。

HelpBookまたはヘルプセットの構築

HelpBookおよびヘルプセットのコンストラクタとそのパラメータを、次の表にまとめます。

ヘルプセット

コンストラクタの詳細
Helpset(URL fileURL)

指定したURL位置にあるヘルプセット・ファイルを使用して、ヘルプセット・オブジェクトを構築します。作成者によるヘルプセット・ファイルの絶対パスがわかっている場合、このコンストラクタを使用します。

パラメータ: 
fileURL - 作成者によるヘルプセット・ファイルの絶対パスを指定するURL。
Helpset(Class pathClass, String pathExtension)

アプリケーションの実装に対する、ヘルプセット・ファイルへの相対的なパスのみがわかっている場合、このコンストラクタを使用します。

パラメータ: 
pathClass - アプリケーション・クラスの1つ。ヘルプセット・オブジェクトでは、このクラスの位置を使用して、ヘルプセット・ファイルの位置を決定します。
pathExtension - pathClassに対して相対的な、ヘルプセット・ファイルへのパス。このパラメータの値が、pathClassを含むディレクトリへの絶対パスに追加されます。追加後のパスが、ヘルプセット・ファイルへのパスになります。

詳細は、OHJDKのJavadocでoracle.help.library.helpset.Helpsetの項目を参照してください。

HelpBook

HelpBook形式は、ディレクトリに基づいています。したがって、そのコンストラクタを使用して、作成者によるヘルプのコンテンツを含むディレクトリの位置を指定します。

コンストラクタの詳細
HelpBook(String baseURL, String baseName, String bookTitle)

指定したタイトルを持つHelpBookを作成し、baseURLで指定したディレクトリ位置からデータをロードします。HelpBookオブジェクトは、ディレクトリを調べ、baseNameで指定された名前の既知の制御ファイル(TOC、TOK、HHC、HHK、OHTおよびIDX)を特定します。ヘルプのコンテンツ・ディレクトリの絶対パスがわかっている場合、このコンストラクタを使用します。

パラメータ: 
baseURL - 作成者によるヘルプセット・ファイルの絶対パスを指定するURL名。
baseName - 指定したディレクトリで検出されたすべての制御ファイルのベース名(すなわち、制御ファイルの名前がdiscoverer.hhc、discoverer.hhkなどであれば、baseNameはdiscovererとなります)。
bookTitle - ヘルプの作成者が指定するブック名。このブック名は、複数ブックのヘルプ・システムの場合にプルダウン・メニューで表示されます。
HelpBook(Class baseClass, String dirPathExt, String baseName, String bookTitle)

指定したタイトルを持つHelpBookを作成し、baseClassおよびdirPathExtで指定したディレクトリ位置からデータをロードします。HelpBookオブジェクトは、ディレクトリを調べ、baseNameで指定された名前の既知の制御ファイル(TOC、TOK、HHC、HHK、OHTおよびIDX)を特定します。アプリケーションの実装に対する、ヘルプのコンテンツ・ディレクトリへの相対的なパスのみがわかっている場合、このコンストラクタを使用します。

パラメータ: 
baseClass - アプリケーション・クラスの1つ。HelpBookオブジェクトでは、このクラスの位置を使用して、ヘルプのコンテンツ・ディレクトリの位置を決定します。
dirPathExt - baseClassに対して相対的な、ヘルプのコンテンツ・ディレクトリへのパス。このパラメータの値が、baseClassを含むディレクトリへの絶対パスに追加されます。追加後のパスが、ヘルプのコンテンツ・ディレクトリへのパスになります。
baseName - 指定したディレクトリで検出されたすべての制御ファイルのベース名(制御ファイルの名前がdiscoverer.hhc、discoverer.hhkなどであれば、baseNameはdiscovererとなります)。
bookTitle - ヘルプの作成者が指定するブック名。このブック名は、複数ブックのヘルプ・システムの場合にプルダウン・メニューで表示されます。

詳細は、OHJDKのJavadocでoracle.help.library.helpbook.HelpBookの項目を参照してください。

HelpBookまたはヘルプセットの追加

HelpBookまたはヘルプセットのコンストラクタを使用してBookインスタンスを構築した後、そのBookをHelpインスタンスに追加する必要があります。そのためには、Helpインスタンスで次のメソッドをコールします。

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

このメソッドでは、ヘルプ・システムにBookインスタンスを追加します。これによりBookに含まれる作成者定義のビューが、ヘルプのナビゲータ・ウィンドウに表示され、Bookのトピックが表示可能になります。

パラメータ: 
book - ヘルプ・システムに追加するBookインスタンス。

Helpオブジェクトを作成するタイミング

Helpオブジェクトのシングル・インスタンスの作成と、ヘルプ・データの追加は、アプリケーションの起動時に行います。Helpオブジェクトのこのシングル・インスタンスは、アプリケーションのセッションを通じて使用されます。アプリケーション内でユーザーがヘルプを要求するたびに別のHelpオブジェクトを作成するのは、効率的ではありません。

ナビゲータ・ウィンドウの表示

showNavigatorWindow()メソッドをコールすることによって、OHJのヘルプ・ナビゲータ・ウィンドウを表示するようHelpインスタンスに指示できます。このメソッドには、特定のナビゲータ・タブ(「目次」、「索引」、「検索」など)を選択してヘルプ・ナビゲータ・ウィンドウを表示するための追加パラメータをとる複数の種類があります。

メソッドの詳細
showNavigatorWindow()

ヘルプ・ナビゲータ・ウィンドウで、選択した最初のブックの最初のナビゲータ・タブを表示します。

showNavigatorWindow(Book activeBook)

ヘルプ・ナビゲータ・ウィンドウで、指定したブックから、関連付けられたナビゲータのセットを表示します。

パラメータ: 
activeBook - ナビゲータ・ウィンドウの表示で、関連付けられたナビゲータのセットが最初に表示されるBookオブジェクト。
showNavigatorWindow(Navigator activeNavigator)

特定のナビゲータ・タブが選択された状態で、ヘルプ・ナビゲータ・ウィンドウを表示します。特定のブックから特定のナビゲータ・タブを表示する場合は、このメソッドを使用します。

パラメータ: 
activeNavigator - 最初に表示するナビゲータ・タブ。

トピックの表示

showTopic()メソッド

showTopic()メソッドをコールし、そのトピックにトピックIDおよびBookインスタンスを指定することによって、特定のヘルプ・トピックを表示するようHelpインスタンスに指示できます。このメソッドには、トピックの表示方法を指定する追加のパラメータをとる複数の種類があります。

メソッドの詳細
showTopic(Book book, String topicID)

現在のトピック・ウィンドウに、指定したbookの指定トピックを表示します。現在トピック・ウィンドウが開かれていない場合は、デフォルトのサイズおよび位置を持つ新規のトピック・ウィンドウが作成されます。

パラメータ: 
book - 表示するトピックを含むBook。
topicID - 表示するトピックのトピックID(ブックのマップ・ファイルで指定されます)。
showTopic(Book book, String topicID, boolean alwaysCreate)

指定したbookから、指定したトピックを表示します。alwaysCreateがtrueの場合、常に新規のウィンドウが作成されます。falseの場合、現在ウィンドウが開かれていない場合にのみ新規のウィンドウが作成されます。

パラメータ: 
book - 表示するトピックを含むBook。
topicID - 表示するトピックのトピックID(ブックのマップ・ファイルで指定されます)。
alwaysCreate - trueの場合、常に新規ウィンドウを作成します。falseの場合、可能であればウィンドウを再利用します。
showTopic(Book book, String topicID, boolean alwaysCreate, Point location, Dimension size)

指定したbookから、指定したトピックを表示します。alwaysCreateがtrueの場合、常に新規のウィンドウが作成されます。falseの場合、現在ウィンドウが開かれていない場合にのみ新規のウィンドウが作成されます。トピック・ウィンドウの表示には、指定した位置およびサイズが使用されます。

パラメータ: 
book - 表示するトピックを含むBook。
topicID - 表示するトピックのトピックID(ブックのマップ・ファイルで指定されます)。
alwaysCreate - trueの場合、常に新規ウィンドウを作成します。falseの場合、可能であればウィンドウを再利用します。
location - 画面の座標における、トピック・ウィンドウの位置。
size - トピック・ウィンドウのサイズ(ピクセル単位)。

TopicDisplayExceptionsの捕捉

トピック表示のプロセスでエラーが発生すると、showTopic()メソッドにより例外がスローされます。たとえば、存在しないトピックID(マップ・ファイルに存在しないトピックID)を表示しようとした場合、TopicDisplayExceptionがスローされます。TopicDisplayExceptionを捕捉することによって、エラーの発生に対応できます。次の例では、TopicDisplayExceptionに対応して、作成者の定義した特別なエラー・トピックが表示されます。

例: 

try
{
  myHelp.showTopic(myhelpset, "nonExistingTopic");
}
catch (TopicDisplayException e)
{
  //An error has occurred, try to show an error topic
  myHelp.showTopic(myhelpset, "onErrorTopic");
}

Helpオブジェクトの破棄

Helpオブジェクトを破棄することによって、OHJのリソースが解放されます。ヘルプ・エンジンが不要になった時点で、Helpオブジェクトを破棄する必要があります。一般的には、これはアプリケーションのユーザー・セッション終了時に実行されます。Helpオブジェクトを破棄すると、Helpオブジェクトにより使用されていたすべてのファイルが閉じられ、メモリーが解放されます。Helpオブジェクトを破棄するには、dispose()メソッドをコールします。

メソッドの詳細
dispose()

ヘルプ・システムを破棄します。このメソッドにより、ヘルプ・システムで使用されていたすべてのリソースが解放されます。アプリケーションでは、ヘルプが不要になった時点でこのメソッドをコールする必要があります。dispose()をコールした後には、Helpオブジェクトでメソッドをコールしないでください。

dispose()メソッドをコールすると、OHJクラスにより保持されていたオブジェクトへの参照はすべて排除されますが、アプリケーションからHelpオブジェクトに対して行った他の参照は排除されません。

したがって、dispose()のコール後には、アプリケーションのコード内でOHJオブジェクト(HelpオブジェクトまたはBookオブジェクト)への参照を排除する必要があります。これにより、Javaのガベージ・コレクション・プロセスがOHJオブジェクトを解放します。


  Previous topic
前へ
Next topic
次へ