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

識別碼: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?)>

   這個元素定義使用者可在 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) "push"
     state         (true | false)
     class         CDATA #REQUIRED
     enablesFor    CDATA #IMPLIED
     actionID      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.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 檔案資源時,就會啟用這個動作。

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

這個延伸點可用來提供動作到目標編輯器先前所建立的功能表中。 此外,可以提供功能表和動作給「工作台」視窗。 「工作台」視窗內的動作和主要群組的識別碼定義在 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>

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

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