為 RCP 向導頁添加上下文敏感的幫助支持


上下文敏感的幫助 (context-sensitive help) 是指當用戶按下 F1 在您的應用程序中所顯示的關於當前執行的任務的幫助,它為用戶提供動態的、彈出式的幫助信息,以提高系統的易用性。用戶可以在一個向導頁(Wizard page)上按 F1 鍵或者點擊向導頁左下端的問號按鈕以獲得該向導頁的詳細操作信息。本文講解了如何使用 Eclipse Rich Client Platform (RCP) 里的 Help 插件在已有系統上實現向導頁的上下文敏感幫助系統,並通過一個簡單的例子直觀的向讀者展示如何創建 RCP 應用和向導頁,如何激活向導頁的問號按鈕,如何添加 Help 相關的插件,增加擴展點,如何創建幫助內容以及關聯該內容和相應的向導頁等一系列完整過程。為對 RCP 幫助系統感興趣的開發人員提供經驗分享。


Eclipse 的幫助系統是基於一個引用 HTML 文件的 XML 目錄表,它是由已有的 Eclipse 幫助插件實現的。我們可以非常容易的把 Eclipse 幫助插件嵌入到我們自己的 RCP 系統里,從而實現強大的聯機幫助系統,並且擁有全文檢索 , 定義書簽等操作。

創建 RCP 應用和向導頁

創建 RCP 應用

本文我們將首先創建一個獨立的 RCP 應用程序“helpdemo”,其內容是一個帶有標題的應用程序窗口,通過菜單選項可以添加一個向導頁,為這個向導頁實現上下文幫助。

步驟如下:

1)從下拉菜單中選擇新建一個項目,繼而選擇新建 plug-in 項目:

圖 1. 從通用項目庫創建新插件項目
圖 1. 從通用項目庫創建新插件項目

2)在項目名字處寫上“helpdemo”作為項目的名字,然后點擊“Next”按鈕。

圖 2. 指定項目的物理屬性
圖 2. 指定項目的物理屬性

3)在選項“是否創建 Rich Client Application”處,選擇“Yes”,然后點擊“Next”按鈕。

圖 3. 選擇是否創建 RCP
圖 3. 選擇是否創建 RCP

4)在最后一個頁面上選擇需要應用的 Template,選擇“Hello RCP”。

圖 4. 選擇 Hello RCP 模版
圖 4. 選擇 Hello RCP 模版

5)點擊“Finish”按鈕后。我們的 RCP 應用程序就創建出來了。

下面,讓我們測試一下我們創建的 RCP 應用程序。

在 Manifest 編輯器上選擇“Overview”標簽頁,點擊“Testing”下面的“Launch an Eclipse Application”用以運行我們創建的 HelpDemo 應用程序。

圖 5. 運行中的 HelpDemo 應用程序
圖 5. 運行中的 HelpDemo 應用程序

在 Package Explore 里,我們可以看到 
RCP 模板自動為我們創建了以下 5 個類,他們分別作用是:
Application 類 :RCP 應用程序入口 
ApplicationWorkbenchAdvisor 類:初始化界面 
ApplicationWorkbenchWindowAdvisor 類: 負責管理整個窗口生命周期,包括狀態欄、工具欄、菜單、窗口標題、窗口大小和各種控件等等 
ApplicationActionBarAdvisor 類:負責管理窗口的菜單欄、狀態欄、工具欄的外觀設計和行為(action)等 
Perspective 類:界面布局 
接下來我們會修改這些類來添加菜單,激活 Help 按鈕等。

圖 6. helpdemo 應用自動生成的代碼
圖 6. helpdemo 應用自動生成的代碼

修改 RCP 應用標題

找到 eclipse 為我們的 RCP 應用自動生成的 ApplicationWorkbenchWindowAdvisor.java 類,在 preWindowOpen 方法里設定 RCP 應用程序的標題。

清單 1. 修改 RCP 應用標題
 public void preWindowOpen() { 
 …
       configure.setTitle(“Help demo”); // 修改 title 
 }

再次運行 RCP 應用,我們可以看到標題已經從“Hello RCP”變成“Help demo”了。

圖 7. 修改 RCP 應用標題
圖 7. 修改 RCP 應用標題

創建一個向導頁 (WizardPage)

在 Eclipse 里,向導(Wizard)是由 WizardDialog,Wizard 和 WizardPage 三部分組成的。他們三者之間,可以看成前者是后者的容器。最終顯示在用戶面前的是向導頁(WizardPage)。向導頁包含多種 SWT 界面元素,構建出一個復雜的頁面,同時向導頁上還定義了界面元素的操作行為。而我們的幫助支持就是在向導頁上按 F1 鍵或者點擊向導頁左下端的問號按鈕被調用的。
所以接下來,我們先創建一個簡單的向導頁示例,供后續使用。

