程式師世界 >> 編程語言 >> JAVA編程 >> 關於JAVA >> 用JavaHelp 2.0構建下一個Java應用程序的幫助系統

用JavaHelp 2.0構建下一個Java應用程序的幫助系統

編輯：關於JAVA

簡介：即使是幫助系統設計師有時也可能需要幫助，有了 JavaHelp 2.0，終於可以提供幫助了。在本文中，將介紹如何使用 Java 平台特有的幫助系統 API 構建一個標准的、全功能的、容易使用的系統，以向 Java 應用程序用戶展示在線信息。

從開發者的角度看，自動化的幫助組件，或者幫助系統，通常是在構建一個 Java 應用程序時最後考慮的事情。不過對於用戶來說，幫助系統是學習新應用程序時非常有價值的資源。隨著對功能更全和更可靠的應用程序幫助系統的需求增加，應用程序開發人員的時間和生產率負擔也隨之增加。幸運的是，Java 平台包括了一個專門構建應用程序幫助系統的 API。

在本文中，將介紹如何使用 JavaHelp 2.0 API 為一個簡單的 Java 應用程序構建一個標准的、全功能的幫助系統。首先將構建一個基本的應用程序幫助系統，它包括一組主題文件、一組導航文件和一組數據文件。然後將介紹如何使這個幫助系統可以被 Java 應用程序使用，並用基於文字或者圖形的導航、預先設置的字體、分層的展示窗口和可搜索的數據庫定制它。還將介紹如何實現上下文敏感的功能、將幫助系統直接加入到應用程序中、合並多個幫助系統以及為幫助系統創建自定義的輕量級組件。在本文最後，我將快速回顧 JavaHelp 2.0 的服務器端幫助系統框架。

注意：本文假定讀者熟悉構建幫助系統的設計考慮並熟悉在 Java 平台上開發企業應用程序。如果有一些 Swing GUI 開發的經驗也會有幫助。

入門

在本文中，將為一個 Tax Calculator 應用程序構建一個 JavaHelp 系統。圖 1 顯示了這個 Tax Calculator。可以在本文最後的參考資料中找到這個例子的源代碼。運行 FirstLook 以顯示 Tax Calculator。

圖 1. Tax Calculator 的 About 頁

在圖 2 中您會看到 Tax Calculator 幫助系統的導航設置。注意突出顯示了後面將要討論的一些導航圖標。

圖 2. 導航幫助系統

安裝 JavaHelp 2.0可以在 JavaHelp 主頁中找到 JavaHelp 2.0 二進制發布。在將下載的 zip 文件解壓縮到所選的目錄中以安裝 JavaHelp 軟件之前，在開發計算機上必須已安裝版本 1.2.2 或者是更高的 J2SE SDK。應當創建一個像 JAVAHELP_HOME這樣的環境變量以包含到安裝 JavaHelp 2.0 的文件夾的路徑。應當在 classpath 中加入
%JAVAHELP_HOME%\javahelp\lib\jhall.jar。

注意在安裝版本 2.0 之前，必須刪除所有以前版本的 JavaHelp。

使用 HelpSet

每一個 JavaHelp 幫助系統都包含一組稱為 HelpSet 的文件。這些文件共同提供了應用程序幫助系統的工作基礎。JavaHelp HelpSet 包括三種類型的文件：

HelpSet 數據文件

導航文件

主題文件

可以在參考資料中找到示例 Tax Calculator 的幫助系統的 HelpSet 文件。HelpSet 數據文件是 TaxCalculatorHelpSet.hs 和 TaxCalculatorMap.jhm。導航文件是 TaxCalculatorIndex.xml、TaxCalculatorTOC.xml 和 TaxCalculatorGlossary.xml。主題文件位於文件夾 TaxCalculator中。請使用這些文件以跟隨下面幾節中的討論。

HelpSet 數據文件

有兩種 HelpSet 數據文件，分別是 helpset 文件和 map 文件。 helpset 文件是幫助系統的主控制文件。它必須有文件擴展名 .hs。 map 文件用於為每一個幫助主題關聯一個 map ID 以進行導航。map 文件的文件擴展名是 .jhm。我將詳細介紹每一種 HelpSet 文件類型。

helpset 文件

helpset 文件提供了應用程序幫助系統的工作基礎。一個典型的 helpset 文件的結構類似清單 1。

清單 1. helpset 文件

<helpset version="2.0"> 　　 　　<view>...</view> 　　... 　　 　　 <presentation>...</presentation> 　　 　　 <impl>...</impl> </helpset>

可以注意到典型的 helpset 文件有四部分：maps（映射）部分、view（視圖）部分、presentation（展示）部分和 implementation（實現）部分。當用戶訪問幫助系統時，系統首先讀取 .hs 文件。它使用在 maps 部分指定的 map 文件尋找所需要的主題文件，在 view 部分的導航文件用於創建導航視圖等。我將用 Tax Calculator 幫助系統作為例子展示這四部分 helpset 文件是如何實際共同工作的。

maps 部分

<maps>元素指定 map 文件，我在下面還將進一步討論。清單 2 顯示了 TaxCalculatorHelpSet.hs 的 maps 部分。注意 TaxCalculatorMap.jhm 是一個 map 文件。它位於 TaxCalculatorHelpSet.hs 所在的同一目錄。

清單 2. maps 部分

<maps> 　　<homeID>overview</homeID> 　　 <mapref location="TaxCalculatorMap.jhm" /> </maps>

view 部分

helpset 文件可以指定一個或者多個 <view>元素，用於指定幫助系統的導航視圖以及它們的導航文件。導航視圖顯示在導航窗格中（請參閱圖 2）。在設置幫助系統時，可以選擇以下的視圖：

javax.help.GlossaryView

javax.help.TOCView

javax.help.IndexView

javax.help.FavoritesView

javax.help.SearchView

清單 3 指定了一個 Glossary 視圖和它的導航文件的位置。

清單 3. 一個 Glossary 視圖元素

