共用檢視器配置

org.eclipse.ui.navigator.viewer

3.2

viewer 元素定義共用檢視器的配置。延伸規格可能提供自訂的蹦現功能表 id、 忽略檢視器是否提供編輯器支援的鏈結、提供過濾對話框,及/或提供「可用的自訂」對話框。 此外,巢狀配置元素可完全控制蹦現快速功能表的結構和行為。

viewerContentBinding 將定義的內容延伸規格(透過 navigatorContent 延伸點) 連結至檢視器(透過 org.eclipse.ui.views 延伸點來定義)。 連結至檢視器的任何內容延伸規格皆視為可見的。 內容服務 (org.eclipse.ui.navigator.INavigatorContentService) 不會傳回檢視器 id 不可見的任何延伸規格。

<!ELEMENT extension (viewer* , viewerContentBinding* , viewerActionBinding* , dragAssistant)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT viewer (popupMenu? , options?)>

<!ATTLIST viewer

viewerId    CDATA #REQUIRED

popupMenuId CDATA #IMPLIED>

提供基本配置來建立檢視器的性質。用戶端也必須定義 org.eclipse.ui.views 延伸規格來建立視圖組件。



<!ELEMENT viewerContentBinding (includes? , excludes?)>

<!ATTLIST viewerContentBinding

viewerId CDATA #REQUIRED>

用戶端必須定義一或多個 viwerContentBinding 元素,描述檢視器可見的內容延伸規格和一般過濾器。 內容延伸規格或一般過濾器的 id 必須符合 viewerContentBinding 下的 includes 陳述式, 且未被 excludes 陳述式所排除,內容延伸規格或一般過濾器才是可見的。 如果內容延伸規格或一般過濾器不是檢視器可見的,則內容服務絕不會向延伸規格要求該檢視器的內容,在可用的過濾器對話框中也不會顯示此延伸規格。

用戶端可定義 includes 元素來選取檢視器可見的延伸規格, 同樣也可定義 excludes 元素來選取檢視器不可見的延伸規格。 用戶端可進一步定義延伸規格,供 "isRoot" 屬性來明確查詢根元素(透過 ITreeContentProvider.getElements())。 如果在 includes 陳述式內有一或多個 contentExtension 元素將 "isRoot" 設為 true,則只會在這些延伸規格中查詢根元素。 "isRoot" 屬性不影響排除。

一個檢視器可定義多個 viewerContentBinding,且 includes/excludes 陳述式將彙總來決定最終的行為。



<!ELEMENT viewerActionBinding (includes? , excludes?)>

<!ATTLIST viewerActionBinding

viewerId CDATA #REQUIRED>

用戶端必須定義檢視器可見的動作提供者。用戶端可定義 includes 元素來選取檢視器可見的延伸規格, 同樣也可定義 excludes 元素來選取檢視器不可見的延伸規格。

一個檢視器可定義多個 viewerActionBinding,且 includes/excludes 陳述式將彙總來決定最終的行為。

對於不是在 navigatorContent 定義下巢狀的 actionProvider 定義,用戶端可指定自訂 id。 如果用戶端不指定 id,則 id 預設為 "org.eclipse.ui.navigator.actionProvider.X"。 對於需要挑選 actionProvider 但沒有特定 id 的用戶端,用戶端必須定義預設 id 的 viewerActionBinding。 相關作法請參閱範例段落。



<!ELEMENT includes ((contentExtension+) | (actionExtension+))>

定義在內容延伸規格中尋找符合 "viewerId" 屬性的檢視器時要包含的一組型樣。當 includes 和 excludes 陳述式交錯時,以 includes 陳述式為優先。



<!ELEMENT excludes ((contentExtension+) | (actionExtension+))>

定義在內容延伸規格中尋找符合 "viewerId" 屬性的檢視器時要排除的一組型樣。當 includes 和 excludes 陳述式交錯時,以 includes 陳述式為優先。



<!ELEMENT contentExtension EMPTY>

<!ATTLIST contentExtension

pattern CDATA #REQUIRED

isRoot  (true | false) >

指出內容延伸規格的 id(或相符型樣), 供 ITreeContentProvider.getElements()ITreeContentProvider.getChildren() 來查詢檢視器的根或使用者在「可用的過濾器」對話框中可用的一般過濾器。

用戶端可指定 "isRoot",選取特定的根延伸規格來置換其他延伸規格,否則檢視器輸入元素會啟用這些延伸規格 (根據檢視器輸入元素相符的 triggerPoints 表示式)。

如需相關資訊,請參閱 viewerContentBinding 的文件。



<!ELEMENT actionExtension EMPTY>

<!ATTLIST actionExtension

pattern CDATA #REQUIRED>

