功能表

org.eclipse.ui.menus

3.2

這個延伸點可讓外掛程式開發人員定義功能表、分隔線、邏輯群組及功能表項目 -- 在應用程式內到處出現,從狀態行到快速功能表,無所不包。也可定義構成要素集(亦即動作集);一般使用者可啟用或停用這些動作集。簡言之,功能表延伸點包含所有呈現元素(圖示除外),可提供給 Eclipse 中的任何功能表或修剪區。

這個延伸點內的每一個元素都有一個唯一 ID。因此,在別處也可參照這些元素,不必重新宣告元素。例如,可能需要 ID 來排序或定義動作集。另外,協力廠商外掛程式開發人員也可將這些元素適當地放入介面內的新位置上。

附註:如果是 3.2,這個延伸規格唯一已實作的組件,是關聯於 'trim' 構成要素的組件。 試圖新增項目、功能表、工具列或狀態列項目,都會扮演 NO-OP 的角色。

<!ELEMENT extension (item* , menu* , group* , widget*)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT item (parameter* , location* , visibleWhen?)>

<!ATTLIST item

id        CDATA #REQUIRED

commandId CDATA #REQUIRED

menuId    CDATA #IMPLIED>

項目可能是功能表項目或修剪項目,視所在位置而定。指令中將繪製項目相關的文字和影像。



<!ELEMENT menu (location* , visibleWhen?)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #IMPLIED>

功能表可附加至工具項目,或出現在檢視功能表、快速功能表或最上層功能表列的某處。為了不受約束,外掛程式開發人員可以假設每一個視圖都有功能表和工具列,且最上層功能表列也存在。快速功能表必須在程式中登錄才能使用(請參閱 API 資訊)。

功能表只能包含群組。



<!ELEMENT group (location*)>

<!ATTLIST group

id                CDATA #REQUIRED

separatorsVisible (true | false) "true">

邏輯群組。可能可見(例如,適當地在前面和後面繪出分隔線)或隱藏。依預設會顯示邏輯群組。

群組可以包含功能表、項目及其他群組。



<!ELEMENT widget (location* , class? , visibleWhen? , layout?)>

<!ATTLIST widget

id    CDATA #REQUIRED

class CDATA #REQUIRED>

可直接存取小組件的功能表或修剪元素。 例如,可用來呈現組合框。很不幸,這表示如果 widget 元素出現在使用者介面中,將導致載入外掛程式。請小心使用這個元素,因為可能造成效能問題。也可能對其他方面造成問題,例如巨集支援、Scripting 及其他許多指令機制。當小組件用來作為修剪時,只有當它在使用者介面中成為可見時,才會使外掛程式載入。



<!ELEMENT layout EMPTY>

<!ATTLIST layout

fillMajor (true | false)

fillMinor (true | false) >

對於新增至 trim 位置的元素,這個元素可用來指定各種版面選項。



<!ELEMENT location (order? , (bar | part | popup))>

<!ATTLIST location

mnemonic   CDATA #IMPLIED

imageStyle CDATA #IMPLIED>

可顯示 menugroupitemwidget 的位置。這個元素用來控制詳細的位置資訊。



<!ELEMENT bar EMPTY>

<!ATTLIST bar

type (menu|trim)

path CDATA #IMPLIED>

一個位置內的葉節點元素。可能是功能表列或修剪區。如果未限定,則表示最上層功能表列或修剪區。如果以 part 元素來限定,則表示該組件的功能表或修剪區。



<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED>

class 元素,支援 widgetdynamic 元素的執行檔延伸規格剖析語法。



