蹦現功能表

org.eclipse.ui.popupMenus

這個延伸點用來將動作新增至其他外掛程式所擁有的快速功能表中。動作的構成要素可以就某特定物件類型 (objectContribution) 或就視圖或編輯器組件 (viewerContribution) 的特定快速功能表來進行。使用 objectContribution 時, 構成要素將出現在所有視圖或編輯器組件快速功能表(選取指定類型之物件的所在)中。相反地,若使用 viewerContribution,則不管選擇為何, 構成要素僅會出現在指定的視圖或編輯器組件快速功能表中。

當選項是異質的,可能的話,如果構成要素是就共用選項類型而登錄的,就會套用這個構成要素。如果沒有直接相符項目,就會嘗試就 Super 類別和 super 介面來找到相符項目。

您可以利用名稱過濾器來進一步限制選項。 如果使用的話,選項中的所有物件都必須符合過濾器,才能套用構成要素。

物件構成要素中的個別動作可以利用 enablesFor 屬性,來指定它是適用於單一、多個或任何其他選項類型。

如果這些過濾機制都不適當,動作構成要素可使用過濾機制。在這個情況下,會以一系列的名稱/值配對來說明目標物件的屬性。 適用於選項的屬性會隨著類型而不同,且會越過工作台本身的領域,因此, 工作台會將這個層次的過濾委派給實際的選項。

您可以分別使用 enablementvisibility 元素, 來定義動作的啟用狀態及/或可見性狀態。這兩個元素含有一個 boolean 表示式, 將被計算以決定啟用及/或可見性的狀態。

enablement 元素和 visibility 元素的語法是相同的。這兩者僅含有一個 boolean 表示式子元素。在最簡單的情況下, 這將是 objectClassobjectStatepluginStatesystemProperty 元素。在其他較複雜的情況下,andornot 元素可以結合以構成 boolean 表示式。andor 元素兩者必須含有 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 中呼叫的動作。



<!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



下列是蹦現功能表延伸點的範例:

   

<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=

"&amp;XYZ Java Tools"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;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=

"&amp;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>

在上述範例中,只有單一選項(enablesFor 屬性)能夠啟用指定的物件構成要素動作。另外,選項中的每個物件都必須實作指定的介面 (IFile),且必須是 Java 檔。這個動作會新增至先前建立的子功能表中。 在有必要選項的任何視圖中,這個構成要素都有效。

相反地,上述檢視器構成要素快速功能表只會出現在「作業」視圖快速功能表中,不會受到視圖中之選項的影響。

下列是過濾機制的範例。在這種情況下,只會出現已完成且有高優先順序的 IMarkers 的動作。

   

<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>

下列是其他使用 visibility 元素的範例:

   

<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=

"&amp;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。

action 屬性 class 的值必須是實作 org.eclipse.ui.IObjectActionDelegate(如果是物件構成要素)、org.eclipse.ui.IViewActionDelegate(如果是屬於視圖之快速功能表的構成要素)或 org.eclipse.ui.IEditorActionDelegate(如果是屬於編輯器之快速功能表的構成要素)之 Java 類別的完整類別名稱。在所有情況下,這個實作類別的載入要儘可能晚一些,以避免在真正需要它之前載入整個外掛程式。

附註:如果需要舊版相容性,可以對物件構成要素實作 org.eclipse.ui.IActionDelegate

僅在目標組件公佈了進行延伸的功能表時,才可能在組件內延伸快速功能表。 強烈鼓勵這樣做,因為它會增進產品的延伸性。 如果要達成這樣的結果,每一個組件都應該呼叫 IWorkbenchPartSite.registerContextMenu, 來公佈任何定義的快速功能表。 一旦完成,工作台將自動插入任何存在的動作延伸。

您必須提供每個已登錄功能表的功能表 ID。 為了要有跨越各組件的一致性,所有組件的實作者都應採用下列策略。

任何以工作台登錄的快速功能表也應該含有 ID 為 IWorkbenchActionConstants.MB_ADDITIONS 的標準插入點。 其他外掛程式將使用此值作為插入的參考點。 定義插入點的做法為在適當的插入位置,將 GroupMarker 新增至功能表。

工作台中作為快速功能表之選項的物件可定義 org.eclipse.ui.IActionFilter。這是可以執行類型特有之過濾的過濾策略。 工作台將擷取選項的過濾器,方法為進行測試以查看它是否實作 IActionFilter。如果失敗,工作台將透過 IAdaptable 機制要求一個過濾器。

動作和功能表標籤可能包含特定的字元編碼助記符號,助記符號是利用已翻換文字中所選取的字元前面加上 '&' 字元來指定的。 由於 XML 字串中不能使用&符號,請使用 &amp; 字元實體。

如果透過單一延伸提供兩個或以上的動作給功能表, 這些動作將按照它們列出在 plugin.xml 檔的相反順序出現。這種行為是一般公認的非直覺行為。然而, 在「Eclipse 平台 API」凍結後,已探索過它。現在變更行為將中斷每一個依賴現存之行為的外掛程式。

selectionenablement 元素互斥。enablement 元素可以使用 objectClassobjectState 子元素, 來取代 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>

工作台視圖已內建若干隨動作一起載入的快速功能表。 外掛程式可以提供到這些功能表中。 如果檢視器已保留若干槽給這些構成要素,且它們已設為公開,就可以將槽的名稱當作路徑來使用。 否則,動作和子功能表會新增至蹦現功能表的尾端。