<view> 　　<name>Glossary</name> 　　 <label>Glossary</label> 　　 <type>javax.help.GlossaryView</type> 　　 <data>TaxCalculatorGlossary.xml</data> 　　 <image>glossary_icon</image> </view>

可以使用任何內容作為視圖的 <name> 和 <label> 。 <type> 元素指定幫助系統的導航視圖，而 <data> 元素指定導航文件的路徑。如果指定 <image> 元素，圖像將顯示在導航窗格的頂部作為該視圖的選項卡圖標（如圖 2第 3 部分所示）。元素值 glossary_icon 是在 map 文件中定義的（請參閱清單 6）。

presentation 部分

<presentation>元素定義了幫助窗口屬性，如清單 4 所示。

清單 4. presentation 部分

<presentation default="true"> 　　 <name>Main_Window</name> 　　<size width="640" height="480" /> 　　<location x="0" y="0" /> 　　 <title>Tax Calculator</title> 　　 <image>icon</image> 　　<toolbar> 　　　　 <helpaction>javax.help.BackAction</helpaction> 　　　　 <helpaction　 image="addfav_icon">javax.help.FavoritesAction</helpaction>　　</toolbar> </presentation>

可以在 Java 代碼中調用元素 <name> 的值 -- Main_Window 。將用 <title> 元素指定幫助窗口的標題，用 <image> 元素指定標題欄圖標（見圖 2的第一個面板）。注意這個 icon 是在下面 map 文件中定義的。 <toolbar> 元素也是可配置的。如果沒有指定一個值，那麼幫助系統將包括一些默認的標題欄按鈕。每一個 <helpaction> 對應於幫助窗口工具欄中的一個工具欄按鈕。JavaHelp 提供了八種類型的 helpaction ，如下所示：

BackAction

ForwardAction

SeparatorAction

HomeAction

ReloadAction

PrintAction

PrintSetupAction

FavoritesAction

請參見前面的圖 2，您會看到工具欄按鈕是（從左到右）： BackAction、 ForwardAction、SeparatorAction、HomeAction、ReloadAction、 SeparatorAction、PrintAction、PrintSetupAction 和 FavoritesAction 。可以通過指定 <helpaction> 元素的 image 屬性改變工具欄按鈕的圖標。注意 addfav_icon 是在下面的 map 文件中定義的。將 <presentation> 標簽的 default 屬性改為 true 將使它成為幫助系統的默認展示。

implementation 部分

在 <impl>元素中，可以指定可以在內容查看器中顯示的文件類型。例如，清單 5 中的代碼使用戶可以觀看 HTML 和 PDF 文件。

清單 5. implementation 部分

<impl> 　　<helpsetregistry helpbrokerclass="javax.help.DefaultHelpBroker" /> 　　 <viewerregistry viewertype="text/html" viewerclass="com.sun.java.help.impl.CustomKit" /> 　　 <viewerregistry viewertype="application/pdf" viewerclass="Your PDF Editor Kit" /> </impl>

map 文件

map 文件是在 HelpSet 數據文件中可以找到的另一種文件類型。它通過將 ID 字符串映射到幫助主題文件的 URL 而為每一個幫助主題關聯一個 map ID。 helpset 文件和導航文件總是通過 map ID 引用幫助主題。map 文件可以將 map ID 分配給任何類型的文件。清單 6 顯示了 Tax Calculator 幫助系統的 map 文件。

清單 6. TaxCalculatorMap.jhm

<map version="2.0"> 　　... 　　<mapID target="overview" url="TaxCalculator/overview.htm" /> 　　 <mapID target="icon" url="images/icon.gif" /> 　　<mapID target="glossary_icon" url="images/g.gif" /> 　　<mapID target="addfav_icon" url="images/addfav_icon.gif" /> 　　... </map>

導航文件

回到原來的 HelpSet，可以看到下一種文件類型是導航文件。四種導航文件是 TOC、Index、Glossary 和 Favorites。幫助系統讀取這些文件中的信息以建立四種類型的導航視圖，然後將它們顯示在導航窗格中。我將詳細介紹每一種導航文件。

TOC

每一個 <tocitem> 元素都可以有屬性 text 、 target 和 image ，如清單 7 所示。 text 屬性的值是 tocItem 的文字標簽。 target 屬性的值是表示幫助主題文件的 map ID。 image 屬性指定一個顯示在 tocItem 左邊的圖片。如果沒有指定一個圖片，那麼幫助系統將使用默認圖片，如圖 2的第四部分所示。清單 7 顯示了 Tax Calculator 幫助系統的 TOC 文件的局部。

清單 7. TaxCalculatorTOC.xml

<toc version="2.0"> 　　... 　　<tocitem text="Pages" image="topLevel"> 　　　　<tocitem text="About Page" target="about" image="secondLevel" /> 　　　　<tocitem text="Color Chooser" target="colorChooser" /> 　　 </tocitem> 　　... </toc>

Index

每一個 <indexitem> 元素都可以有屬性 text 和 target 。 text 屬性的值是 indexItem 的文字標簽。 target 屬性的值是表示幫助主題文件的 map ID。清單 8 顯示了 Tax Calculator 幫助系統的 index 文件的部分內容。

清單 8. TaxCalculatorIndex.xml

<index version="2.0"> 　　... 　　<indexitem text="Color"> 　　　　<indexitem text="Changing Color" target="changeColor"/> 　　　　<indexitem text="Color Chooser" target="colorChooser"/> 　　</indexitem> 　　... </index>

Glossary

Glossary 文件也使用 <indexitem> 元素，如清單 9 所示。

清單 9. TaxCalculatorGlossary.xml

<index version="2.0"> 　　... 　　<indexitem text="Button" target="button_def"/> 　　... </index>

Favorites

幫助系統自動生成 Favorites.xml 文件。它存儲在 usrdir/javahelp 中。如果在同一台計算機中安裝了多個 JavaHelp 系統，那麼將保留最後運行的幫助系統的 Favorites.xml。

主題文件

主題文件為 HTML 格式。建議在 HTML 文件中指定 <title> 標簽，因為 <title> 標簽將用於在搜索數據庫中進行全文搜索 -- 稍後將作介紹。