指出可提供給快速功能表和動作列的動作延伸規格。

如需相關資訊,請參閱 viewerActionBinding 的文件。



<!ELEMENT popupMenu (insertionPoint*)>

<!ATTLIST popupMenu

id                          CDATA #IMPLIED

allowsPlatformContributions (true | false) >

未指定 viewer 元素的 "popupMenuId" 屬性時,才能定義 popupMenu 元素。

popupMenu 元素容許進一步自訂檢視器相關的快速功能表。 為了正確套用選項,檢視器實例必須委派 org.eclipse.ui.navigator.NavigatorActionService, 此類別如同正常的 org.eclipse.ui.ActionGroup 一樣。 如需利用這項功能的相關資訊,請參閱這個 API 的文件。 對於使用 org.eclipse.ui.navigator.CommonNavigator 實例的用戶端,則不必做任何動作。

popupMenu 宣告一或多個 insertionPoint,供貢獻者將構成要素組織成有意義、更方便、一致的清單。
如果用戶端僅指定 viewer 元素的 "popupMenuId" 屬性, 則快速功能表使用的 insertionPoint 配對依給定的次序預設為下列清單:

"group.new"             separator="true"
"group.goto"            
"group.open"            separator="true"
"group.openWith"
"group.show"            separator="true"
"group.edit"            separator="true"
"group.reorganize"
"group.port"
"group.generate"        separator="true"
"group.search"          separator="true"
"group.build"           separator="true"
"additions"             separator="true" 
"group.properties"      separator="true"


需要在程式中參照這些值的用戶端可使用 org.eclipse.ui.navigator.ICommonMenuConstants 中相對應的常數。

建議需要自訂功能表的用戶端可從這個清單開始,視需要來新增或移除插入點。 也建議用戶端一律以 "group." 作為每一個群組名稱的開頭.

如果指定 popupMenu 元素且「不」含 insertionPoint 子元素,則快速功能表不會有發佈的插入點。 當然,程式化用戶端可視需要來自行新增插入點。對於定義檢視器的用戶端,基於記錄用途和簡潔性, 建議將下游延伸規格的插入點發佈至檢視器/導覽器,或明確指出哪些插入點視為 API,哪些視為內部。



<!ELEMENT insertionPoint EMPTY>

<!ATTLIST insertionPoint

name      CDATA #REQUIRED

separator (true | false) >

定義快速功能表的插入點。包括供用戶端參照的插入點名稱,以及插入點是否呈現為分隔線或群組標記。



<!ELEMENT options (property+)>

提供選項供檢視器來自訂如何呈現給使用者。如需可用的內容,請參閱 org.eclipse.ui.navigator.INavigatorViewerDescriptor



<!ELEMENT property EMPTY>

<!ATTLIST property

name  CDATA #REQUIRED

value CDATA #REQUIRED>

提供 name=value 配對。值會原封不動地提供給檢視器(空字串依然以空字串傳送)。關於可用的內容及說明,請參閱 org.eclipse.ui.navigator.INavigatorViewerDescriptor



<!ELEMENT dragAssistant EMPTY>

<!ATTLIST dragAssistant

class    CDATA #REQUIRED

viewerId CDATA #REQUIRED>

「拖放」輔助提供輕型連結鉤,供應額外的轉送類型和邏輯來設定拖曳資料。 因為基本 org.eclipse.ui.navigator.CommonViewer 提供了 org.eclipse.jface.util.LocalSelectionTransfer 類型,因此,已不需要這個元素。

用戶端只需要在陰影相依關係樹的輕型外掛程式中定義這個延伸規格。在建立檢視器的一開始必須載入拖曳輔助,以強制載入受影響的外掛程式。



下列範例配置檢視器的蹦現功能表 id。


   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer id=

"org.eclipse.testViewer"

popupMenuId=

"org.eclipse.testViewer#PopupMenu"

/>

</extension>

由於上述範例未使用檢視器的 popupMenu 子元素,將使用預設的 insertionPoint 集。 這個集的定義如下。如需相關資訊,請參閱 popupMenu 元素的文件。

"group.new"             separator="true"
"group.goto"            
"group.open"            separator="true"
"group.openWith"
"group.show"            separator="true"
"group.edit"            separator="true"
"group.reorganize"
"group.port"
"group.generate"        separator="true"
"group.search"          separator="true"
"group.build"           separator="true"
"additions"             separator="true" 
"group.properties"      separator="true"

下列範例示範檢視器配置,其中宣告自訂的 popupMenu/insertionPoints,但以 "allowsPlatformContributions" 屬性來限制物件和檢視器構成要素。 用戶端只能透過檢視器宣告的 org.eclipse.ui.navigator.CommonActionProvider 來提供給定義的功能表(最上層或與內容延伸規格有關聯)。

