當選項是異質的,可能的話,如果構成要素是就共用選項類型而登錄的,就會套用這個構成要素。如果沒有直接相符項目,就會嘗試就 Super 類別和 super 介面來找到相符項目。
您可以利用名稱過濾器來進一步限制選項。 如果使用的話,選項中的所有物件都必須符合過濾器,才能套用構成要素。
物件構成要素中的個別動作可以利用 enablesFor
屬性,來指定它是適用於單一、多個或任何其他選項類型。
如果這些過濾機制都不適當,動作構成要素可使用過濾機制。在這個情況下,會以一系列的名稱/值配對來說明目標物件的屬性。 適用於選項的屬性會隨著類型而不同,且會越過工作台本身的領域,因此, 工作台會將這個層次的過濾委派給實際的選項。
您可以分別使用 enablement 和 visibility 元素, 來定義動作的啟用狀態及/或可見性狀態。這兩個元素含有一個 boolean 表示式, 將被計算以決定啟用及/或可見性的狀態。
enablement 元素和 visibility 元素的語法是相同的。這兩者僅含有一個 boolean 表示式子元素。在最簡單的情況下, 這將是 objectClass、objectState、pluginState 或 systemProperty 元素。在其他較複雜的情況下,and、or 及 not 元素可以結合以構成 boolean 表示式。and 和 or 元素兩者必須含有 2 個子元素。not 元素必須僅含有 1 個子元素。
<!ELEMENT extension (objectContribution , viewerContribution)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT objectContribution (filter* , visibility? , enablement? , menu* , action*)>
<!ATTLIST objectContribution
id CDATA #REQUIRED
objectClass CDATA #REQUIRED
nameFilter CDATA #IMPLIED
adaptable (true | false) "false">
這個元素是用來為任何檢視器快速功能表(將為它們選取指定類型的物件)定義動作及/或功能表的群組。
<!ELEMENT viewerContribution (visibility? , menu* , action*)>
<!ATTLIST viewerContribution
id CDATA #REQUIRED
targetID CDATA #REQUIRED>
這個元素是用來為特定視圖或編輯器組件快速功能表定義動作及/或功能表的群組。
<!ELEMENT action (selection* , enablement?)>
<!ATTLIST action
id CDATA #REQUIRED
label CDATA #REQUIRED
definitionId CDATA #IMPLIED
menubarPath CDATA #IMPLIED
icon CDATA #IMPLIED
helpContextId CDATA #IMPLIED
style (push|radio|toggle|pulldown)
state (true | false)
class CDATA #REQUIRED
enablesFor CDATA #IMPLIED
overrideActionId CDATA #IMPLIED
tooltip CDATA #IMPLIED>
這個元素定義使用者可在 UI 中呼叫的動作。
push | - 作為一般功能表項目或工具項目。 | |
radio | - 作為圓鈕樣式功能表項目或工具項目。在同一功能表或工具列群組內具有圓鈕樣式的動作將當作圓鈕集來操作。起始值是由 state 屬性指定。 | |
toggle | - 作為已勾選的樣式功能表項目或作為切換工具項目。起始值是由 state 屬性指定。 | |
pulldown | - 作為階式排列樣式功能表項目。 |
! | - 選取 0 個項目 | |
? | - 選取 0 或 1 個項目 | |
+ | - 選取 1 或多個項目 | |
multiple, 2+ | - 選取 2 或更多個項目 | |
n | - 選取精確數目的項目。 例如:enablesFor=" 4" 僅在選取了 4 個項目時,才啟用動作 | |
* | - 選取任意數目的項目 |
動作延伸的啟用準則起初是由 enablesFor、selection 和 enablement 定義。然而,在建立好動作委派的實例之後,它可以在它的 selectionChanged 方法內直接控制動作啟用狀態。
<!ELEMENT filter EMPTY>
<!ATTLIST filter
name CDATA #REQUIRED
value CDATA #REQUIRED>
這個元素是用來計算現行選擇中每個物件的屬性狀態。僅在選項中的每一個物件都具有指定的屬性狀態時,才會進行比對。在選項中的每一個物件都必須實作或適合於 org.eclipse.ui.IActionFilter。
<!ELEMENT menu (separator+ , groupMarker*)>
<!ATTLIST menu
id CDATA #REQUIRED
label CDATA #REQUIRED
path CDATA #IMPLIED>
這個元素是用來定義新的功能表。
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name CDATA #REQUIRED>
這個元素是用來在新功能表中建立功能表分隔字元。
<!ELEMENT groupMarker EMPTY>
<!ATTLIST groupMarker
name CDATA #REQUIRED>
這個元素是用來在新功能表中建立具名群組。不同於 separator 元素, 它在新功能表中沒有任何視覺化表示法。
<!ELEMENT selection EMPTY>
<!ATTLIST selection
class CDATA #REQUIRED
name CDATA #IMPLIED>
這個元素是用來協助根據現行選擇,來判定動作的啟用狀態。如果指定了 enablement 元素,將予以忽略。
<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>
這個元素是用來定義延伸的啟用狀態。
<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>
這個元素是用來定義延伸的可見性狀態。
<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>
這個元素代表 Boolean AND 運算,以算出它的兩個子元素表示式的結果。
<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>
這個元素代表 Boolean OR 運算,以算出它的兩個子元素表示式的結果。
<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>
這個元素代表 Boolean NOT 運算,以算出它的子元素表示式的結果。
<!ELEMENT objectClass EMPTY>
<!ATTLIST objectClass
name CDATA #REQUIRED>
這個元素是用來計算現行選擇中每個物件的類別或介面。如果選擇中的每個物件都實作指定的類別或介面,則表示式將計算為 true。
<!ELEMENT objectState EMPTY>
<!ATTLIST objectState
name CDATA #REQUIRED
value CDATA #REQUIRED>
這個元素是用來計算現行選擇中每個物件的屬性狀態。如果選擇中的每個物件都具有指定的屬性狀態,則表示式將計算為 true。如果要計算這種類型的表示式,則選擇中的每個物件都必須實作或適合於 org.eclipse.ui.IActionFilter 介面。
<!ELEMENT pluginState EMPTY>
<!ATTLIST pluginState
id CDATA #REQUIRED
value (installed|activated) "installed">
這個元素是用來計算外掛程式的狀態。外掛程式的狀態可以是下列之一:installed(相等於 "resolved" 的 OSGi 概念)或 activated(相等於 "active" 的 OSGi 概念)。
<!ELEMENT systemProperty EMPTY>
<!ATTLIST systemProperty
name CDATA #REQUIRED
value CDATA #REQUIRED>
這個元素是用來計算某個系統內容的狀態。內容值擷取自 java.lang.System。
在上述範例中,只有單一選項(enablesFor 屬性)能夠啟用指定的物件構成要素動作。另外,選項中的每個物件都必須實作指定的介面 (IFile),且必須是 Java 檔。這個動作會新增至先前建立的子功能表中。 在有必要選項的任何視圖中,這個構成要素都有效。<extension point=
"org.eclipse.ui.popupMenus"
>
<objectContribution id=
"com.xyz.C1"
objectClass=
"org.eclipse.core.resources.IFile"
nameFilter=
"*.java"
>
<menu id=
"com.xyz.xyzMenu"
path=
"additions"
label=
"&XYZ Java Tools"
>
<separator name=
"group1"
/>
</menu>
<action id=
"com.xyz.runXYZ"
label=
"&Run XYZ Tool"
style=
"push"
menubarPath=
"com.xyz.xyzMenu/group1"
icon=
"icons/runXYZ.gif"
helpContextId=
"com.xyz.run_action_context"
class=
"com.xyz.actions.XYZToolActionDelegate"
enablesFor=
"1"
/>
</objectContribution>
<viewerContribution id=
"com.xyz.C2"
targetID=
"org.eclipse.ui.views.TaskList"
>
<action id=
"com.xyz.showXYZ"
label=
"&Show XYZ"
style=
"toggle"
state=
"true"
menubarPath=
"additions"
icon=
"icons/showXYZ.gif"
helpContextId=
"com.xyz.show_action_context"
class=
"com.xyz.actions.XYZShowActionDelegate"
/>
</viewerContribution>
</extension>
相反地,上述檢視器構成要素快速功能表只會出現在「作業」視圖快速功能表中,不會受到視圖中之選項的影響。
下列是過濾機制的範例。在這種情況下,只會出現已完成且有高優先順序的 IMarkers 的動作。
下列是其他使用 visibility 元素的範例:<extension point=
"org.eclipse.ui.popupMenus"
>
<objectContribution id=
"com.xyz.C3"
objectClass=
"org.eclipse.core.resources.IMarker"
>
<filter name=
"done"
value=
"true"
/>
<filter name=
"priority"
value=
"2"
/>
<action id=
"com.xyz.runXYZ"
label=
"High Priority Completed Action Tool"
icon=
"icons/runXYZ.gif"
class=
"com.xyz.actions.MarkerActionDelegate"
>
</action>
</objectContribution>
</extension>
<extension point=
"org.eclipse.ui.popupMenus"
>
<viewerContribution id=
"com.xyz.C4"
targetID=
"org.eclipse.ui.views.TaskList"
>
<visibility>
<and>
<pluginState id=
"com.xyz"
value=
"activated"
/>
<systemProperty name=
"ADVANCED_MODE"
value=
"true"
/>
</and>
</visibility>
<action id=
"com.xyz.showXYZ"
label=
"&Show XYZ"
style=
"push"
menubarPath=
"additions"
icon=
"icons/showXYZ.gif"
helpContextId=
"com.xyz.show_action_context"
class=
"com.xyz.actions.XYZShowActionDelegate"
>
</action>
</viewerContribution>
</extension>
在上述範例中,指定的動作將以功能表項目出現在「作業」視圖快速功能表中,但前提必須是 "com.xyz" 外掛程式作用中,且指定的系統內容設為 true。
附註:如果需要舊版相容性,可以對物件構成要素實作 org.eclipse.ui.IActionDelegate。
僅在目標組件公佈了進行延伸的功能表時,才可能在組件內延伸快速功能表。 強烈鼓勵這樣做,因為它會增進產品的延伸性。 如果要達成這樣的結果,每一個組件都應該呼叫 IWorkbenchPartSite.registerContextMenu, 來公佈任何定義的快速功能表。 一旦完成,工作台將自動插入任何存在的動作延伸。
您必須提供每個已登錄功能表的功能表 ID。 為了要有跨越各組件的一致性,所有組件的實作者都應採用下列策略。
任何以工作台登錄的快速功能表也應該含有 ID 為 IWorkbenchActionConstants.MB_ADDITIONS 的標準插入點。 其他外掛程式將使用此值作為插入的參考點。 定義插入點的做法為在適當的插入位置,將 GroupMarker 新增至功能表。
工作台中作為快速功能表之選項的物件可定義 org.eclipse.ui.IActionFilter。這是可以執行類型特有之過濾的過濾策略。 工作台將擷取選項的過濾器,方法為進行測試以查看它是否實作 IActionFilter。如果失敗,工作台將透過 IAdaptable 機制要求一個過濾器。
動作和功能表標籤可能包含特定的字元編碼助記符號,助記符號是利用已翻換文字中所選取的字元前面加上 '&' 字元來指定的。 由於 XML 字串中不能使用&符號,請使用 & 字元實體。
如果透過單一延伸提供兩個或以上的動作給功能表, 這些動作將按照它們列出在 plugin.xml 檔的相反順序出現。這種行為是一般公認的非直覺行為。然而, 在「Eclipse 平台 API」凍結後,已探索過它。現在變更行為將中斷每一個依賴現存之行為的外掛程式。
selection 和 enablement 元素互斥。enablement 元素可以使用 objectClass 和 objectState 子元素, 來取代 selection 元素。例如,下列:
可以表示成:<selection class=
"org.eclipse.core.resources.IFile"
name=
"*.java"
>
</selection>
<enablement>
<and>
<objectClass name=
"org.eclipse.core.resources.IFile"
/>
<objectState name=
"extension"
value=
"java"
/>
</and>
</enablement>
Copyright (c) 2000, 2005 IBM Corporation and others.
All rights reserved.
本程式與隨附的資料依照 Elipse Public License 1.0 版此次發行所隨附的條款而提供,
可以在以下網址取得:http://www.eclipse.org/legal/epl-v10.html