在編寫了主題文件、導航文件、map 文件和 helpset 文件後，就可以通過運行 %JAVAHELP_HOME%\demos\bin 中的 hsviewer.jar 打開 helpset。圖 3 顯示了浏覽到 TaxCalculatorHelpSet.hs 並單擊 Display 時所出現的情況。

圖 3. hsviewer 中的 Tax Calculator HelpSet

在 Java 應用程序中調用 JavaHelp

在構建了一個基本的幫助系統後，會希望可以在 Java 應用程序中調用它。可以通過單擊一個按鈕或者菜單項調出 JavaHelp 系統。清單 10 顯示了用按鈕調出幫助系統的兩種方式。不管采用哪種方式，第一步都是創建一個新的 helpset（如在前面的練習中所做的）並為它創建 help broker。然後可以利用 help broker 的 enableHelpOnButton() 方法用按鈕調出幫助系統，也可以加入一個名為 CSH.DisplayHelpFromSource() 的操作監聽器。單擊按鈕時，操作監聽器將得到操作源的 helpID 並在幫助查看程序中顯示這個 helpID 。清單 10 中顯示了這兩種方式。

清單 10. ButtonHelp.java

... help_but=new JButton("Help"); ... Classloader loader = ButtonHelp.class.getClassLoader(); URL url = HelpSet.findHelpSet (loader, "TaxCalculatorHelpSet"); try { 　　hs = new HelpSet (loader, url); } catch (HelpSetException e) { 　　...　 } HelpBroker helpbroker = hs.createHelpBroker ("Main_Window"); /**-----the first way of calling a help system--- --------- helpbroker.enableHelpOnButton(help_but, "overview", hs); /**-----the second way of calling a help system----------- ActionListener contentListener = new CSH.DisplayHelpFromSource (helpbroker); CSH.setHelpIDString(help_but, "overview"); help_but.addActionListener (contentListener); */

用菜單項調用幫助系統的過程與此類似。

自定義外觀

盡管一開始完全可以使用默認的 JavaHelp 幫助系統，但是一般會希望定制它的外觀以更好地適合自己的應用程序。在這一節，將介紹如何為 GUI　組件配置特別的圖標，自定義導航標簽和工具欄並設置幫助系統字體。

配置圖標

可在 helpset 文件中配置 JavaHelp 標題欄圖標、工具欄按鈕圖標和導航標簽圖標。標題欄圖標是用 <presentation> 標簽設置的，可以用 <presentation> 標簽的 <helpaction> 元素的一個屬性設置工具欄按鈕圖標，而導航標簽圖標可以在 <view> 標簽中設置。此外，可以在導航文件中設置導航文件項圖標。

基於文字的標簽還是基於圖像的標簽？

可以在幫助系統中使用默認的圖像標簽，也可以使用文字標簽。要使用文字標簽，需要在 TaxCalculatorHelpSet.hs 中將 <presentation> 標簽的 displayviewimages 屬性設置為 false 。例如，代碼 <presentation default="true" displayviewimages="false"> 將得到如圖 4 的第二個面板所示的基於文字的標簽。

圖 4. 圖像標簽和文字標簽

注意如圖 4 所示顯示在文字標簽上的字是 helpset 文件 TaxCalculatorHelpSet.hs 的 <view> 標簽的 <label> 元素的值。

要工具欄還是不要工具欄？

可以顯示不帶工具欄的幫助窗口。要選擇所喜歡的那種方式，運行 ButtonHelp.java 文件的 ButtonHelp.class 並單擊 Help 按鈕。將會看到兩個幫助窗口，一個帶工具欄，另一個不帶。如果選擇不帶工具欄，只要在 helpset 文件 TaxCalculatorHelpSet.hs 中創建一個沒有 <toolbar> 元素的 <presentation> 標簽。

設置字體

設置幫助系統的字體非常容易。例如，代碼 Font font = new Font ("SansSerif", Font.ITALIC, 10); helpbroker.setFont(font); 將產生如圖 5b 所示的自定義字體，可以與圖 5a 所示的默認字體進行比較。

圖 5a. 默認字體顯示

圖 5b. 自定義字體顯示

使用展示窗口

在 JavaHelp 幫助系統中有三種類型 -- 或者層 -- 的幫助窗口：

主窗口可以有圖標、改變大小、讓用戶移動和讓用戶關閉。在默認情況下，主窗口包含一個工具欄、一個導航窗格和一個內容查看器。

二級窗口可以有圖標、改變大小、讓用戶移動、可以讓用戶關閉或者在關閉幫助查看器時關閉它。它可以包含工具欄和導航窗格，但是在默認情況下它只包含一個內容查看器。

彈出窗口專門用於內容敏感的幫助，然而也可以定制它在其他地方使用。這個窗口不能改變大小或者移動，並且失去焦點時關閉。它只包含內容查看器。

在不同的展示窗口之間移動信息很簡單，可以通過配置主題文件或者調用 Java 代碼中的函數實現。在給定主題文件中嵌入一個 <ahref=url> 標簽會在調用時在當前窗口中打開鏈接的文件，不過要在二級窗口或者彈出窗口中顯示新的主題文件需要多做一點工作（在下面討論）。如要對展示做精心調整，可以在 JavaHelp API 中使用帶參數 presentation 的方法。例如， HelpBroker 類的 enableHelpOnButton() 將像下面這樣：

enableHelpOnButton(java.lang.Object obj, java.lang.String id, HelpSet hs, 　　　　java.lang.String presentation, java.lang.String presentationName)

如果采用這種方式，將需要為參數 presentation 選擇 main window 、 secondary window 或者 popup window 。例如，下面一行代碼將使用戶可以單擊按鈕 help_but 在二級窗口中打開幫助主題：

helpbroker.enableHelpOnButton(help_but, "overview", hs, "javax.help.SecondaryWindow", "main");

<object> 標簽

如果選擇使用主題文件而不是調用 Java 代碼中的函數，那麼將需要在 HTML 文件中加入 <object> 標簽以在不同類型的窗口中移動文件。清單 11 顯示了如何用 <object> 標簽打開一個二級窗口。