請注意,"popupMenuId" 屬性和 popupMenu 元素不同時指定。有效的配置只能指定其中一個(而非兩者)。

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer viewerId=

"org.eclipse.ui.navigator.resourceContent"

>

<popupMenu allowsPlatformContributions=

"false"

id=

"org.eclipse.ui.navigator.resourceContent#PopupMenu"

>

<insertionPoint name=

"group.new"

/>

<insertionPoint name=

"group.open"

separator=

"true"

/>

<insertionPoint name=

"group.openWith"

/>

<insertionPoint name=

"group.port"

separator=

"true"

/>

<insertionPoint name=

"additions"

separator=

"true"

/>

<insertionPoint name=

"group.properties"

separator=

"true"

/>

</popupMenu>

</viewer>

<viewerContentBinding viewerId=

"org.eclipse.ui.navigator.resourceContent"

>

<includes>

<contentExtension pattern=

"org.eclipse.ui.navigator.resourceContent"

/>

</includes>

</viewerContentBinding>

</extension>

下列範例宣告一個內容延伸規格 (id: "org.eclipse.ui.navigator.resourceContent") 連結至符合 id "org.eclipse.ui.navigator.resourceContent" 的檢視器。 (在此範例中,內容延伸規格和檢視器 id 相符,但非必要。)再者,將忽略 id 開頭為 "org.eclipse.ui.navigator.tests." 的任何內容延伸規格。

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewerContentBinding viewerId=

"org.eclipse.ui.navigator.resourceContent"

>

<includes>

<contentExtension pattern=

"org.eclipse.ui.navigator.resourceContent"

/>

</includes>

<excludes>

<contentExtension pattern=

"org.eclipse.ui.navigator.tests.*"

/>

</excludes>

</viewerContentBinding>

</extension>

在下列範例中,對於符合正規表示式 "org.acme.actions.*" 而非 "org.acme.actions.tests.*" 的所有 actionProvider(未置於 navigatorContent 延伸規格之下),宣告 viewerActionBinding。 對於 id "org.acme.viewer" 的檢視器,這個表示式會將 id 開頭為 "org.acme.actions." 而非 "org.acme.actions.tests." 的任何 actionProvider 變成可見的。 當然,viewerActionBindings 僅適用於未巢狀於 navigatorContent 元素之下的 actionProvider 元素。 巢狀 actionProvider 元素的可見性是由外圍 navigatorContent 元素的 viewerContentBinding 所控制。

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewerActionBinding viewerId=

"org.acme.viewer"

>

<includes>

<actionExtension pattern=

"org.acme.actions.*"

/>

</includes>

<excludes>

<actionExtension pattern=

"org.acme.actions.tests.*"

/>

</excludes>

</viewerActionBinding>

</extension>

對於檢視器 "org.acme.viewer",下列範例將不具 "id" 屬性的任何 actionProvider 變成可見的。 沒有 "id" 屬性的 actionProvider 預設為 id "org.eclipse.ui.navigator.actionProvider.X"。 當然,viewerActionBindings 僅適用於未巢狀於 navigatorContent 元素之下的 actionProvider 元素。 巢狀 actionProvider 元素的可見性是由外圍 navigatorContent 元素的 viewerContentBinding 所控制。

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewerActionBinding viewerId=

"org.acme.viewer"

>

<includes>

<actionExtension pattern=

"org.eclipse.ui.navigator.actionProvider.*"

/>

</includes>

</viewerActionBinding>

</extension>

下列範例示範檢視器可用的標準內容。

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer popupMenuId=

"org.eclipse.ui.tests.navigator.TestView#PopupMenu"

viewerId=

"org.eclipse.ui.tests.navigator.TestView"

>

<options>

<!-- Hide the

"Available Extensions"

tab in the

"Available Customizations"

dialog (available from the

"Filters"

action -->

<property name=

"org.eclipse.ui.navigator.hideAvailableExtensionsTab"

value=

"true"

/>

<!-- Hide the

"Available Customizations"

dialog completely. This includes hiding the filters and the available content extensions. -->

<property name=

"org.eclipse.ui.navigator.hideAvailableCustomizationsDialog"

value=

"true"

/>

<!-- Hide the

"鏈結編輯器"

action from the toolbar of the viewer -->

<property name=

"org.eclipse.ui.navigator.hideLinkWithEditorAction"

value=

"true"

/>

<!-- Hide the

"全部收合"

action from the toolbar of the viewer -->

<property name=

"org.eclipse.ui.navigator.hideCollapseAllAction"

value=

"true"

/>

</options>

</viewer>

</extension>