動作集

識別碼:org.eclipse.ui.actionSets

說明:這個延伸點用來將功能表、功能表項目和工具列按鈕新增到「工作台」視窗中的共用區。 這些構成要素統稱為動作集,而且會透過自訂視景的使用者,出現在「工作台」視窗中。

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

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

配置標記:

   <!ELEMENT extension (actionSet+)>

   <!ATTLIST extension
     point CDATA #REQUIRED
     id    CDATA #IMPLIED
     name  CDATA #IMPLIED
   >

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

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

   <!ATTLIST actionSet
      id          CDATA #REQUIRED
      label       CDATA #REQUIRED
     visible     (true | false)
     description CDATA #IMPLIED
   >

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

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

   <!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|pulldown) "push"
     state            (true | false)
     pulldown         (true | false)
     class            CDATA #IMPLIED
     retarget         (true | false)
     allowLabelUpdate (true | false)
     enablesFor       CDATA #IMPLIED
   >

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

   這個元素係用來在新功能表中建立具名群組。不同於 separator 元素, 它在新功能表中沒有任何視覺化表示法。

   <!ATTLIST groupMarker
     name CDATA #REQUIRED
   >

   <!ELEMENT selection EMPTY>

   這個元素係用來協助根據現行選擇,來判定動作的啟用狀態。如果指定了 enablement 元素,將予以忽略。

   <!ATTLIST selection
     class CDATA #REQUIRED
     name  CDATA #IMPLIED
   >

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

   這個元素係用來計算現行選擇中每個物件的類別或介面。 如果選擇中的每個物件都實作指定的類別或介面,則表示式將計算為 true。

   <!ATTLIST objectClass
     name CDATA #REQUIRED
   >

   <!ELEMENT objectState EMPTY>

   這個元素係用來計算現行選擇中每個物件的屬性狀態。 如果選擇中的每個物件都具有指定的屬性狀態,則表示式將計算為 true。 如果要計算這種類型的表示式,則選擇中的每個物件都必須實作或適合於 org.eclipse.ui.IActionFilter 介面。

   <!ATTLIST objectState
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >

   <!ELEMENT pluginState EMPTY>

   這個元素係用來計算外掛程式的狀態。外掛程式的狀態可以是下列之一:installedactivated

   <!ATTLIST pluginState
      id    CDATA #REQUIRED
     value (installed|activated) "installed"
   >

   <!ELEMENT systemProperty EMPTY>

   這個元素係用來計算某個系統內容的狀態。內容值擷取自 java.lang.System

   <!ATTLIST systemProperty
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >
範例:以下是動作集的範例(請注意子元素和使用屬性的方法):

    <extension point = "org.eclipse.ui.actionSets"> 
        <actionSet
            id="com.xyz.actionSet" 
            label="My Actions"> 
         <menu            id="com.xyz.xyzMenu" 
            label="XYZ Menu" 
               path="additions"> 
               <separator name="group1"/>
               <separator name="option1"/>
            </menu>
            
        <action            id="com.xyz.runXYZ" 
            label="&amp;Run XYZ Tool" 
            style="toggle"
            state="false" 
            menubarPath="com.xyz.xyzMenu/group1"
            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="&amp;Run ABC Tool"
            style="push"
            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">
               <enablement>
                  <and>
                     <objectClass name="org.eclipse.core.resources.IFile"/>
                     <not>
                        <objectState name="extension" value="java"/>
                     </not>
                  </and>
               </enablement>
            </action>             

        <action               id="com.xyz.runDEF"
               label="&amp;Run DEF Tool"
               style="radio"
            state="true" 
               menubarPath="com.xyz.xyzMenu/option1"
               icon="icons/runDEF.gif"
               tooltip="Run DEF Tool"
               class="com.xyz.actions.RunDEF" 
               helpContextId="com.xyz.run_def_action_context">
            </action>             
        <action               id="com.xyz.runGHI"
               label="&amp;Run GHI Tool"
               style="radio"
            state="false" 
               menubarPath="com.xyz.xyzMenu/option1"
               icon="icons/runGHI.gif"
               tooltip="Run GHI Tool"
               class="com.xyz.actions.RunGHI" 
               helpContextId="com.xyz.run_ghi_action_context">
            </action>             
        <action               id="com.xyz.runJKL"
               label="&amp;Run JKL Tool"
               style="radio"
            state="false" 
               menubarPath="com.xyz.xyzMenu/option1"
               icon="icons/runJKL.gif"
               tooltip="Run JKL Tool"
               class="com.xyz.actions.RunJKL" 
               helpContextId="com.xyz.run_jkl_action_context">
            </action>             
        </actionSet> 
   </extension> 

在上述範例中,開始時,每個視景內都看不到名為 "My Actions" 的指定動作集, 因為未指定 visible 屬性。

XYZ 動作將顯示為開始時並未勾選的勾選框功能表項目。僅在選擇計數為 1,且如果選擇含有 Java 檔案資源時,才會啟用它。

ABC 動作將同時出現在功能表和工具列。僅在選擇未含有任何 Java 檔案資源時,才會啟用它。亦請注意,這是標籤重定目標動作,因此它不會提供 class 屬性。

動作 DEF、GHI 和 JKL 顯示為圓鈕功能表項目。它們始終都是啟用的,與現行選擇狀態無關。

API 資訊:class 屬性值必須是實作 org.eclipse.ui.IWorkbenchWindowActionDelegateorg.eclipse.ui.IWorkbenchWindowPulldownDelegate 之類別的完整名稱。 如果 style 屬性具有 pulldown 值,應該實作後者。 這個類別是負責執行動作的處理程式。如果 retarget 屬性為 true, 將忽略這個屬性,且不應該提供它。這個類別的載入要儘可能晚,以避免在真正需要它之前載入整個外掛程式。

動作延伸項目的啟用準則起初是由 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>

提供的實作方式:外掛程式可以利用這個延伸點來加入新的最上層功能表。外掛程式也可以定義具名群組,以讓其他外掛程式提供其動作到其中。

最上層功能表是利用下列 path 屬性值來建立的:

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

工作台視窗中的預設群組定義在 IWorkbenchActionConstants 介面中。 這些常數可用在動態提供的程式碼中。 這個值也可以複製到 XML 檔中,以更精密整合到現有工作台功能表及工具列中。

工作台視窗內的各種功能表和工具列項目都是以演算法定義。在這些情況下, 必須利用個別機制來延伸視窗。比方說,新增新的工作台檢視畫面會在「視景」功能表中出現新的功能表項目。 「匯入」、「匯出」和「新建精靈」等延伸項目也會自動新增到視窗中。

Copyright (c) 2000, 2003 IBM Corporation and others. All rights reserved. 這個程式和伴隨的素材可以根據伴隨這個分送,而且可在 http://www.eclipse.org/legal/cpl-v10.html 中取得的 Common Public License v1.0 的條款來使用