清單 11. 打開一個二級窗口

<object CLASSID="java:com.sun.java.help.impl.JHSecondaryViewer"> 　　 <param name="id" value="about"> 　　<param name="viewerActivator" value="javax.help.LinkLabel"> 　　 <param name="iconByName" value="../images/topLevel.gif"> 　　 <param name="viewerSize" value="350,400"> 　　<param name="viewerName" value="TaxCal"> </object>

表 1. object 標簽的有效參數

功能參數說明窗口 viewStyle 可以設置為 javax.help.SecondaryWindow （默認值）或者 java.help.Popup 。內容 id 用在 map 文件中定義的 map ID 指定內容。內容 content 用相對 URL 指定內容。 Activator viewerActivator 可以設置為 javax.help.LinkButton （默認值）或者 javax.help.LinkLabel 。大小 viewerSize 示例：value="300, 400" 表明窗口是 300 像素寬，400 像素高。位置 viewerLocation 示例：value="300, 400" 表明窗口位於離左邊 300 像素，離上邊 400 像素的位置。名字 viewerName 設置窗口的名字。只對 secondaryWindow 起作用， Popup window 忽略這個參數。圖標 iconByID 用在 map 文件中定義的 map ID 指定圖像。圖標 iconByName 用相對 URL 指定圖像。文字 text 用戶將會看到的字符串。文字特性 textFontFamily 可以設置為 Serif、SansSerif、Monospaced、Dialog、DialogInput 或者 Symbol 。文字特性 textFontSize 可以設置為 xx-small 、 x-small 、 small 、 medium 、 large 、 x-large 、 xx-large 、 bigger 、 smaller （bigger 和 smaller 的單位是 1）、 nnpt （將字體大小設置為特定的磅數 nn）、 +n ,-n （ +n 和 -n 將當前基准字體大小增加或者減小 n）、 n （設置字體大小為與索引 n 相關聯的磅數）。文字特性 textFontWeight 可以設置為 plain 或者 bold 。文字特性 textFontStyle 可以設置為 plain 或者 italic。文字特性 textColor 可以設置為 black、blue、cyan、darkGray、gray、green、 lightGray、magenta、orange、pink、red、white 或者 yellow 。

四種 activator

activator是一個用戶單擊以啟動展示窗口（彈出或者二級）的對象。使用參數 viewerActivator 和參數 text 或者 icon 將生成四種 activator：文字標簽、圖像標簽、文字按鈕或者圖像按鈕,如圖 6 所示。（注意第二種 activator 是清單 11中的代碼的結果。）

圖 6. activator 的四種類型

單擊如圖 6 所示的 About 頁上的第二個或者第四個 activator 後，將可發現調出的二級窗口與主窗口幾乎一樣。如果回到 helpset 文件的 <presentation> 標簽，將會看到 Main_Window 展示設置為 default 。因為二級窗口也使用這個默認展示，它也有一個導航窗格和工具欄。

調出展示窗口的完整代碼和展示請見 about.htm。

添加內容敏感的幫助

內容敏感的幫助是向用戶提供信息的特別具有用戶友好特點的方式。當用戶單擊一個特定的圖標或者字段時 -- 如下面例子中顯示的 Calculation 字段 -- 就會有一個彈出窗口解釋功能或者這個字段下一步要做的事情。內容敏感的幫助可以歸為下列三類之一：

窗口級幫助：當 Java 應用程序的窗口擁有焦點時，用戶按下 Help 鍵（ F1 ）以啟動幫助系統的特定主題，它通常是一個介紹主題。

字段級幫助：當 Java 應用程序的 GUI 上的一個特定組件 -- 如文本字段或者按鈕 -- 擁有焦點時，用戶按下 Help 鍵（ F1）或者單擊一個按鈕以啟動幫助系統的描述當前組件的特定主題。

屏幕級幫助：用戶單擊一個按鈕以調出具有描述應用程序當前屏幕的特定主題的幫助系統。

我將在後面幾節中介紹調用各種類型的內容敏感的幫助的基本內容。代碼示例可見 ContextSensitiveHelp.java 文件中的完整源代碼。

窗口級幫助

當用戶處在一個給定應用程序窗口中並發現他或者她需要幫助時，就可調出窗口級幫助。用戶可以按 Help 鍵（ F1）調出窗口級幫助。調出的幫助系統如圖 7 所示。

圖 7. 用 Help 鍵（F1）調出窗口級幫助

為了啟用如圖 7 所示的 Tax Calculator 窗口的 Help 鍵（ F1），要調用 helpbroker.enableHelpKey(getRootPane(), "personal", hs); 。注意我用幫助系統的 map ID personal 設置幫助主題。注意 helpbroker.enableHelpKey() 只對在基於 Swing 的應用程序中 JFrame 的 rootPane 或者基於 AWT 的應用程序的 java.awt.Window 起作用。我將在稍後討論如何啟用字段級組件的 Help 鍵。

字段級幫助

字段級幫助文件是根據焦點啟動的，即光標的位置和按下 Help 鍵。清單 12 顯示了如何用 CSH.DisplayHelpFromFocus() 啟用字段級幫助的 Help 鍵。

清單 12. 用 Help 鍵調出的字段級幫助

CSH.setHelpIDString(maid_tf, "maid"); CSH.setHelpIDString (course_tf, "course"); CSH.setHelpIDString(income_tf, "income"); CSH.setHelpIDString(result_tf, "result"); ActionListener listener = new CSH.DisplayHelpFromFocus (hs, "javax.help.MainWindow", null); maid_tf.addActionListener (listener); course_tf.addActionListener (listener); income_tf.addActionListener (listener); result_tf.addActionListener(listener);

繼續上面的例子，單擊 Calculation 選項卡以轉換到 calculation 頁並將光標移到這一頁上的第一個文字字段 maid_tf 。當光標在 maid_tf 中閃動時，按 F1在主窗口中顯示 Maid Levy 幫助主題，如圖 8 所示。

圖 8. 用 Help 鍵調出的字段級幫助

