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

識別碼:org.eclipse.ui.editorActions

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

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

配置標記:

   <!ELEMENT editorContribution (menu | action)*>
   <!ATTLIST editorContribution
      id         CDATA #REQUIRED
      targetID   CDATA #REQUIRED
   >

  • id - 可用來參照這項構成要素的唯一識別碼
  • editorID - 本身是先前所登錄而成為這個構成要素的目標之編輯器的唯一識別碼
  •    <!ELEMENT menu (separator)+>
       <!ATTLIST menu
          id         CDATA #REQUIRED
          label      CDATA #REQUIRED
          path       CDATA #IMPLIED
       >    <!ELEMENT separator EMPTY>
       <!ATTLIST separator
          name       CDATA #REQUIRED
       >
  • name - 之後可作為動作路徑中最後一個記號來參照的分隔字元名稱。因此,分隔字元可作為動作可新增其中的具名群組。
  •    <!ELEMENT action (selection)* (enablement)?>
       <!ATTLIST action
          id                NMTOKEN #REQUIRED
          label             CDATA #REQUIRED
          accelerator       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
          class             CDATA #REQUIRED
          enablesFor        CDATA #IMPLIED
       >    <!ELEMENT selection EMPTY>
       <!ATTLIST selection
          class             CDATA #REQUIRED
          name              CDATA #IMPLIED
       >    <!ELEMENT enablement (and | or | not | objectClass | objectState | systemProperty
            | pluginState)>
       <!ATTLIST enablement EMPTY>
    在第 2.0 版的 Eclipse 中,enablement 元素可用來定義是否要啟用動作。 如需如何使用 enablement 元素的詳細資訊,請參閱 actionExpressions.html
    開始時,動作延伸項目的啟用準則是由 enablesFor、 selectionenablement 來定義的。不過,在建立好動作委派的實例之後,它會直接在其 selectionChanged 方法中控制動作啟用狀態。

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

    1. 助記符號則是利用已翻譯文字中所選取的字元前面加上 '&' 字元來指定的。由於 XML 字串中不能使用&符號,請使用 &amp; 字元實體。
    2. 選用的加速器是利用 @,後面接著修飾元系列及最終的加速字元(如 &amp;Save@Ctrl+S),在名稱字串的結尾指定的。利用 '+' 作為定界符號可以將修飾元連結起來(如在 @Ctrl+Shift+S 中)。
    如果透過單一延伸項目提供兩個或以上動作給功能表或工具列, 這些動作將按它們出現在 plugin.xml 檔的相反順序出現。這種行為是一般公認的非直覺行為。然而,在「Eclipse 平台 API」凍結後,已探索過它。現在變更行為將中斷每一個依賴現存之行為的外掛程式。

    範例:

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

       <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"
                  state="true"
                  icon="icons/runXYZ.gif"
                  tooltip="Run XYZ Tool"
                  helpContextId="com.xyz.run_action_context"
                  class="com.xyz.actions.RunXYZ">
             </action>
          </editorContribution>
       </extension>

    在上述範例中,指定的動作會成為最上層新功能表(XYZ 功能表)中的勾選框項目及工具列中的切換按鈕。

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

       <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"
                  state="true"
                  icon="icons/runXYZ2.gif"
                  tooltip="Run XYZ2 Tool"
                  helpContextId="com.xyz.run_action_context2"
                  class="com.xyz.actions.RunXYZ2">
             </action>
          </editorContribution>
       </extension>

    在上述範例中,指定的動作會成為子功能表(XYZ2 功能表)中和最上層「編輯」功能表中的勾選框項目。

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

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

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

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

    Copyright IBM Corporation and others 2000, 2002.