<!ELEMENT visibleWhen (not | or | and | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>

<!ATTLIST visibleWhen

checkEnabled (true | false) "false">

控制給定元素的可見性。



<!ELEMENT part (popup | bar)>

<!ATTLIST part

id    CDATA #IMPLIED

class CDATA #IMPLIED>

一個位置內的一個元素。限定用來參照特定工作台組件的位置。可能是視圖或編輯器。資格限定可使用組件的類別名稱(包括繼承),或參照視圖或編輯器的 ID。

只能指定 idclass 其中一個。



<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

執行檔延伸規格或指令的參數 -- 取決於在延伸規格內出現在何處而定。



<!ELEMENT order EMPTY>

<!ATTLIST order

position   (start|end|before|after)

relativeTo CDATA #IMPLIED>

在特定位置內控制功能表、群組、項目或小組件的位置。



<!ELEMENT popup EMPTY>

<!ATTLIST popup

id   CDATA #IMPLIED

path CDATA #IMPLIED>

位置的一部分。表示在蹦現功能表中顯示功能表、群組、項目或小組件。



<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

一般的根元素。這個元素可用於延伸點內定義其 enablement 表示式。 enablement 表示式的子項是使用 and 運算子來組合。



<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>

這個元素代表對其子元素表示式的求值結果執行的 NOT 運算。



<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

這個元素代表對其所有子元素表示式的求值結果執行的 AND 運算。



<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

這個元素代表對其所有子元素表示式的求值結果執行的 OR 運算。



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED>

這個元素是用來執行焦點物件的 instanceof 檢查。如果物件類型是屬性值指定的類型的子類型, 則這個表示式傳回 EvaluationResult.TRUE。 否則傳回 EvaluationResult.FALSE。



<!ELEMENT test EMPTY>

<!ATTLIST test

property CDATA #REQUIRED

args     CDATA #IMPLIED

value    CDATA #IMPLIED>

這個元素是用來評估焦點物件的內容狀態。testable 內容集可使用內容測試程式延伸點加以延伸。如果尚未載入要執行實際測試的內容測試程式, 則 test 表示式傳回 EvaluationResult.NOT_LOADED。



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED>

呼叫 System.getProperty 方法來測試系統內容,並比較其結果與透過 value 屬性指定的值。



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

這個元素是用來執行焦點物件的相等檢查。如果物件等於屬性值提供的值, 則表示式傳回 EvaluationResult.TRUE。否則傳回 EvaluationResult.FALSE。



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED>

這個元素是用來測試集合中的元素數目。



<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST with

variable CDATA #REQUIRED>

這個元素將要視察其所有子元素的物件變更為給定的變數所參照的物件。 如果無法解析變數,則表示式在求值時會擲出 ExpressionException。with 表示式的子項是使用 and 運算子來組合。



<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST resolve

variable CDATA #REQUIRED

args     CDATA #IMPLIED>

這個元素將要視察其所有子元素的物件變更為給定的變數所參照的物件。 如果無法解析變數,則表示式在求值時會擲出 ExpressionException。with 表示式的子項是使用 and 運算子來組合。



<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST adapt

type CDATA #REQUIRED>

這個元素是用來調整焦點物件,使它成為屬性類型指定的類型。 如果配接器或參照的類型尚未載入,則表示式傳回未載入。 如果類型名稱根本不存在,它會在評估期間擲出 ExpressionException。adapt 表示式的子項是使用 and 運算子來組合。



<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST iterate

operator (or|and) >

這個元素是用於 java.util.Collection 類型變數的疊代。如果焦點物件不是 java.util.Collection 類型, 則在評估表示式時,將擲出 ExpressionException。



基本的功能表定義如下。

<menu id=

"com.mycompany.myplugin.projection"

label=

"%Folding.label"

>

<location mnemonic=

"%Folding.label.mnemonic"

>

<part id=

"AntEditor"

>

<popup id=

"#RulerContext"

path=

"rest"

/>

</part>

</location>

</menu>

在此範例中,外掛程式開發人員提供給繼承或實作給定類型的組件。例如,可將一些構成要素新增至所有文字編輯器。

<menu id=

"com.mycompany.myplugin.textEditorMenu"

label=

"Text Commands"

>

<location mnemonic=

"X"

>

<part class=

"AbstractTextEditor"

>

<popup id=

"#RulerContext"

path=

"rest"

/>

</part>

</location>

</menu>

說明和功能表可以建立關聯性。

<menu id=

"com.mycompany.myplugin.RunWithConfigurationAction"

label=

"Run With Configuration"

helpContextId=

"run_with_configuration_context"

>

<location>

<bar />

</location>

</menu>

功能表內可以定義邏輯群組。這些邏輯群組可能可見(例如,適當地在前面和後面繪出分隔線)或隱藏。依預設會顯示邏輯群組。

<group id=

"com.mycompany.myplugin.stepGroup"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</group>

<group id=

"com.mycompany.myplugin.stepIntoGroup"

separatorsVisible=

"false"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</group>

功能表、群組、項目及小組件可放在多個位置上。

<item id=

"com.mycompany.myplugin.ToggleStepFilters"

commandId=

"com.mycompany.myplugin.ToggleStepFilters"

>

<location mnemonic=

"%mnemonic"

>

<bar path=

"org.eclipse.ui.run/emptyStepGroup"

/>

</location>

<location>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<bar type=

"trim"

path=

"renderGroup"

/>

</part>

</location>

<location mnemonic=

"%mnemonic"

>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<popup path=

"renderGroup"

/>

</part>

</location>

</item>

如果指定的 popup 元素沒有 id 和母項 part 元素,則適用於已向工作台登錄的任何快速功能表。這很類似舊物件構成要素的行為。同樣地,具有 id 的最上層 popup 元素將影響以給定名稱來登錄的任何快速功能表。

<item id=

"com.mycompany.myplugin.ObjectContribution"

commandId=

"com.mycompany.myplugin.ObjectContribution"

>

<location>

<popup path=

"additions"

/>

</location>

</item>

您有時可能想要控制項目的可見性。通常,功能表和工具列的版面最好保持穩定,但有時適合隱藏沒有直接關係的項目。在快速功能表中更是如此,因為空間有限。在此情況下,您可以定義 visibleWhen 元素。這個元素幾乎等同於處理常式延伸點中定義的 activeWhenenabledWhen 元素。

<item id=

"com.mycompany.myplugin.ConvertToWatchExpression"

commandId=

"com.mycompany.myplugin.ConvertToWatchExpression"

>

<location mnemonic=

"%mnemonic"

>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<popup path=

"additions"

/>

</part>

</location>

<visibleWhen>

<with variable=

"selection"

>

<iterate operator=

"and"

>

<not>

<instanceof value=

"IWatchExpression"

/>

</not>

<instanceof value=

"IExpression"

/>

</iterate>

</with>

</visibleWhen>

</item>

最常見的情況是直接在啟用處理常式時顯示一些項目。這是透過一些簡化語法來處理。visibleWhen 元素上有一個 checkEnabled 屬性。

<item id=

"com.mycompany.myplugin.compareWithPatch"

commandId=

"com.mycompany.myplugin.compareWithPatch"

>

<location mnemonic=

"%mnemonic"

>

<part id=

"MyPart"

>

<popup path=

"additions"

/>

</part>

</location>

<visibleWhen checkEnabled=

"true"

/>

</item>

指令相關的任何項目都可以包含參數值。如果給定 ID 的參數未定義,則視為錯誤。如果項目沒有指令,也一樣錯誤。

<item id=

"com.mycompany.myplugin.RunHistory"

commandId=

"com.mycompany.myplugin.RunHistory"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

<parameter name=

"index"

value=

"1"

/>

</item>

也可以指定相對排序。需要以 location 元素上的 order 屬性來完成。order 屬性接受下列值:start(將元素放在儲存檔案開頭);end(將元素放在儲存檔案尾端);after(將元素放在 id 符合 ref 的同屬元素之後);before(將元素放在 id 符合 ref 的同屬元素之前)。相對排序適用於任何類型的功能表元素。

<item id=

"com.mycompany.myplugin.MyFirstItem"

commandId=

"com.mycompany.myplugin.MyFirstCommand"

>

<location>

<order position=

"start"

/>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</item>

<item id=

"com.mycompany.myplugin.MySecondItem"

commandId=

"com.mycompany.myplugin.MySecondCommand"

>

<location>

<order position=

"after"

relativeTo=

"com.mycompany.myplugin.MyFirstItem"

/>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</item>

如果需要直接存取小組件(例如,為了呈現組合框),您可以使用 widget 元素。很不幸,這表示如果 widget 元素出現在使用者介面中,將導致載入外掛程式。

<widget id=

"com.mycompany.myplugin.MyComboBoxSimple"

class=

"com.mycompany.myplugin.MyComboBox"

>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

<widget id=

"com.mycompany.myplugin.MyComboBoxParameterized1"

class=

"com.mycompany.myplugin.MyComboBox:a,b,c"

>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

<widget id=

"com.mycompany.myplugin.MyComboBoxParameterized2"

>

<class class=

"com.mycompany.myplugin.MyComboBox"

>

<parameter name=

"list"

value=

"a,b,c"

/>

<parameter name=

"selected"

value=

"c"

/>

<parameter name=

"editable"

value=

"false"

/>

</class>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

您也可以利用小組件在工作台修剪區內提供。下列範例定義新的 'HeapStatus' 小組件,依預設應該放在狀態行修剪區後面(亦即,工作台視窗的底部)。如需預先定義的群組的相關資訊,請參閱 'bar' 元素的說明。

請注意,修剪 'groups' 可重新放到其他修剪區。在決定新修剪區的位置時,位置資訊的 relativeTo 會假設參照的群組在預設位置中。這個類型的貢獻者通常會建立自己的群組來存放新的小組件,以利於重新定位修剪元素,而不必顧慮其他修剪元素。一個明顯的例外是 'status' 群組。

   

<extension point=

"org.eclipse.ui.menus"

>

<group id=

"TestTrimAPI.heapStatusGroup"

separatorsVisible=

"true"

>

<location>

<bar type=

"trim"

/>

<order position=

"after"

relativeTo=

"status"

/>

</location>

</group>

<widget class=

"HeapStatusWidget"

id=

"TestTrimAPI.HeapStatus"

>

<location>

<bar path=

"heapStatusGroup"

type=

"trim"

/>

</location>

<layout fillMajor=

"false"

fillMinor=

"true"

/>

</widget>

</extension>

若要登錄快速功能表,請使用 IWorkbenchPartSite.registerContextMenu 方法。