蹦現功能表

識別碼:org.eclipse.ui.popupMenus

說明:這個延伸點用來新增動作至其他外掛程式所擁有的快速功能表中。動作的構成要素可以就某特定物件類型 (objectContribution) 或就檢視畫面或編輯器組件 (viewerContribution) 的特定快速功能表來進行。使用 objectContribution 時, 構成要素將出現在所有檢視畫面或編輯器組件快速功能表(選取指定類型之物件的所在)中。相反地,若使用 viewerContribution,則不管選擇為何, 構成要素僅會出現在指定的檢視畫面或編輯器組件快速功能表中。

當選項是異質的,可能的話,如果構成要素是就共用選項類型而登錄的,就會套用這個構成要素。 如果沒有直接相符項目,就會嘗試就超類別和超介面來找到相符項目。

您可以利用名稱過濾條件來進一步限制選項。 如果使用的話,選項中的所有物件都必須符合過濾條件,才能套用構成要素。

物件構成要素中的個別動作可以利用 enablesFor 屬性來指定它是適用於單一、多個或任何其他選項類型。

如果這些過濾機制都不適當,動作構成要素可使用過濾機制。在這個情況下,會以一系列的名稱值配對來說明目標物件的屬性。 適用於選項的屬性會隨著類型而不同,且會越過工作台本身的領域,因此, 工作台會將這個層次的過濾委派給實際的選項。

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

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

配置標記:

   <!ELEMENT extension (objectContribution , viewerContribution)>

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

   <!ELEMENT objectContribution (filter* , visibility? , menu* , action*)>

  這個元素係用來為任何檢視器快速功能表(將為它們選取指定類型的物件)定義動作及/或功能表的群組。

   <!ATTLIST objectContribution
      id          CDATA #REQUIRED
     objectClass CDATA #REQUIRED
     nameFilter  CDATA #IMPLIED
     adaptable   (true | false) "false"
   >

   <!ELEMENT viewerContribution (visibility? , menu* , action*)>

   這個元素係用來為特定檢視畫面或編輯器組件快速功能表定義動作及/或功能表的群組。

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

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

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

   <!ATTLIST action
      id               CDATA #REQUIRED
      label            CDATA #REQUIRED
     menubarPath      CDATA #IMPLIED
      icon             CDATA #IMPLIED
     helpContextId    CDATA #IMPLIED
     style            (push|radio|toggle)
     state            (true | false)
     class            CDATA #REQUIRED
     enablesFor       CDATA #IMPLIED
     overrideActionId CDATA #IMPLIED
      tooltip          CDATA #IMPLIED
   >

   <!ELEMENT filter EMPTY>

   這個元素係用來計算現行選擇中每個物件的屬性狀態。 僅在選項中的每一個物件都具有指定的屬性狀態時,才會進行比對。選項中的每一個物件必須實作或適合於 org.eclipse.ui.IActionFilter

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

   <!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.popupMenus"> 
      <objectContribution         id="com.xyz.C1" 
            objectClass="org.eclipse.core.resources.IFile" 
         nameFilter="*.java"> 
         <menu            id="com.xyz.xyzMenu" 
            path="additions" 
            label="&amp;XYZ Java Tools"> 
            <separator name="group1"/> 
         </menu> 
        <action            id="com.xyz.runXYZ" 
            label="&amp;Run XYZ Tool" 
            style="push"
            menubarPath="com.xyz.xyzMenu/group1"
            icon="icons/runXYZ.gif" 
            helpContextId="com.xyz.run_action_context" 
            class="com.xyz.actions.XYZToolActionDelegate" 
            enablesFor="1">
         </action> 
      </objectContribution> 
      <viewerContribution         id="com.xyz.C2" 
         targetID="org.eclipse.ui.views.TaskList">
        <action            id="com.xyz.showXYZ" 
            label="&amp;Show XYZ"
            style="toggle"
            state="true" 
            menubarPath="additions" 
            icon="icons/showXYZ.gif" 
            helpContextId="com.xyz.show_action_context" 
            class="com.xyz.actions.XYZShowActionDelegate"> 
         </action> 
      </viewerContribution> 
   </extension> 

