說明:這個延伸點是用來將新動作新增到其他外掛程式所擁有的蹦現功能表中。動作的構成要素可以就某特定物件類型(objectContribution)或特定蹦現功能表來進行。 就物件類型來登錄時,構成要素會出現在選取了指定類型之物件的所有檢視器中。 相反地,就蹦現功能表而登錄時,不論選項為何,都只會出現在指定的功能表中。
當選項是異質的,可能的話,如果構成要素是就共用選項類型而登錄的,就會套用這個構成要素。 如果沒有直接相符項目,就會嘗試就超類別和超介面來找到相符項目。
您可以利用名稱過濾條件來進一步限制選項。 如果使用的話,選項中的所有物件都必須符合過濾條件,才能套用構成要素。
物件構成要素中的個別動作可以利用 enablesFor 屬性來指定它是適用於單一、多個或任何其他選項類型。
如果這些過濾機制都不適當,動作構成要素可以使用 filter 機制。在這個情況下,會以一系列的鍵值對來說明目標物件的屬性。適用於選項的屬性會隨著類型而不同,且會超過工作台本身的範圍,因此,工作台會將這個層次的過濾委派給實際的選項。
配置標記:
<!ELEMENT objectContribution (filter | menu | action)*
(visibility)?>
<!ATTLIST objectContribution
id
CDATA #REQUIRED
objectClass CDATA #REQUIRED
nameFilter CDATA #IMPLIED
adaptable (true|false)
#IMPLIED
>
在第 2.0 版的 Eclipse 中,visibility 元素可用在 objectContribution 以定義動作的可見性。 這不會取代 objectClass 屬性(定義動作的主要目標)。visibility 元素是用來修正主要目標。如需如何使用 visibility 元素的詳細資訊,請參閱 actionExpressions.html。<!ELEMENT viewerContribution (menu | action)*>
<!ELEMENT action (selection)* (enablement)?>name - 之後可作為動作路徑中最後一個記號來參照的分隔字元名稱。因此,分隔字元可作為動作可新增其中的具名群組。
在第 2.0 版的 Eclipse 中,enablement 元素可用來定義是否要啟用動作。 如需如何使用 enablement 元素的詳細資訊,請參閱 actionExpressions.html。開始時,動作延伸項目的啟用準則是由 enablesFor、 selection 及 enablement 來定義的。不過,在建立好動作委派的實例之後,它會直接在其 selectionChanged 方法中控制動作啟用狀態。
動作和功能表標籤可能包含特定的字元編碼助記符號,助記符號是利用已翻譯文字中所選取的字元前面加上 '&' 字元來指定的。 由於 XML 字串中不能使用&符號,請使用 & 字元實體。
如果透過單一延伸項目提供兩個或以上動作給功能表或工具列, 這些動作將按它們出現在 plugin.xml 檔的相反順序出現。這種行為是一般公認的非直覺行為。然而,在「Eclipse 平台 API」凍結後,已探索過它。現在變更行為將中斷每一個依賴現存之行為的外掛程式。
範例:
下列是一個蹦現功能表延伸點的範例:
<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"
menubarPath="com.xyz.xyzMenu/group1"
icon="icons/runXYZ.gif"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.XYZToolActionDelegate"
enablesFor="1">
</action>
</objectContribution>
<viewerContribution
id="com.xyz.C2"
targetID="org.eclipse.ui.views.TaskList">
<action
id="com.xyz.showXYZ"
label="&Show XYZ"
menubarPath="additions"
icon="icons/showXYZ.gif"
helpContextId="com.xyz.show_action_context"
class="com.xyz.actions.XYZShowActionDelegate">
</action>
</viewerContribution>
</extension>
在上述範例中,只有單一選項能夠啟用指定的動作(enablesFor 屬性)。 另外,選項中的每個物件都必須實作指定的介面 (IFile),且必須是 Java 檔。 這個動作會新增到先前建立的子功能表中。 在有必要選項的任何檢視畫面中,這個構成要素都有效。
相反地,上述檢視器構成要素只會出現在「作業」檢視畫面中,不會受到檢視畫面中之選項的影響。
以下是過濾機制的範例。在這裡,只會出現已完成且有高優先順序的 IMarkers 的動作。
<extension point="org.eclipse.ui.popupMenus">
<objectContribution
id="com.xyz.C1"
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>
API 資訊:action 屬性 class 的值必須是在物件構成要素中實作 org.eclipse.ui.IObjectActionDelegate, 在屬於檢視畫面之檢視器的構成要素中實作 org.eclipse.ui.IViewActionDelegate, 或在屬於編輯器之檢視器的構成要素中實作 org.eclipse.ui.IEditorActionDelegate 的 Java 類別的完整類別名稱。 在所有情況中,負責實作的類別都是儘可能晚一點載入,以避免在真正需要之前載入整個外掛程式。
附註:如果要向後相容,物件構成要素可以實作 org.eclipse.ui.IActionDelegate。
只有當目標部份發佈了延伸項目的功能表,否則,不可能有該部份內的蹦現功能表延伸項目。 強力建議您這麼做,因為它可以增進產品的可延伸性。 如果要做到這一點,每個部份都要發佈藉由呼叫 IWorkbenchPartSite#registerContextMenu 來定義的蹦現功能表。 這個動作完成之後,工作台就會自動插入任何存在的動作延伸項目。
必須提供每個登錄功能表的功能表 ID。為了要有跨越各部份的一致性,所有部份的實作者都應採用下列策略。
工作台中本身是快捷功能表選項的物件可以定義一個 org.eclipse.ui.IActionFilter。這是可執行特定類型 private 過濾作業的過濾策略。 工作台會測試選項的過濾條件是否實作 IActionFilter 來擷取過濾條件。如果失敗的話,工作台會透過 IAdaptable 機制來要求過濾條件。
提供的實作:工作台檢視畫面已內建隨若干動作而載入的蹦現功能表。外掛程式可以提供到這些功能表中。 如果檢視畫面已保留若干槽給這些構成要素,且它們已設為公開,就可以將槽的名稱當作路徑來使用。 否則,動作和子功能表會新增到蹦現功能表的尾端。