檢視畫面功能表、工具列和動作

識別碼:org.eclipse.ui.viewActions

說明:這個延伸點係用來在其他外掛程式所登錄的檢視畫面的下拉功能表和工具列中加入動作。 每個檢視畫面都有一個本端下拉功能表,通常按一下右上角三角形按鈕就可以啟動它。 其他外掛程式可以提供子功能表和動作到這個功能表中。 外掛程式也提供動作到檢視畫面工具列中。 檢視擁有者最先有機會移入這些區域。 其他外掛程式的選用新增內容會附加在後面。

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

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

配置標記:

   <!ELEMENT extension (viewContribution+)>

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

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

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

   <!ATTLIST viewContribution
      id       CDATA #REQUIRED
     targetID CDATA #REQUIRED
   >

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

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

   <!ATTLIST action
      id            CDATA #REQUIRED
      label         CDATA #REQUIRED
     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
   >

   <!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.viewActions"> 
      <viewContribution          id="com.xyz.xyzViewC1" 
         targetID="org.eclipse.ui.views.navigator.ResourceNavigator"> 
         <menu            id="com.xyz.xyzMenu" 
               label="XYZ Menu"
            path="additions"> 
            <separator name="group1"/> 
         </menu> 
        <action            id="com.xyz.runXYZ" 
            label="&amp;Run XYZ Tool" 
            menubarPath="com.xyz.xyzMenu/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> 
     </viewContribution> 
   </extension> 

在上述範例中,只有單一選項能夠啟用指定的動作(enablesFor 屬性)。 此外,選擇中的物件必須是 Java 檔案資源。

以下是檢視畫面動作延伸項目的其他範例:

   <extension point="org.eclipse.ui.viewActions"> 
      <viewContribution          id="com.xyz.xyzViewC1" 
         targetID="org.eclipse.ui.views.navigator.ResourceNavigator"> 
         <menu            id="com.xyz.xyzMenu" 
               label="XYZ Menu"
            path="additions"> 
            <separator name="group1"/> 
         </menu> 
        <action            id="com.xyz.runXYZ2" 
            label="&amp;Run XYZ2 Tool" 
            menubarPath="com.xyz.xyzMenu/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> 

在上述範例中,指定的動作將以功能表項目出現。當選擇沒有 Java 檔案資源時,就會啟用這個動作。

API 資訊:class 屬性值必須是實作 org.eclipse.ui.IViewActionDelegate 之 Java 類別的完整名稱。 這個類別的載入要儘可能晚,以避免在真正需要它之前載入整個外掛程式。

org.eclipse.ui.IViewActionDelegate 介面延伸 org.eclipse.ui.IActionDelegate, 並新增一個額外方法,容許提供至其中的檢視畫面實例來起始設定委派。

這個延伸點可用來提供動作到目標檢視畫面先前所建立的功能表中。如果略過 menu 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 的條款來使用