也可以用按鈕調出字段級幫助，如圖 9 中的一個帶有箭頭的按鈕。為此，應使用 CSH.DisplayHelpAfterTracking() ，如下所示：

help_but.addActionListener(new CSH.DisplayHelpAfterTracking (hs,"javax.help.Popup", "popup"));

注意還有一個彈出窗口展示幫助主題。在單擊箭頭按鈕並將光標移到 maid_tf 字段，然後單擊鼠標，會顯示一個帶有幫助主題 Maid Levy 的彈出窗口，如圖 9 所示。

圖 9. 用按鈕調出字段級幫助

屏幕級幫助

當位於給定應用程序屏幕中的用戶通過單擊一個按鈕請求關於該屏幕的信息（或者幫助）時，就會調出屏幕級幫助。在這個例子中，有一個有四種不同屏幕的選項卡窗格。清單 13 顯示了一種根據當前屏幕顯示幫助的方法。

清單 13. 屏幕級幫助

menu.addChangeListener(new ChangeListener() { public void stateChanged(ChangeEvent evt) { 　　int sel = menu.getSelectedIndex(); 　　if(sel==0) CSH.setHelpIDString (help_but1, "about"); 　　else if(sel==1) CSH.setHelpIDString (help_but1, "preference"); 　　else if(sel==2) CSH.setHelpIDString (help_but1, "personal"); 　　else if(sel==3) CSH.setHelpIDString (help_but1, "calculation"); 　　} }); ... help_but1.addActionListener(new CSH.DisplayHelpFromSource(hs, "javax.help.SecondaryWindow", "secondary"));　　

對象 help_but1 表示圖 10 中帶有文字 Help的按鈕。我為選項卡窗格 menu 添加了一個 ChangeListener 。當焦點變為新的屏幕時，用 CSH.setHelpIDString() 為 help_but1 設置新的 helpID 。注意 help_but1 還有一個名為 CSH.DisplayHelpFromSource() 的操作監聽器。當用戶單擊按鈕時，操作監聽器將得到操作源（即 help_but1 ）的當前 helpID ，並在幫助查看器中顯示這個 helpID 。因此，不管用戶用任何種方法轉換屏幕（使用選項卡或者菜單項），幫助系統都會顯示當前屏幕的正確信息。

圖 10 顯示當用戶轉換到 Preference 屏幕時，顯示描述 preferences 的特定主題。

圖 10. 屏幕級幫助

添加嵌入幫助

在建立了默認在線幫助系統後，可以將它直接嵌入到應用程序的界面中。清單 14 顯示了如何將一個 TOC 視圖嵌入到示例 Tax Calculator 應用程序中。 toc 是一個 JPanel， tabbedpane 將 toc JPanel 關聯到選項卡 TOC。 getNavigatorView() 的參數必須與在幫助文件中定義的視圖的名字相同。它是大小寫敏感的。可以用類似的方式將其他導航視圖嵌入到應用程序中。

清單 14. EmbeddedHelp.java

viewer = new JHelpContentViewer(hs); viewer.setPreferredSize (new Dimension(250,220)); navTOC = (JHelpTOCNavigator) hs.getNavigatorView("TOC").createNavigator(viewer.getModel ()); navTOC.setPreferredSize(new Dimension(150,220)); toc.add (navTOC); toc.add(viewer);

圖 11 顯示了將 TOC 嵌入到 Tax Calculator 應用程序的結果。注意只有在選擇了菜單項 Show 後才會顯示幫助系統。

圖 11. 嵌入的幫助

添加搜索功能

搜索功能是幫助系統的基本部分。要想利用這種功能，需要創建一個搜索數據庫。JavaHelp API 包括一個可以自動索引幫助主題目錄並建立搜索數據庫的功能。按以下步驟創建搜索數據庫：

設置幫助主題所在的目錄為當前目錄。在這個例子中是 src\TaxCalculator 。

運行 %JAVAHELP_HOME%\javahelp\bin\jhindexerTaxCalculator命令。記住 src\TaxCalculator 是存儲主題文件的目錄。這會在當前目錄創建一個名為 JavaHelpSearch的索引文件夾。

運行 %JAVAHELP_HOME%\javahelp\bin\jhsearchJavaHelpSearch命令以驗證搜索數據庫的有效性。如果看到消息 initialized; enterquery，就是成功創建了搜索數據庫。

停用詞

停用詞（Stop words）是在搜索時不提供結果的常用單詞。下面是創建搜索數據庫時使用的默認停用詞。

a all am an and any are as at be but by can could for from etc does do did goes got had has have he her him his how if in is it let me more much must my nor not now of off on or our own see set shall she should so some than that the them then there these this those though to too us was way we what when where which who why will would yes yet you

圖 12 顯示在 EmbeddedHelp 的搜索視圖中搜索單詞 how時所出現的情況。沒有結果顯示，因為在默認情況下 how是一個停用詞。

圖 12. 默認停用詞的搜索結果

自定義停用詞列表

可以創建一個自定義停用詞列表。例如，假設希望將單詞 how從默認停用詞列表中刪除。有兩種方法可以做到這一點，它們都需要用一個配置文件。第一種方法要創建一個配置文件（config.txt），然後將停用詞存到另一個名為 stopWords.txt 的文件中。然後文件 config.txt 用 StopWordsFile stopWords.txt 這一行指定停用詞文件的位置。

清單 15 顯示了這個自定義停用詞文件，其中去掉了單詞 how。注意在 stopWords.txt 中，每個停用詞都必須開始一個新行。

清單 15. stopWords.txt

a all ... his if ...

也可以在配置文件中直接包含所有停用詞。為此，只要創建一個名為 config1.txt 的配置文件並將停用詞直接加入到配置文件中，如下所示：

StopWords a, all,..., his, if...

要索引自定義的停用詞列表，需要讓 src 成為當前目錄並運行命令

%JAVAHELP_HOME%\javahelp\bin\jhindexer -c config.txt TaxCalculator 。用自已的配置文件替換命令中的 config.txt。例如，如果用 -c config1.txt 運行 jhindexer 命令，然後在 EmbeddedHelp 視圖中重新搜索 how，它將會返回幾個結果項，如圖 13 所示。