清單 2. 創建向導頁示例
 package helpdemo; 
 import org.eclipse.jface.wizard.WizardPage; 
 import org.eclipse.swt.SWT; 
 import org.eclipse.swt.layout.GridData; 
 import org.eclipse.swt.layout.GridLayout; 
 import org.eclipse.swt.widgets.Composite; 
 import org.eclipse.swt.widgets.Label; 
 import org.eclipse.ui.PlatformUI; 
 public class WizardPageA extends WizardPage { 
      protected WizardPageA(String pageName) { 
      super(pageName); 
      this.setTitle(pageName); 
      } 
 public void createControl(final Composite parent) { 
      final Composite composite = new Composite(parent, SWT.NONE); 
      setControl(composite); 
      composite.setLayout(new GridLayout(1, false)); 
      Label description = new Label(composite, SWT.WRAP); 
      description.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, false, 1, 1)); 
      description.setText("This is a WizardPage for Help Demo."); 
      } 
 }

創建向導

向導(Wizard)是裝載了一系列向導頁的容器。通過向導,我們可以根據需求加載一系列向導頁,構建出復雜的界面,並且加載具體的業務邏輯處理方法。在我們的例子中,只創建了一個向導頁,並且把向導頁 WizardPageA 加入了向導 WizardA 中。

清單 3. 創建向導
 package helpdemo; 
 import org.eclipse.jface.wizard.Wizard; 
 public class WizardA extends Wizard { 
       private WizardPageA wizardA; 
       public WizardA() { 
              wizardA = new WizardPageA("WizardPage A"); 
              this.addPage(wizardA); 
       } 
       public boolean canFinish() { 
              return true; 
       } 
       public boolean performFinish() { 
              return true; 
       } 
 }

創建向導對話框

向導對話框(WizardDialog)是向導的容器。通過向導對話框可以構造出一個完整的 GUI 界面以及操作界面。它負責裝載向導類,操作時通過按鈕 Back、Next 來在多個向導頁之間切換。

清單 4. 創建向導對話框
 package helpdemo; 
 import org.eclipse.jface.wizard.IWizard; 
 import org.eclipse.jface.wizard.WizardDialog; 
 import org.eclipse.swt.widgets.Shell; 
 public class WizardDialogA extends WizardDialog{ 
      public WizardDialogA(Shell parentShell, IWizard newWizard) { 
            super(parentShell, newWizard); 	
           // TODO Auto-generated constructor stub 
      } 
 }

創建 action 類用來彈出向導對話框

下面,我們要定義響應菜單或者工具欄按鈕的 action 類。通過重寫 run() 方法打開向導對話框。

清單 5. 定義 action 類
 package helpdemo; 
 import org.eclipse.jface.action.Action; 
 import org.eclipse.jface.action.IAction; 
 import org.eclipse.jface.viewers.ISelection; 
 import org.eclipse.ui.IWorkbenchWindow; 
 import org.eclipse.ui.IWorkbenchWindowActionDelegate; 
 import org.eclipse.ui.PlatformUI; 
 public class NewWizardAction extends Action implements IWorkbenchWindowActionDelegate { 
       @Override 
       public void run(IAction action) { 
         WizardA wizardOne = new WizardA(); 
        WizardDialogA dialog = new WizardDialogA(PlatformUI.getWorkbench(). 
              getActiveWorkbenchWindow().getShell(), wizardOne); 
        dialog.create(); 
        dialog.open(); 
       } 
       @Override 
       public void selectionChanged(IAction action, ISelection selection) { 
         // TODO Auto-generated method stub 
       } 
       @Override 
       public void dispose() { 
         // TODO Auto-generated method stub 
       } 
       @Override 
       public void init(IWorkbenchWindow window) { 
         // TODO Auto-generated method stub 
        } 
 }

添加菜單 Menu

我們需要在已有的 RCP 應用里添加菜單。找到名為"ApplicationActionBarAdvisor"的類。修改 fillMenuBar 方法,在其中新建 MenuManager,並且把其加入到 menubar 中。

清單 6. 添加菜單 Menu
 public void fillMenuBar(IMenuManager menuBar) { 
         MenuManager menu = new MenuManager(“&Menu”,”Menu”); 
         menuBar.add(menu); 
     }

添加 actionset

插件開發環境提供了 Manifest 編輯器來為插件的配置文件提供圖形化的編輯功能。我們切換到“plugin.xml”的 tab 頁直接修改代碼,增加以下擴展點(extension),加入 actionset。

清單 7. 添加 actionset
 <extension 
 point="org.eclipse.ui.actionSets"> 
 <actionSet 
     id="helpdemo.NewWizard"
     label="NewWizard"
     visible="true"> 
     <action 
         class="helpdemo.NewWizardAction"
         id="helpdemo.NewWizard"
         label="&amp;NewWizard"
         menubarPath="Menu/NewWizard"
         style="push"> 
     </action> 
 </actionSet> 
 </extension>

測試

下面來測試下我們創建的 RCP 向導對話框,向導頁以及 action。運行應用程序后,一個標題為 Help Demo 的對話框彈了出來,其中在菜單欄上還有我們新建立的菜單。

圖 8. 點擊 Menu
圖 8. 點擊 Menu

