ナビゲーション・ヘッダーをスキップ
Oracle Help for Java開発者ガイド Table of Contents
目次
Previous topic
前へ
Next topic
次へ

アプリケーションへのOHJの追加

ここでは、製品アプリケーションにOHJを統合する方法について説明します。項目は、次のとおりです。

手順の詳細は、次の各項で説明します。

アプリケーションへのOHJの追加の概要

アプリケーションへOHJを追加する基本的な手順は、次のとおりです。

  1. Helpオブジェクトを作成します。
  2. 次のとおりにHelpオブジェクトにヘルプ・コンテンツを移入します。
  3. OHJのナビゲータ・ウィンドウを表示する方法、およびヘルプ・トピックを表示する方法を実装します。
  4. アプリケーションのライフ・サイクルの終了とともにHelpオブジェクトを破棄します。

Helpオブジェクトの作成

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

Helpオブジェクトのコンストラクタに指定されたboolean combineBooksパラメータによって、複数のBookHelpBookまたはHelpSet、あるいはその両方)がOHJでどのように表示されるかが決定されます。boolean combineBooksパラメータをtrueに設定した場合、作成者の定義した表示でtypeおよびlabelの同じものは、すべてマージされます。たとえば、複数のブックにラベルの同じ索引が含まれていると、キーワードのリストをマージおよびソートして、1つの索引がナビゲータに表示されます。combineBooksパラメータがfalseの場合は、各ブックの表示が別々に表示され、エンド・ユーザーはナビゲータ・ウィンドウのドロップダウン・リストを使用して、表示するブックを選択することができます。(どちらの振舞いが実装されるかは、通常ヘルプの作成者が指定します。)

各種のHelpオブジェクトについて、次の表にまとめます。詳細は、APIのドキュメントoracle.help.Helpを参照してください。

Help() Constructors
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に設定してください。

ヘルプ・データの追加

Helpオブジェクトの作成後、1つ以上のBookオブジェクトをこのHelpオブジェクトに追加する必要があります。Bookオブジェクトは、ヘルプ・コンテンツの集合またはブックをカプセル化します。Bookインタフェースには2種類の実装があり、それぞれ異なる制御ファイル形式を扱います。

HelpSet。この実装では、「Oracle Helpのファイル形式」で説明されているように、デフォルトとなったOracle Helpのファイル形式を扱います。これらのファイルには、ヘルプ・システムの特性を定義するヘルプセット・ファイルが含まれます。

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

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

HelpSetの作成

HelpSet()コンストラクタは、次のとおりです。

HelpSet()コンストラクタ
HelpSet(URL fileURL)

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

パラメータ:

fileURL - ヘルプセット・ファイルの絶対パスを指定するURL。

HelpSet(Class pathClass, String pathExtension)

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

パラメータ:

pathClass - アプリケーション・クラスの1つ。HelpSetオブジェクトでは、このクラスの位置を使用して、ヘルプセット・ファイルの位置を決定します。

pathExtension - pathClassに対して相対的な、ヘルプセット・ファイルへのパス。このパラメータの値が、pathClassを含むディレクトリへの絶対パスに追加されます。追加後のパスが、ヘルプセット・ファイルへのパスになります。

詳細は、APIのドキュメントoracle.help.library.helpset.HelpSetを参照してください。

HelpBookの作成

HelpBook形式は、ディレクトリに基づいています。そのコンストラクタを使用して、ヘルプのコンテンツ(HTMLトピック・ファイル)を含むディレクトリの位置を指定します。

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

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

パラメータ:

baseURL - ヘルプセット・ファイルの絶対パスを指定するURL名。

baseName - 指定したディレクトリで検出されたすべての制御ファイルのベース名(たとえば、制御ファイルの名前がuserguide.hhc、userguide.hhkなどであれば、baseNameはuserguideとなります)。

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 - このブック名は、複数ブックのヘルプ・システムの場合にプルダウン・メニューで表示されます。(タイトルは、多くの場合ヘルプの作成者によって指定されます。)

詳細は、APIのドキュメントoracle.help.library.helpbook.HelpBookを参照してください。

HelpへのBookの追加

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

addBook()メソッド
addBook(Book book)

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

パラメータ:

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

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

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

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

showNavigatorWindow()メソッドをコールすることによって、OHJのナビゲータ・ウィンドウを表示するようHelpインスタンスに指示します。このメソッドのいくつかのバージョンは、指定のナビゲータ・タブ(たとえば「目次」、「索引」、「検索」など)を選択してナビゲータ・ウィンドウを表示するための追加パラメータをとります。

showNavigatorWindow()メソッド
showNavigatorWindow()

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

showNavigatorWindow(Book activeBook)

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

パラメータ:

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

showNavigatorWindow(Navigator activeNavigator)

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

パラメータ:

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

トピックの表示

showTopic()メソッドをコールし、そのトピックにトピックIDおよびBookインスタンスを指定することによって、特定のヘルプ・トピックを表示するようHelpインスタンスに指示します。このメソッドのいくつかのバージョンは、トピックの表示方法を指定する追加のパラメータをとります。

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

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

パラメータ:

book - 表示するトピックを含むBook

topicID - 表示するトピックのトピックID(ブックのマップ・ファイルで指定されます)。

showTopic(Book book, String topicID, boolean alwaysCreate)

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

パラメータ:

book - 表示するトピックを含むBook

topicID - 表示するトピックのトピックID(ブックのマップ・ファイルで指定されます)。

alwaysCreate - trueの場合、常に新規のウィンドウが作成されます。falseの場合、可能であればウィンドウを再利用します。

showTopic(Book book, String topicID, boolean alwaysCreate, Point location, Dimension size)

指定したbookから、指定したトピックを表示します。alwaysCreatetrueの場合、常に新規のウィンドウが作成されます。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()

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

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

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