圖 13.使用自定義停用詞的搜索結果

搜索窗口中的紅圈表明結果項與查詢的相關程度。圓圈填充得越滿，結果項的相關程度就越高。有五種相關程度。在圖 13 中，數字表示查詢在結果文件中匹配的次數。數字右邊的文字是從幫助系統的主題文件中的 <title> 標簽中提取的。

合並 helpset

大型、模塊化的應用程序可能需要創建很多 helpset，甚至可能是由開發應用程序不同方面的不同小組所創建的。讓用戶分別觀看每一個 helpset 當然是有用的，但是他或者她可能還想將所有 helpset（或者主題列表）作為一個整體來看。要做到這一點，可以合並 helpset。

在 JavaHelp 2.0 中有四種合並類型： SortMerge、UniteAppendMerge 、 AppendMerge 和 NoMerge 。表 2 列出了這四種合並類型及它們的特點。

表 2. JavaHelp 2.0 合並類型

SortMerge UniteAppendMerge AppendMerge NoMerge 這種合並類型完全按字母排序。如果在一個新視圖中的項與在現有視圖中的一項有同樣的文字和目標，那麼在合並的視圖中這兩項將成為一項。如果只有文字是相同的，那麼在項的結尾處將加上 helpset 標題。這種合並類型保留現有視圖層次結構。它將兩個視圖中匹配的元素合並為一個元素，然後合並且排序匹配元素的所有子元素。它將所有剩下的元素附加到現有視圖的最後。這種合並類型只是將新視圖數據附加到現有視圖數據之後。不進行合並。 Search 視圖的默認合並類型。沒有視圖默認使用這種類型的合並。 TOC、Index 和 Glossary 視圖的默認合並類型。 Favorites 視圖的默認合並類型。

每種合並類型都是在 helpset 文件或者在導航文件中指定的。為了正確合並，現有 helpset 的視圖名和新 helpset 的視圖名必須相同。可以靜態或者動態地合並 helpset。

靜態和動態合並

可以通過在現有 helpset 文件中添加 <subhelpset>標簽靜態合並 helpset。如果使用絕對路徑，那麼位置應當有前綴 file:\，如 : <subhelpset location="file:\...\helpset.hs">。如果使用相對路徑，那麼位置看起來應當像這樣： <subhelpset location="helpset.hs">。

可以用方法 hs.add(hs1)、hs.remove(hs1) 動態合並 helpset。 hs 是現有 helpset，而 hs1 是新的 helpset。要看到動態合並操作的結果，請參見本文源代碼中的 MergeHelp.java 並運行 MergeHelp 。

結果

在圖 14 中有兩個 helpset TOC 以及合並它們的結果。

圖 14. 合並

在現有 helpset 的 TOC 視圖標簽中添加屬性 mergetype="javax.help.UniteAppendMerge" 將得到圖 14 的第三個面板中的合並的 helpset，如清單 16 所示。

清單 16. Mergetype 屬性 -- TaxCalculatorHelpSet.hs

<view 　　　　 mergetype="javax.help.UniteAppendMerge"> <name>TOC</nam e> <label>TOC</label> <type>javax.help.TOCV iew</type> <data>TaxCalculatorTOC.xml</data> & lt;/view>

圖 14 的第四個面板顯示了在現有 helpset 的 TOC 導航文件中的 tocitem Pages 中添加屬性 mergetype="javax.help.SortMerge" 的結果，如清單 17 所示。注意第三個和第四個面板中 Pages 主題的不同展示。在第三個面板中，新視圖的元素附加到現有視圖的最後。在第四個面板中，新視圖和現有視圖的元素按字母排列。

清單 17. Mergetype 屬性 -- TaxCalculatorTOC.xml

<tocitem text="Pages" image="topLevel" 　　　　 mergetype="javax.help.SortMerge"> 　　　 ...　 </tocitem>

如果選擇了菜單項 Add，那麼就合並兩個 helpset。如果沒有選擇這個菜單項，那麼應用程序就從第一個 helpset 中刪除第二個 helpset。

添加輕量級組件

Java 平台的輕量級組件類可以在定制幫助系統方面發揮很多作用。例如，您已經看到如何用輕量級組件類 JHSecondaryViewer 和 <object> 標簽，創建及打開二級窗口和彈出窗口。在本節，將在這個練習的基礎上創建自己的輕量級組件，然後用 <object> 標簽操縱它。將開發一個組件類 LightWeightCom ，在用戶單擊一個圖像時它會播放一段音頻。

請參閱本文源代碼 LightWeightCom.java 和 LightWeightComBeanInfo.java ，以跟隨本節的例子。要觀看結果，使用 about.htm。

清單 18 中顯示的 BeanInfo類提供了關於輕量級組件的清晰信息。它必須擴展 SimpleBeanInfo。 getPropertyDescriptors()是 ContentViewer使用的這個類中的惟一方法。

清單 18. LightWeightComBeanInfo.java

public PropertyDescriptor[] getPropertyDescriptors() { PropertyDescriptor back[] = new PropertyDescriptor[4]; try { back[0] = new PropertyDescriptor("iconByName", LightWeightCom.class); back[1] = new PropertyDescriptor("iconByID", LightWeightCom.class); back[2] = new PropertyDescriptor("audioByName", LightWeightCom.class); back[3] = new PropertyDescriptor("audioByID", LightWeightCom.class); return back; } catch (Exception ex) { return null; } }

輕量級組件類必須直接擴展 java.awt.Component或者 java.awt.Container ，或者一個實現了輕量級組件的類。這個例子擴展 JLabel，它是一個實現了輕量級組件的類。如果您的組件將利用 View的信息，那麼必須實現 com.sun.java.help.impl.ViewAwareComponent接口的 setViewData()方法。對於這個示例音頻組件，我將利用 View的 helpset 和文檔庫（document base）信息，如清單 19 所示。

清單 19. LightWeightCom.java -- 實現 setViewData

