動作集
識別碼:org.eclipse.ui.actionSets
說明:這個延伸點是用來新增功能表、功能表項目和工具列按鈕到工作台視窗中的共用區。
這些提供項總稱為動作集,會出現在使用者喜好設定的工作台視窗中。
配置標記:
<!ELEMENT actionSet (menu)* (action)* (description?)>
<!ATTLIST actionSet
id CDATA
#REQUIRED
label CDATA #REQUIRED
visible (true
| false) #IMPLIED
>
<!ELEMENT description (#PCDATA)>
-
id - 用來識別動作集的唯一名稱。
-
label - 在工作台視窗功能表中,用來代表這個動作集的可翻譯的名稱。
-
visible - 指出在開始時是否應該在所有視景中看到動作集。只有在使用者開啟未自訂的視景時,才會提供此選項。使用者可以從「自訂視景對話框」來置換這個選項。
-
description - 主體含有文字來提供動作集之簡短說明的選用子元素。
<!ELEMENT menu (separator)+ (groupMarker)*>
<!ATTLIST menu
id
CDATA #REQUIRED
label
CDATA #REQUIRED
path
CDATA #IMPLIED
>
-
id - 可用來參照這個功能表的唯一識別碼
-
label - 新功能表的文字標籤。
標籤應該包括助記符號資訊。
-
path - 從功能表列起始位置開始的功能表的位置。
如果略過的話,功能表會新增到功能表列中的 Windows 功能表之前。
路徑中的每個記號都必須指向工作台中現有的功能表,但最後一個除外,它應該代表路徑中最後一個功能表中的具名群組。
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name CDATA #REQUIRED
>
name - 之後可作為動作路徑中最後一個記號來參照的分隔字元名稱。因此,分隔字元可作為動作和子功能表可新增其中的具名群組。
<!ELEMENT groupMarker EMPTY>
<!ATTLIST groupMarker
name CDATA #REQUIRED
>
name - 群組標示元的名稱,可在稍後參照為動作路徑中最後的記號。
<!ELEMENT action (selection)* (enablement)?>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
accelerator
CDATA #IMPLIED
definitionId
CDATA #IMPLIED
menubarPath
CDATA #IMPLIED
toolbarPath
CDATA #IMPLIED
icon
CDATA #IMPLIED
disabledIcon
CDATA #OPTIONAL
hoverIcon
CDATA #OPTIONAL
tooltip
CDATA #IMPLIED
helpContextId
CDATA #IMPLIED
state
(true | false) #IMPLIED
pulldown
(true | false) #IMPLIED
class
CDATA #OPTIONAL
retarget
(true | false) #OPTIONAL
allowLabelUpdate
(true | false) #OPTIONAL
enablesFor
CDATA #IMPLIED
>
-
id - 可用來參照這個動作的唯一識別碼。
-
label - 隨環境定義而不同,以各種方式來使用的可翻譯的名稱。在功能表中,它是功能表文字。在工具列中,它是按鈕標籤。標籤可含有 JFace 編碼的助記符號和加速器資訊(請參閱範例)。
-
accelerator - 用來指定動作加速器之 keycode 的整數。
這是由具有零個或多個 SWT 鍵修飾元遮罩(如 SWT.CTRL 或 SWT.ALT)及一個字元碼的按位元 OR 所產生。
比方說,對於 Ctrl+Z,請使用 SWT.CTRL | 'Z' =
(1<<18)|'Z' = 262234。
-
definitionId - 動作定義中指定的 ID。只在動作集中透過索引鍵連結服務程式指定加速器時才需要。
請參閱延伸點動作定義和加速器集。
-
menubarPath - 用來指定動作在功能表列中之位置的斜線定界路徑('/')。除了最後一個,路徑中的每個記號都代表階層中現有功能表的有效 ID。最後一個記號代表動作要新增到其中的具名分隔字元群組。
如果忽略路徑的話,動作不會出現在功能表列中。
-
toolbarPath - 用來指定動作在工具列中之位置的斜線定界路徑('/')。第一個記號代表工具列 ID(以「正常」為預設工具列),第二個記號是工具列內的具名群組。如果群組不在工具列中,就會建立它。如果忽略 toolbarPath 的話,動作不會出現在工具列中。
-
icon - 在其環境定義中,視覺化代表動作之圖示的相對路徑。如果略過它的話,動作應該會出現在工具列中,工作台會使用位置保留元圖示。這個路徑相對於提供外掛程式的 plugin.xml 檔的位置。圖示會出現在工具列而不是功能表。已啟用的動作將在功能表中用 hoverIcon 呈現。
-
disabledIcon - 圖示的相對路徑,在停用動作時,會使用此圖示以在環境定義中以視覺化的方式呈現動作。如果省略
此動作,正常圖示將顯示為灰色。這個路徑相對於提供外掛程式的 plugin.xml 檔的位置。停用的圖示會出現在工具列而不是功能表。OS 提供功能表中停用的動作圖示。
-
hoverIcon - 圖示的相對路徑,當這個滑鼠在動作之上時,會在環境定義中以視覺化的方式呈現該動作。如果省略此動作,將會使用正常圖示。這個路徑相對於提供外掛程式的 plugin.xml 檔的位置。
-
tooltip - 當動作出現在工具列時的工具提示文字值。否則,會予以忽略。
-
helpContextId - 指出這個動作之說明環境定義 ID 的唯一識別碼。如果動作顯示為功能表項目,在強調顯示這個功能表項目時按下 F1,會顯示給定環境定義 ID 的說明。
-
state - 指示動作應該屬於某切換類型的選用屬性。當新增到功能表中,它會將自己當作一個勾選框項目來處理。當新增到工具列時,它會成為雙向按鈕。如果定義的話,會利用屬性值來作為起始狀態(true 或 false)。這個屬性與 pulldown 互斥。
-
pulldown - 指出動作有其他下拉功能表的選用屬性。如果動作出現在工具列中,且屬性值為 true,動作旁就會出現下拉功能表。如果動作出現在功能表中,就會忽略這個屬性。這個屬性與 state 互斥。
-
class - 實作 org.eclipse.ui.IWorkbenchWindowActionDelegate 或 org.eclipse.ui.IWorkbenchWindowPulldownDelegate 之類別的完整名稱。在 pulldown 為 true 的情況下,應該實作後者。如果 RETARGET 的屬性為 True,不支援此屬性。
-
RETARGET - 如果屬性為 True 則將建立 RETARGET (廣域)動作。
部份提供廣域動作處理程式,在他們的網站使用此動作 ID 設定廣域動作的標準機制。
如果這個屬性為 True,則不支援此類別屬性。
-
allowLabelUpdates - 只有當 RETARGET 為 true 時才能套用。如果這個屬性為 True,則
RETARGET 動作將從處理程式更新它的標籤和工具提示。
-
enablesFor - 指出必須符合啟動動作之選項計數的值。如果指定這個屬性且狀況符合,就會啟動動作。如果狀況不符合,就會停用動作。如果沒有指定屬性的話,就會啟用任何所選項目數的動作。以下是支援的屬性格式:
! - 選取 0 個項目
? - 選取 0 或 1 個項目
+ - 選取 1 或多個項目
multiple, 2+ - 選取 2 或更多個項目
n - 選取精確數目的項目。範例:4。
* - 任何所選項目的數目
<!ELEMENT selection EMPTY>
<!ATTLIST selection
class
CDATA #REQUIRED
name
CDATA #IMPLIED
>
-
class - 選項中每個物件都必須建立其子類別或加以實作以啟用動作之類別或介面的完整名稱。
-
name - 可選用地套用到選項中之物件的名稱所用的萬用字元過濾條件。如果指定這個過濾條件且找不到相符項目,就會將動作停用。
<!ELEMENT enablement (and | or | not | objectClass
| objectState | systemProperty | pluginState)*>
<!ATTLIST enablement EMPTY>
在 Eclipse 版本 2.0 中,啟用元素可能用來定義動作的啟用。關於更多使用啟用元素的詳細資訊,請參閱
actionExpressions.html。
範例:
以下是動作集的範例(請注意子元素和屬性的使用方式):
<extension point = "org.eclipse.ui.actionSets">
<actionSet id="com.xyz.actionSet"
label="My Actions"
visible="true">
<menu id="com.xyz.xyzMenu"
label="XYZ Menu"
path="additions">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&Run XYZ Tool"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
icon="icons/runXYZ.gif"
tooltip="Run XYZ Tool"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.RunXYZ"
enablesFor="1">
<selection class="org.eclipse.core.resources.IFile" name="*.java"/>
</action>
<action id="com.xyz.runABC"
label="&Run ABC Tool"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
icon="icons/runABC.gif"
tooltip="Run ABC Tool"
helpContextId="com.xyz.run_abc_action_context"
retarget="true"
allowLabelUpdate="true">
</action>
</actionSet>
</extension>
在上述範例中,開始時,每個視景內都可以見到名稱為 "My Actions" 的指定動作,只有單一選項能夠啟用它(enablesFor 屬性)。
另外,選項內的物件都必須實作指定的介面(IFile),且必須是 Java 檔。
API 資訊:class 屬性值必須是實作 org.eclipse.ui.IWorkbenchWindowActionDelegate 或 org.eclipse.ui.IWorkbenchWindowPulldownDelegate 之類別的完整名稱。
在 pulldown 為 true 的情況下,應該實作後者。這個類別的載入要儘可能晚,以避免在真正需要它之前載入整個外掛程式。
動作延伸項目的啟用準則是 enablesFor,選項和啟用所起始定義。然而,
一旦設定動作委派的實例化,它可能在 selectionChanged 方法內直接控制動作啟用狀態。
請務必記住,工作台不會代表外掛程式產生功能表:功能表路徑必須參照已存在的功能表。
動作和功能表標籤可含有利用下列規則來編碼助記符號和加速器的特殊字元:
-
助記符號則是利用已翻譯文字中所選取的字元前面加上 '&' 字元來指定的。由於 XML 字串中不能使用 & 符號,請使用 & 字元實體。
-
選用的加速器是利用 @,後面接著修飾元系列及最終的加速字元(如 &Save@Ctrl+S),在名稱字串的結尾指定的。
利用 '+' 作為定界符號可以將修飾元連結起來(如在 @Ctrl+Shift+S 中)。
如果透過單一延伸項目提供兩個或以上動作給功能表或工具列,
這些動作將按它們出現在 plugin.xml 檔的相反順序出現。這種行為是一般公認的非直覺行為。然而,在「Eclipse 平台 API」凍結後,已探索過它。現在變更行為將中斷每一個依賴現存之行為的外掛程式。
提供的實作:外掛程式可以利用這個延伸點來加入新的最上層功能表(如「除錯」)。
外掛程式也可以定義具名群組,以讓其他外掛程式提供其動作到其中。
最上層功能表是利用 path 屬性的下列值來建立的:
-
additions - 在「視窗」功能表左側呈現群組。
如果略過 path 屬性,結果會將新功能表新增到其他功能表列群組中。
工作台視窗中的預設群組定義在 IWorkbenchActionConstants 介面中。這些常數可用在動態提供的程式碼中。
這個值也可以複製到 XML 檔中,以更精密整合到現有工作台功能表及工具列中。
工作台視窗內的各種功能表和工具列項目都是以演算法定義。在這些情況下,必須利用個別機制來延伸視窗。
比方說,新增新的工作台檢視畫面會使「視窗」功能表中出現新的功能表項目。
「匯入」、「匯出」和「新建精靈」等延伸項目也會自動新增到視窗中。