功能表和工具列路徑

我們已經見過指定其動作位置路徑的動作構成要素。 現在,我們要仔細查看這些路徑代表什麼。  

功能表路徑

首先,我們將藉由查看工作台說明功能表來查看功能表路徑。

工作台中的具名群組

插入新功能表和功能表項目的位置是利用具名群組來定義的。 您可以將具名群組想成是一個槽或位置保留器,可讓您在功能表列或下拉功能表的某些點上插入您的功能表項目。

工作台會在 IWorkbenchActionConstants 中定義它的所有群組槽名稱。 對於每個工作台功能表,具名群組都會放在功能表中外掛程式應在其中插入新動作的位置上。

下列說明功能表的說明取自 IWorkbenchActionConstants 類別定義。

標準「說明」功能表動作
   啟動群組 - HELP_START - "start"
   結束群組 - HELP_END - "end"
   關於動作 - ABOUT - "About"

標準工作台說明功能表依次稱為 "start"、稱為 "end" 的具名群組及 "About" 動作組成。 定義兩個群組給予外掛程式它們在說明功能表中的項目提供定位有更多控制權。當您定義功能表時,您可以定義您需要的任意數目的槽。新增較多的槽會使外掛程式更能夠控制它們的構成要素相對於現有構成要素的出現位置。

但請等一下!我們知道,「說明」功能表中還有其他功能表項目。它們是外掛程式所新增的。 比方說,說明外掛程式會新增含有「說明內容」功能表的動作集到工作台中。以下是取自 org.eclipse.help.ui 外掛程式之 plugin.xml 的標記。

<extension point="org.eclipse.ui.actionSets">
	<actionSet
		id="org.eclipse.help.internal.ui.HelpActionSet"
		label="%help"
		visible="true">
			
	<action id="org.eclipse.help.internal.ui.HelpAction"
		menubarPath="help/helpEnd"
		label="%helpcontents"
		class="org.eclipse.help.ui.internal.HelpContentsAction"
		icon="icons/view.gif"
		helpContextId="org.eclipse.help.ui.helpContentsMenu"
		tooltip="%openhelpcontents"/>
	...

新說明動作會放在說明功能表的 helpEnd 群組內。 如果沒有提供其他外掛程式到說明功能表中,這表示「說明內容」功能表項目會出現為在「關於」項目上的功能表其中的第一個項目。 如果另一個外掛程式要提供一律出現「說明內容」上的項目,它可以在它的路徑中指定 helpStart 群組。  

完整功能表路徑

完整功能表路徑是簡單的「功能表名稱 / 群組名稱」。工作台的功能表名稱定義於 IWorkbenchActionConstants。 這個類別,用來尋找我們的說明動作的完整名稱是 "help/helpEnd"。

有些功能表有巢狀子功能表。 這會帶來較長的路徑。 如果說明功能表以稱為 "submenuStart" 的具名群組定義了稱為 "submenu" 的子功能表, 新子功能表中之動作的完整功能表路徑會是 "help/submenu/submenuStart"。

外部化 UI 標籤

上述範例會示範外部化出現在 UI 中之字串的技術。使用外部化字串,使得將外掛程式 UI 翻譯成其他語言更為容易。 我們可以將字串改成某個鍵(如 %help,%helpcontents),並採用下列形式在 plugin.properties 檔中建立項目,以在我們的 plugin.xml 檔中將字串外部化:

   help = "Help"
   helpContents = "Help Contents"

可以將 plugin.properties 檔翻譯成不同的語言,而不需要修改 plugin.xml

新增新的功能表和群組

在目前已見到的許多範例中,範例外掛程式所提供的動作已在功能表中,新增到現有的具名群組中。

actionSetsviewActionseditorActionspopupMenus 延伸點也可讓您在構成要素內定義新的功能表和群組。 這表示您可以定義新的子功能表或新下拉功能表,並將您的動作新增到這些新功能表中。 在這個情況下,新動作的路徑會含有新定義的功能表的名稱。