public class LightWeightCom extends JLabel implements ViewAwareComponent { ... public void setViewData(View v) { myView = v; doc = (HTMLDocument) myView.getDocument(); base = doc.getBase(); // Loop through and find the JHelpContentViewer Component c = container = (Component) myView.getContainer(); while (c != null) { if (c instanceof JHelpContentViewer) { break; } c = c.getParent(); } // Get the helpset if there was JHelpContentViewer if (c !=null) { TextHelpModel thm = ((JHelpContentViewer)c).getModel(); if (thm != null) { hs = thm.getHelpSet(); } } } ... }

輕量級組件應當可以接受參數。例如，清單 20 設計為接收 param audioByID。 setAudioByID方法使用由 setViewData()獲取的 helpset 信息。這個方法用 map ID得到主題文件的位置，如下所示。

清單 20. LightWeightCom.java -- setAudioByID

public void setAudioByID(String name) { sound = null; URL url=null; Map map = hs.getCombinedMap(); try { url = map.getURLFromID(ID.create(name, hs)); } catch (java.net.MalformedURLException e2) { return; } sound = Applet.newAudioClip(url); }

編譯 LightWeightCom.java 和 LightWeightComBeanInfo.java 後，將它們的類添加到類路徑中並在幫助主題文件中添加清單 21 中的各行。在這個例子中，我將它們加到 about.htm 中。結果，單擊圖像標簽時，將播放不同的音頻片段。注意 <object>標簽的屬性 CLASSID必須以 java:開始，否則，幫助查看器將忽略它。

清單 21. about.htm 中的 Object 標簽

<OBJECT CLASSID="java:LightWeightCom"> <param name="iconByID" value="top"> <param name="audioByID" value="music"> </OBJECT> <OBJECT CLASSID="java:LightWeightCom"> <param name="iconByName" value="../images/leaf2.gif"> <param name="audioByName" value="../audio/voice.au"> </OBJECT>

基於服務器的幫助

基於服務器的應用程序需要在線幫助。在這一節，將介紹如何向網絡上的用戶展示幫助系統。為了跟隨本節中的練習，最好熟悉 Tomcat Web 服務器以及 JavaBean 和 JavaServer pages （JSP）技術的基礎知識，以及 JavaScript 和 HTML 腳本。

服務器上的服務更少

JavaHelp 2.0 的基於服務器的幫助比基於客戶機的幫助所提供的功能要少，盡管它非常健壯。基於服務器的幫助只包括 TOC、Index 和 Search 視圖，並且它不包括對使用和創建輕量級組件的支持。因此，不能在彈出窗口或者二級窗口中打開主題文件、或者為服務器端幫助系統創建自定義輕量級組件。

設置

我將使用 Tomcat Web server 4.1.18 運行本節中的例子。如果在開發計算機上沒有安裝 Tomcat version 4.0 或者更高版本，那麼現在應當安裝它。（更多信息請參閱參考資料。）

為了完成這些練習，在 Tomcat Web 服務器的 webapps 目錄創建一個文件夾並將其命名為 TaxCalculatorHelp。作為最簡單的基於服務器的幫助設置，我將利用 JavaHelp 2.0 的 serverhelp demo 中的代碼。可以在 % JAVAHELP_HOME%/demos/serverhelp/web 目錄中找到這些代碼。將所有 .js、.html、.jsp、.tld 文件和子文件夾 images拷貝到新的 TaxCalculatorHelp文件夾中。將自己的 helpset 文件也拷貝到這個文件夾。最後，在 TaxCalculatorHelp中，創建一個名為 WEB-INF的文件夾和兩個名字分別為 classes和 lib的子文件夾。將 jh.jar 拷貝到 WEB-INF/lib，就設置完成了。這種設置的例子請見本文源代碼。

JavaHelp 服務器 bean

ServletHelpBroker是存儲幫助狀態信息的 JavaBeans 組件，如所使用的 helpset、當前 ID、當前導航視圖和其他幫助信息。清單 22 的第 1 行定義了 help broker。第 2 和第 3 行通過提供 helpSetName設置特定 helpset 的 help broker。第 4 到第 6 行將新的 helpset 合並到現有的 HelpSet。如果 merge屬性設置為 false，那麼 help broker 將只對現有 HelpSet 起作用。

清單 22. JavaHelp 服務器 bean

1. <jsp:useBean id="helpBroker" class="javax.help.ServletHelpBroker" scope="session" /> 2. <jh:validate helpBroker="<%= helpBroker %>" 3. helpSetName="TaxCalculatorHelp/TaxCalculatorHelpSet.hs"/> 4. <jh:validate merge="<%= true %>" 5. helpSetName="TaxCalculatorHelp/ContextSensitive/HelpSet.hs"< br> 6. helpBroker="<%= helpBroker %>" />

JavaScript 文件

有幾個重要的 JavaScript 文件。tree.js 用於構建樹。可以用這個文件創建 TOC 和 Index 視圖的導航樹。可以用清單 23 中的代碼構建樹。文件 searchList.js 可以用於構建 Search 視圖的樹。util.js 檢查內容中是否有任何改變。如果發生了改變，那麼就會由這個改變觸發更新。

清單 23. 構建樹

indexTree = new Tree(name, lineHeight, selectColor, showIcon, expandAll) indexTree.addTreeNode(parent, idnum, icon, content, helpID, URLData, expandType) indexTree.drawTree(); indexTree.refreshTree();

JSP 文件

要介紹幾個重要的 JSP 文件。navigator.jsp 用於從 helpset 文件中得到視圖。javax.help.TOCView.jsp、javax.help.SearchView.jsp 和 javax.help.IndexView.jsp 分別構建它們相應的視圖。help.jsp 文件控制幫助窗口的整體展示。圖 15中幫助窗口的頂部幀顯示標題（banner）。可以通過修改 banner.html 文件創建自己的標題。也可排除標題。圖 15 中左下方的幀包含文件 navigator.jsp 和一個樹導航器。右下方的幀包含文件 toolbar.html 和幫助主題內容查看器。可以將幀移到其他位置以及加入和 / 或排除幀而改變 GUI 顯示。

讓我們首先分析 navigator.jsp 文件。

清單 24. navigator.jsp

<jh:navigators helpBroker="<%= helpBroker % >" > <td classtableDefStyle BGCOLOR="<%= isCurrentNav.booleanValue() ? "white" : "#E5E5E5" %>" ALIGN="center"> <A class=tabbedAnchorStyle HREF="navigator.jsp?nav=<%= name %>"> <IMG src="<%= iconURL!=""? iconURL : "images/" + className +".gif" %>" Alt="<%= tip % >" border=0> </A> </td> </jh:navigators>

表 3 列出了所有 JSP 擴展。注意所有 JSP 擴展都必須以符號 jh:開始。

表 3. JSP 擴展

標簽說明屬性 validate 用新的 helpset 設置 help broker，它可以與其他 helpset 合並。它還可以指定當前 ID 要求的屬性： helpbroker; 非要求的屬性： setInvalidURL, helpSetName, currentID, merge navigators 返回給定 help broker 的 navigatorView信息要求的屬性： helpbroker; 非要求的屬性： currentNav tocItem 返回給定 TOCView的 tocItem信息要求的屬性： tocView, helpbroker; 非要求的屬性： baseID indexItem 返回給定 IndexView的 IndexItem信息要求的屬性： indexView、 helpbroker，非要求的屬性： baseID searchTOCItem 返回給定 SearchView的 SearchTOCItem信息要求的屬性： searchView、 helpbroker，非要求的屬性： baseID

注意嵌套在 JSP 擴展的正文中的腳本變量 navigators、 tocItem、 indexItem和 searchTOCItem。清單 24用嵌套的變量的名字從 helpset 文件中得到所有視圖。下表顯示了在 <jh:navigators>開始和結束標簽之間可以使用的變量。

表 4. 導航器變量

變量數據類型說明 classname String NavigatorView類的名字，例如， javax.help.TOCView name String 在 helpset 中定義的視圖的名字，在這個例子中，對於 NavigatorView類 javax.help.TOCView它是“TOC” tip String 視圖的工具提示 iconURL String 在 helpset 中的視圖的 image 屬性中定義的圖標位置

現在，讓我們分析文件 javax.help.TOCView.jsp。

清單 25. javax.help.TOCView.jsp

tocTree = new Tree("tocTree", 16, "ccccff", true, false); <% TOCView curNav = (TOCView)helpBroker.getCurrentNavigatorView(); %> <jh:tocItem helpBroker="<%= helpBroker %>" tocView="<%= curNav %>" > tocTree.addTreeNode("<%= parentID %>","<%= nodeID %>","<%= iconURL!=""? iconURL:"null" %>", "<%= name %>","<%= helpID % >","<%= contentURL!=""? contentURL:"null" %>", "<%= expansionType%>" ); </jh:tocItem> tocTree.drawTree(); tocTree.refreshTree();

這段代碼構建當前 helpset 的 TOC 導航樹。可以用類似的方式創建 Search 和 Index 視圖。您已經知道了 JSP 擴展 tocItem、 indexItem和 searchTOCItem及它們的屬性。下面將介紹它們的嵌套變量，可在 <jh:tocItem>、 <jh:indexItem>和 <jh:searchTOCItem>的開始和結束標簽之間調用下面表 5 和表 6 的變量。

表 5. tocItem 和 indexItem 變量的功能

變量數據類型說明 name String 用 tocItem或者 IndexItem的“name”屬性設置的文字 target String 用 tocItem或者 IndexItem的“target”屬性設置的目標 parent String 標識父代碼的十六進制值 parentID String 標識父代碼的字符串 node String 標識當前節點的十六進制值 nodeID String 標識當前節點的字符串 iconURL String 定位在 tocItem或者 IndexItem中的“image”屬性中定義的圖標 contentURL String 由這一項所表示的內容的 URL isCurrentNav Boolean 如果是當前導航器則為 true，否則為 false。注意：這個變量只對 tocItem可用

表 6. searchTOCItem 變量的功能

變量數據類型說明 name String searchTOCItem的名字 helpID String 與 searchTOCItem相關聯的 ID confidence String 查詢結果的相關程度 hits String 在得到的文件中查詢匹配的次數 contentURL String 內容的位置 hitBoundries String 一組邊界

測試服務器端幫助

所有開發過程的最後一步自然是測試工作的成果。要測試服務器端幫助系統，遵循以下步驟：

運行 Tomcat 服務器

打開 Web 浏覽器

進入 URL http://127.0.0.1:8080/TaxCalculatorHelp

跟隨 Web 頁面中的鏈接，可以找到服務器端幫助系統。當進入第一個鏈接時，將會看到與圖 15a 同樣的一個窗口。當進入第二個鏈接時，將會看到與圖 15b 相同的窗口。

圖 15a. 服務器端幫助

圖 15b. 服務器端幫助

結束語

本文介紹了 Java 平台的幫助系統 API: JavaHelp 2.0。利用 JavaHelp，可以容易地在任何 Java 應用程序、組件或者設備中加入全功能的、標准的幫助系統。一個獨立的 JavaHelp 幫助系統可以在任何平台上運行並可以嵌入到任何應用程序中。有了 JavaHelp 2.0，還可以為網絡上的用戶開發健壯的幫助系統，雖然功能沒有那麼全。

JavaHelp 2.0 有許多很好的功能，我們在這篇文章中對它們作了初步探討。通過一步一步的解釋和練習，介紹了如何創建和操縱位於 JavaHelp 2.0 幫助系統核心的主題文件、導航文件和 helpset 數據文件。還介紹了如何定制自己的 helpset、將它嵌入到現有的 Java 應用程序中、合並 helpset、為幫助系統創建輕量級組件插件、為用戶提供上下文敏感的幫助等。在本文的最後介紹了 JavaHelp 2.0 API 的服務器端幫助功能。

在這裡，我鼓勵讀者練習所學的內容。研究本文的源代碼並試著用 JavaHelp 2.0 API 構建不同功能和不同類型的幫助系統。更多參考請參閱參考資料中的文章。