點擊 menu->NewWizard,我們的 WizardPageA 被打開。

圖 9. 向導頁
圖 9. 向導頁

這個向導頁,就是我們即將加入上下文敏感幫助支持的頁面。如果你的程序已經能成功顯示,那我們的准備工作已經就緒。下面,將開始添加 Help 了。

激活向導頁的 help 按鈕

在前一步生成的 RCP 應用的類中找到 ApplicationWorkbenchAdvisor 類。我們需要在其中激活 help 按鈕,也就是我們通常在 eclipse 的向導頁看到的左下角的問號。
重寫 initialize 方法。 把對話框的“setDialogHelpAvailable”方法設成 true 就代表激活 help 按鈕。同時,需要 import IWorkbenchConfigurer 和 TrayDialog 類。

清單 8. 激活 help 按鈕
 import org.eclipse.jface.dialogs.TrayDialog; 
 import org.eclipse.ui.application.IWorkbenchConfigurer; 
 @Override 
 public void initialize(IWorkbenchConfigurer configurer) { 
 TrayDialog.setDialogHelpAvailable(true); 
 }

運行 RCP 應用,可以看到 help 按鈕已經出現在 wizardPage 的左下角。

圖 10. 激活了 help 按鈕的向導頁
圖 10. 激活了 help 按鈕的向導頁

此時點擊 help 按鈕沒有任何反應,因為我們還沒有加入 help 的相關依賴。

添加 Help 插件依賴

接下來我們需要把 help 相關的插件導入到我們的項目中,這些插件包括:
org.eclipse.help
org.eclipse.help.base
org.eclipse.help.ui
org.eclipse.help.webapp

在 Manifest 編輯器打開“Dependencies”tap 頁面通過點擊”Add”按鈕依次加入以上 help 插件依賴。

圖 11. 添加 help 依賴
圖 11. 添加 help 依賴

增加擴展點 help.contexts 到 plugin.xml

在 plugin.xml 中增加 help.contexts 擴展點,help_contexts.xml 是定義幫助內容的配置文件。

清單 9. 在 plugin.xml 中增加 help.contexts 擴展點
   <extension 
      point="org.eclipse.help.contexts"> 
      <contexts 
            file="help_contexts.xml"
            plugin="helpdemo"> 
      </contexts> 
   </extension>

創建幫助內容

清單 10. help_contexts.xml 內容
 <contexts> 
   <context id="WizardA"> 
   <description>WizardA: Demo for context-sensitive help. 
   </description> 
   <topic href="html/WizardA_subtopic.html"
     label="WizardA:Subtopic" /> 
   </context> 
 </contexts>
清單 11. WizardA_subtopic.html 內容
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> 
 <html> 
 <head> 
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 
 <title>Table of Contents</title> 
 </head> 
 <body> 
 <h3>WizardA_subtopic</h3>This is Help Content Page. 
 </body> 
 </html>

help_contexts.xml 和 html/WizardA_subtopic.html 位置如下

圖 12. 幫助文檔內容文件位置
圖 12. 幫助文檔內容文件位置

通過 context id 關聯向導頁及其對應的幫助內容

添加下面代碼到向導頁 WizardA 的 createControl 方法:

清單 12. 關聯向導頁極其對應的幫助內容
 public void createControl(finalComposite parent) 
 {  
      ……  
           
 PlatformUI.getWorkbench().getHelpSystem().setHelp(getShell(), 
                                             "helpdemo.WizardA"); 
  
  // 需要指定 helpdemo 以此來保證 context id 的唯一性
  
  }

通過添加以上代碼,將向導頁 WizardA 和它對應的幫助內容頁面通過 context id“helpdemo.WizardA”關聯起來。
運行結果:點擊 help 按鈕或者按 F1,上下文幫助頁面將被打開。其中,我們可以看到幫助主題:WizardA:Subtopic。

圖 13. 上下文敏感幫助運行結果
圖 13. 上下文敏感幫助運行結果

其中右邊部分的描述,及 topic 等就是 help_contexts.xml 里的內容。
點擊超鏈接 WizardA:Subtoic 將打開我們新建的 help 內容頁面,即 html/WizardA_subtopic.html 頁面的內容。

圖 14. 上下文敏感幫助內容頁面
圖 14. 上下文敏感幫助內容頁面

至此,RCP 向導頁面的上下文敏感的幫助支持全部實現了。

結束語

利用 eclipse 提供的強大的 help 插件可以簡化 help 系統的開發。通過本文提供的方法,我們能夠有效的利用 Eclipse 中的 help 插件為自己的 RCP 程序創建出上下文敏感的幫助系統,從而進一步完善產品的開發。


轉自http://www.ibm.com/developerworks/cn/opensource/os-cn-rcp-contexthelp/index.html


注意!

本站转载的文章为个人学习借鉴使用,本站对版权不负任何法律责任。如果侵犯了您的隐私权益,请联系我们删除。



 
粤ICP备14056181号  © 2014-2021 ITdaan.com