アプリケーションへのOHJの追加
ここでは、製品アプリケーションにOHJを統合する方法について説明します。項目は、次のとおりです。
手順の詳細は、次の各項で説明します。
アプリケーションへのOHJの追加の概要
アプリケーションへOHJを追加する基本的な手順は、次のとおりです。
Help
オブジェクトを作成します。
- 次のとおりに
Help
オブジェクトにヘルプ・コンテンツを移入します。
- ヘルプ・データを表す
Book
オブジェクトを作成します。
- その
Book
オブジェクトをHelp
オブジェクトに追加します。
- OHJのナビゲータ・ウィンドウを表示する方法、およびヘルプ・トピックを表示する方法を実装します。
- アプリケーションのライフ・サイクルの終了とともに
Help
オブジェクトを破棄します。
Help
オブジェクトの作成
Help
オブジェクトは、Oracle Help for Javaへのエントリ・ポイントとなるものです。これには、ヘルプのコンテンツを追加する方法と、OHJのナビゲータ・ウィンドウおよび特定のトピックを表示する方法が含まれます。Help
オブジェクトの作成時に設定できるいくつかのオプションがあります。
Help
オブジェクトのコンストラクタに指定されたboolean combineBooks
パラメータによって、複数のBook
(HelpBook
またはHelpSet
、あるいはその両方)がOHJでどのように表示されるかが決定されます。boolean combineBooks
パラメータをtrue
に設定した場合、作成者の定義した表示でtypeおよびlabelの同じものは、すべてマージされます。たとえば、複数のブックにラベルの同じ索引が含まれていると、キーワードのリストをマージおよびソートして、1つの索引がナビゲータに表示されます。combineBooks
パラメータがfalse
の場合は、各ブックの表示が別々に表示され、エンド・ユーザーはナビゲータ・ウィンドウのドロップダウン・リストを使用して、表示するブックを選択することができます。(どちらの振舞いが実装されるかは、通常ヘルプの作成者が指定します。)
各種のHelp
オブジェクトについて、次の表にまとめます。詳細は、APIのドキュメントのoracle.help.Help
を参照してください。
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(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(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
インスタンスを構築した後、その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()
メソッドをコールし、そのトピックにトピック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オブジェクトを解放します。
Copyright © 1996, 2004, Oracle. All rights reserved.