當 Readme 工具定義其動作集的新功能表時,我們見過這個技術。現在,我們要再檢視一次這個標記,更詳細看看功能表路徑。

   <extension point = "org.eclipse.ui.actionSets">   <actionSet id="org_eclipse_ui_examples_readmetool_actionSet"
	   label="%ActionSet.name"
	   visible="true">
	   <menu id="org_eclipse_ui_examples_readmetool"
		   label="%ActionSet.menu"
		   path="window/additions"> 
            <separator name="slot1"/>
            <separator name="slot2"/>
            <separator name="slot3"/>
	   </menu>
	   <action id="org_eclipse_ui_examples_readmetool_readmeAction"
		   menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
		   toolbarPath="readme"
		   label="%ReadmeAction.label"
		   tooltip="%ReadmeAction.tooltip"
		   helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context"
		   icon="icons/ctool16/openbrwsr.gif"
		   class="org.eclipse.ui.examples.readmetool.WindowActionDelegate"
		   enablesFor="1">
		   <selection class="org.eclipse.core.resources.IFile"
				name="*.readme">
		   </selection>
	   </action>
	   ...

我們新增一個新的功能表,叫做  "org_eclipse_ui_examples_readmetool", 標籤是由內容檔中的 "%ActionSet.name" 鍵所定義。 在這個功能表中,我們定義三個命名群組:  "slot1"、"slot2" 和 "slot3"。我們新增這個新功能表到 "window/additions" 路徑中。

如果我們回到 IWorkbenchActionConstants,我們會在 javadoc 中見到視窗功能表的這個定義:

    * <h3>標準「視窗」功能表動作</h3>
    * <ul>
 *   <li>額外視窗型動作群組 (<code>WINDOW_EXT</code>)</li> 

如果我們再檢視類別定義,就會看到這些相關定義:

   public static final String MENU_PREFIX = "";
   ...
    public static final String M_WINDOW = MENU_PREFIX+"window";   ...
   public static final String MB_ADDITIONS = "additions";  // Group.
   ...
public static final String WINDOW_EXT = MB_ADDITIONS;   // 群組。

從這項資訊中,我們可以將新增內容到工作台「視窗」功能表的路徑拼合起來。 功能表本身稱為視窗,它定義一個稱為新增內容的槽。 我們利用window/additions來新增我們的新功能表。

在動作集宣告中,我們利用 "window/org_eclipse_ui_examples_readmetool/slot1" 路徑來新增一個動作到新定義的功能表中。

其他外掛程式也可以利用這個相同的路徑(或能是另一個槽)來新增它們自己的功能表到我們的功能表中。

在 readme 工具範例中,我們使用 separator 屬性來識別群組名稱。 當這些群組含有項目時,這將導致它們之間出現一條分隔線。 如果我們想要定義一個具名群組,但不想要在功能表中顯示任何分隔符號, 以區隔這些群組,我們可以改為使用 groupMarker 屬性。

工具列路徑

工具列路徑的運作類似於功能表路徑。  

工作台中的具名工具列

工作台工具列是由不同外掛程式(包括工作台本身)提供的工具列所組成。 在任何特殊工具列內,有若干具名群組或槽,可用於插入新的工具列項目。    

下列工作台工具的說明取自 IWorkbenchActionConstants 類別定義。

// 工作台工具列 ID
public static final String TOOLBAR_FILE = "org.eclipse.ui.workbench.file"
public static final String TOOLBAR_NAVIGATE = "org.eclipse.ui.workbench.navigate"; 

// 工作台工具列 ID。若要在群組開始處新增項目,
// 請使用 GROUP ID。若要在群組的結尾處新增項目,請使用 EXT ID。
public static final String PIN_GROUP = "pin.group"; 
public static final String HISTORY_GROUP = "history.group"; 
public static final String NEW_GROUP = "new.group"; 
public static final String SAVE_GROUP = "save.group"; 
public static final String BUILD_GROUP = "build.group"; 

