編輯器功能表、工具列和動作

org.eclipse.ui.editorActions

這個延伸點是用來將動作新增至其他外掛程式所登錄編輯器的功能表和工具列中。

編輯器的起始構成要素集由另一個延伸點 (org.eclipse.ui.editors) 來定義。 相同編輯器類型的所有實例會建立及共用一個動作集。當呼叫這些動作時, 這些動作會作用於作用中的編輯器。這個延伸點遵循相同的型樣。 每個動作延伸都是由相同編輯器類型的所有實例來建立和共用。需要這個動作類別,才能實作 org.eclipse.ui.IEditorActionDelegate。 作用中的編輯器是藉由呼叫 IEditorActionDelegate.setActiveEditor 來傳遞給委派項目。

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

enablement 元素和 visibility 元素的語法是相同的。這兩者僅含有一個 boolean 表示式子元素。在最簡單的情況下, 這將是 objectClassobjectStatepluginStatesystemProperty 元素。在其他較複雜的情況下,andornot 元素可以結合以構成 boolean 表示式。andor 元素兩者必須含有 2 個子元素。not 元素必須僅含有 1 個子元素。

<!ELEMENT extension (editorContribution+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT editorContribution (menu* , action*)>

<!ATTLIST editorContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

這個元素是用來定義編輯器動作及/或功能表的群組。



<!ELEMENT action (selection* | enablement?)>

<!ATTLIST action

id            CDATA #REQUIRED

label         CDATA #REQUIRED

accelerator   CDATA #IMPLIED

definitionId  CDATA #IMPLIED

menubarPath   CDATA #IMPLIED

toolbarPath   CDATA #IMPLIED

icon          CDATA #IMPLIED

disabledIcon  CDATA #IMPLIED

hoverIcon     CDATA #IMPLIED

tooltip       CDATA #IMPLIED

helpContextId CDATA #IMPLIED

style         (push|radio|toggle) "push"

state         (true | false)

class         CDATA #REQUIRED

enablesFor    CDATA #IMPLIED

actionID      CDATA #IMPLIED>

這個元素定義使用者可在 UI 中呼叫的動作。



<!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.editorActions"

>

<editorContribution id=

"com.xyz.xyzContribution"

targetID=

"com.ibm.XMLEditor"

>

<menu id=

"XYZ"

label=

"&amp;XYZ Menu"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Run XYZ Tool"

menubarPath=

"XYZ/group1"

toolbarPath=

"Normal/additions"

style=

"toggle"

state=

"true"

icon=

"icons/runXYZ.gif"

tooltip=

"Run XYZ Tool"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.RunXYZ"

>

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

/>

</action>

</editorContribution>

</extension>

在上述範例中,指定的動作會成為最上層新功能表(XYZ 功能表)中的勾選框項目及工具列中的切換按鈕。 當選擇僅含有 Java 檔案資源時,就會啟用這個動作。

以下是編輯器動作延伸的其他範例:

   

<extension point=

"org.eclipse.ui.editorActions"

>

<editorContribution id=

"com.xyz.xyz2Contribution"

targetID=

"com.ibm.XMLEditor"

>

<menu id=

"XYZ2"

label=

"&amp;XYZ2 Menu"

path=

"edit/additions"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ2"

label=

"&amp;Run XYZ2 Tool"

menubarPath=

"edit/XYZ2/group1"

style=

"push"

icon=

"icons/runXYZ2.gif"

tooltip=

"Run XYZ2 Tool"

helpContextId=

"com.xyz.run_action_context2"

class=

"com.xyz.actions.RunXYZ2"

>

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<not>

<objectState name=

"extension"

value=

"java"

/>

</not>

</and>

</enablement>

</action>

</editorContribution>

</extension>

在上述範例中,指定的動作將在最上層「編輯」功能表中,顯示為子功能表(XYZ2 功能表)中的功能表項目。 當選擇沒有 Java 檔案資源時,就會啟用這個動作。

class 屬性值必須是實作 org.eclipse.ui.IEditorActionDelegate的完整 Java 類別名稱。 這個類別的載入要儘可能晚,以避免在真正需要它之前載入整個外掛程式。 每次啟動指定類型的編輯器時,都會呼叫 setActiveEditor 方法。指定編輯器類型的所有實例只會建立一組動作和功能表,不論「工作區」目前開啟的編輯器實例的數目有多少都是如此。

這個延伸點可用來提供動作到目標編輯器先前所建立的功能表中。此外,可以提供功能表和動作給「工作台」視窗。 「工作台」視窗內的動作和主要群組的 ID 定義在 org.eclipse.ui.IWorkbenchActionConstants。 這些應該作為新增動作的參照點。最上層功能表是利用下列 path 屬性值來建立的:

如果略過 path 屬性,結果會將新功能表新增至其他功能表列群組中。

新增至這些路徑的動作和功能表只有在相關編輯器在作用中時才會顯示。 當關閉編輯器時,會移除功能表和動作。

動作延伸的啟用準則起初是由 enablesFor, 而且也由 selectionenablement 定義。不過,在建立好動作委派的實例之後, 它可以在它的 selectionChanged 方法內直接控制動作啟用狀態。

動作和功能表標籤可含有利用下列規則來編碼助記鍵的特殊字元:

  1. 助記符號則是利用已翻譯文字中所選取的字元前面加上 '&' 字元來指定的。由於 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>

工作台提供一個內建的「預設文字編輯器」。外掛程式可以提供到這個預設編輯器或其他外掛程式所提供的編輯器中。