裝飾元

您的外掛程式可以使用裝飾元來註解出現在工作台視圖中的資源和其他物件影像。當您的外掛程式為現有的資源類型新增功能時,裝飾元是非常有用的。許多標準工作台視圖參與顯示裝飾。

例如,PDE 提供裝飾元,讓您分辨二進位專案和程式碼專案。

內含 PDE 裝飾元的套件瀏覽器視圖

com.example.helloworld  專案是顯示在導覽器中唯一的程式碼專案。請注意所有其他二進位專案如何在 Java 專案圖示的左上方顯示二進位裝飾元。這個裝飾元是 PDE 使用 org.eclipse.ui.decorators 延伸點所提供。

    <extension
     point="org.eclipse.ui.decorators">
      <decorator
            lightweight="true"
            quadrant="TOP_LEFT"
            adaptable="true"
            label="%decorator.label"
            icon="icons/full/ovr16/binary_co.png"
            state="false"
            id="org.eclipse.pde.ui.binaryProjectDecorator">
         <description>
            %decorator.desc
         </description>
       <enablement> 
            ...
       </enablement> 
      </decorator>
    </extension>

有數種不同的方法,可用來提供裝飾元實作。 這個標記使用最簡單的方法,稱為宣告的小型裝飾元。 當定義了宣告的小型裝飾元時,標記將含有裝飾元的圖示、 放置位置及啟用條件的完整說明。僅在使用圖示來裝飾標籤時,宣告的裝飾元才有用。 外掛程式僅需要指定象限,在這裡裝飾元應該覆蓋在一般圖示和覆蓋圖示之上。 如同圖片中所示,PDE 二進位圖示覆蓋在套件圖示的左上端象限。

如果除了圖示之外,您的外掛程式還需要操作標籤文字,或者, 如果圖示類型是以動態方法判定,您可以使用非宣告的小型裝飾元。在此情況下,實作 ILightweightLabelDecorator 的實作類別必須加以定義。指定的類別負責提供在執行時期要套用至標籤的字首、字尾和覆蓋影像。背景緒中的工作台程式碼會處理將字首和字尾與標籤文字連結一起, 並執行覆蓋的機制。因此,任何由您的外掛程式在其 ILightweightLabelDecorator 實作中執行的工作必須能夠安全地使用 UI-執行緒。(如果需要詳細資料, 請參閱從非 UI 執行緒執行程式碼。)

下列標記顯示 CVS 用戶端如何使用這個技術來定義它的裝飾元:

    <extension
     point="org.eclipse.ui.decorators">
      <decorator
            objectClass="org.eclipse.core.resources.IResource"
            adaptable="true"
        label="%DecoratorStandard.name"
            state="false"
            lightweight= "true"
            quadrant = "BOTTOM_RIGHT"
            class="org.eclipse.team.internal.ccvs.ui.CVSLightweightDecorator"
        id="org.eclipse.team.cvs.ui.decorator">
         <description>
            %DecoratorStandard.desc
         </description>
      </decorator>
    </extension>

裝飾元最終是由使用者透過工作台標籤裝飾喜好設定頁面來控制。 個別裝飾元可以開啟和關閉。即使如此,設計您的裝飾元, 以便它們不會與現有的平台 SDK 裝飾元發生重疊或衝突,是不錯的主意。如果有多個外掛程式提供小型裝飾元給相同的象限, 將無法判定是否能夠解析衝突。  

您的外掛程式也可能自行管理所有影像和標籤。在這種情況下,lightweight 屬性應該設成 false,而 class 屬性應該命名一個實作 ILabelDecorator 的類別。 這個類別可讓您以自己的來附註裝飾程式標籤的影像和文字。它將給與您更大的彈性,因為您不會受到字首、字尾和簡單象限覆蓋的限制。

其他裝飾元屬性與特殊實作樣式無關。labeldescription 屬性指定用來在喜好設定對話框中命名和說明裝飾元的文字。objectClass 命名應該套用裝飾元的物件類別。enablement 屬性可讓您說明在哪些條件下應該裝飾物件。adaptable 旗標指出是否也應該裝飾適合 IResource 的物件。 state 旗標控制在預設的情況下是否看得見裝飾元。

如果您的裝飾元包含難以計算或潛在複雜的資訊,當它開啟時, 您可能要提供自己的喜好設定,讓使用者做進一步細部調整裝飾元。這是 CVS 用戶端所使用的技術。

「CVS 裝飾元」喜好設定頁面

 

裝飾元更新循環

裝飾藉由自動更新標籤提供者來初值設定,該標籤提供者使用 DecoratorManager 來提供裝飾。由於裝飾處理程序是在背景中完成的,因此,裝飾計算會計算在要求標籤和發動 labelProviderChanged 事件之間的那一段時間。這段期間內,因效率因素,只會計算一次「物件」上的裝飾。 如果在這段期間內變更了裝飾元,則舊結果可能會被當成第二個和後續呼叫來廣播,以裝飾會被忽略的元素。

裝飾元貢獻者應在裝飾時,避免變更它們的裝飾元。如果不可能避免,則需要第二個呼叫,以在處理 labelProviderChanged 之後裝飾元素。