在最簡單的情況中,外掛程式可以在它自己的工具列中提供工具列項目。 舉例來說,提供給功能表的 readme 工具動作也會給定一個工具列路徑:

...
<action id="org_eclipse_ui_examples_readmetool_readmeAction"  
            menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
   toolbarPath="readme"
...

既然沒有工作台工具列路徑或群組的參照,那麼 readme 動作就會出現在工具列上它們自己的群組中。 指定下列路徑反而會將檔案工具列中的項目置於儲存群組中:

...
<action id="org_eclipse_ui_examples_readmetool_readmeAction"  
            menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
   toolbarPath="org.eclipse.ui.workbench.file/save.group"
...

在其他外掛程式的工具列路徑中,可以參照 IWorkbenchActionConstants 中定義的路徑。

新增至另一個外掛程式的動作集

假設外掛程式想要它的工具列項目能與來自不同外掛程式的動作有更佳整合? 讓我們查看外部工具外掛程式 (org.eclipse.ui.externaltools) 如何整合它的動作與除錯器工具列。 除錯器 (org.eclipse.debug.ui) 的工具列動作定義如下:

   <extension
      point="org.eclipse.ui.actionSets">
<actionSet         label="%LaunchActionSet.label"
   visible="false"
         id="org.eclipse.debug.ui.launchActionSet">
   ...
         <action
         toolbarPath="debug"
         id="org.eclipse.debug.internal.ui.actions.RunDropDownAction"
         hoverIcon="icons/full/ctool16/run_exc.gif"
         class="org.eclipse.debug.internal.ui.actions.RunToolbarAction"
         disabledIcon="icons/full/dtool16/run_exc.gif"
         icon="icons/full/etool16/run_exc.gif"
         helpContextId="run_action_context"
         label="%RunDropDownAction.label"
         pulldown="true">
         </action>
   ...

正如同 readme 工具一般,除錯器外掛程式會定義它自己的工具列路徑, 表示它的工具列項目將位於工作台上它們自己的工具列內。 外部工具外掛程式的作用為何?

<extension point="org.eclipse.ui.actionSets">
	<actionSet
		id="org.eclipse.ui.externaltools.ExternalToolsSet"
		label="%ActionSet.externalTools"
		visible="true">
		...
		<action
			id="org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar"
			definitionId= "org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar"
			label="%Action.externalTools"
			toolbarPath="org.eclipse.debug.ui.launchActionSet/debug"
			disabledIcon="icons/full/dtool16/external_tools.gif"
			icon="icons/full/etool16/external_tools.gif"
			hoverIcon="icons/full/ctool16/external_tools.gif"
			tooltip="%Action.externalToolsTip"
			pulldown="true"
			class="org.eclipse.ui.externaltools.internal.menu.ExternalToolMenuDelegate">
		   </action>
	   </actionSet>
</extension>

請注意,如何在工具列路徑中使用除錯器的動作集 ID。 在路徑中使用動作集 ID 表示工具列項目應該置於被參照的動作集所使用的工具列中。 在工具列群組中,項目係按照動作集 ID 來排序, 所以在我們的範例中,外部工具動作將出現在除錯器動作之後。 

當新增至另一個動作集的工具列時,也可以定義新的群組。 如果外部工具外掛程式定義了它的 toolbarpath 作為 "org.eclipse.debug.ui.launchActionSet/external",則系統會為工具列上的動作建立新的群組。 如同功能表一般,工具列群組是以分隔符號來描述。 

使用來自另一個外掛程式的路徑

一般說來,藉由從 plugin.xml 衍生路徑名稱,來促成另一個外掛程式的功能表或工具列, 並不是一個好的做法,除非它已特別標示為可供用戶端使用。未來的外掛程式版本有可能可以變更路徑的名稱。兩個常用來將您的外掛程式動作集 ID 及路徑標示為目標的方法如下:

Copyright IBM Corporation and others 2000, 2003.