在上述範例中,只有單一選項(enablesFor 屬性)能夠啟用指定的物件構成要素動作。另外,選項中的每個物件都必須實作指定的介面 (IFile),且必須是 Java 檔。這個動作會新增到先前建立的子功能表中。 在有必要選項的任何檢視畫面中,這個構成要素都有效。

相反地,上述檢視器構成要素快速功能表只會出現在「作業」檢視畫面快速功能表中,不會受到檢視畫面中之選項的影響。

下列是過濾機制的範例。在這種情況中,只會出現已完成且有高優先順序的 IMarkers 的動作。

   <extension point="org.eclipse.ui.popupMenus"> 
      <objectContribution         id="com.xyz.C3" 
         objectClass="org.eclipse.core.resources.IMarker"> 
         <filter name="done" value="true"/> 
         <filter name="priority" value="2"/> 
        <action            id="com.xyz.runXYZ" 
            label="High Priority Completed Action Tool" 
            icon="icons/runXYZ.gif" 
            class="com.xyz.actions.MarkerActionDelegate"> 
         </action> 
      </objectContribution> 
   </extension> 

下列是其他使用 visibility 元素的範例:

   <extension point="org.eclipse.ui.popupMenus"> 
      <viewerContribution         id="com.xyz.C4" 
         targetID="org.eclipse.ui.views.TaskList">
         <visibility>
            <and>
               <pluginState id="com.xyz" value="activated"/>
               <systemProperty name="ADVANCED_MODE" value="true"/>
            </and>
         </visibility>
        <action            id="com.xyz.showXYZ" 
            label="&amp;Show XYZ"
            style="push"
            menubarPath="additions" 
            icon="icons/showXYZ.gif" 
            helpContextId="com.xyz.show_action_context" 
            class="com.xyz.actions.XYZShowActionDelegate"> 
         </action> 
      </viewerContribution> 
   </extension> 

在上述範例中,指定的動作將以功能表項目出現在「作業」檢視畫面快速功能表中,但前提必須是 "com.xyz" 外掛程式作用中,且指定的系統內容設為 true。

API 資訊:action 屬性 class 的值必須是實作 org.eclipse.ui.IObjectActionDelegate(若是物件構成要素)、 org.eclipse.ui.IViewActionDelegate(若是屬於檢視畫面之快速功能表的構成要素) 或 org.eclipse.ui.IEditorActionDelegate(若是屬於編輯器之快速功能表的構成要素) 之 Java 類別的完整類別名稱。 在所有情況中,這個實作類別的載入要儘可能晚一些,以避免在真正需要它之前載入整個外掛程式。

附註:如需舊版相容性,可以對物件構成要素實作 org.eclipse.ui.IActionDelegate

僅在目標組件公佈了進行延伸的功能表時,才可能在組件內延伸快速功能表。 強烈鼓勵這樣做,因為它會增進產品的延伸性。 若要達成這樣的結果,每一個組件都應該呼叫 IWorkbenchPartSite.registerContextMenu, 來公佈任何定義的快速功能表。 一旦完成,工作台將自動插入任何存在的動作延伸項目。

您必須提供每個已登錄功能表的功能表 ID。 為了要有跨越各組件的一致性,所有組件的實作者都應採用下列策略。

任何以工作台登錄的快速功能表也應該含有 ID 為 IWorkbenchActionConstants.MB_ADDITIONS 的標準插入點。 其他外掛程式將使用此值作為插入的參考點。 定義插入點的做法為在適當的插入位置,將 GroupMarker 新增至功能表。

工作台中作為快速功能表之選項的物件可定義 org.eclipse.ui.IActionFilter。 這是可以執行類型特有之過濾的過濾策略。 工作台將擷取選項的過濾器,方法為進行測試以查看它是否實作 IActionFilter。如果失敗,工作台將透過 IAdaptable 機制要求一個過濾器。

動作和功能表標籤可能包含特定的字元編碼助記符號,助記符號是利用已翻換文字中所選取的字元前面加上 '&' 字元來指定的。 由於 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 的條款來使用