共通ビューアー構成

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>

クライアントは、どのコンテンツ拡張機能と共通フィルターがビューアーに対して可視 であるかを記述するために、1 つ以上の viwerContentBinding 要素を定義する必要があります。コンテンツ拡張機能または共通フィルターの ID が viewerContentBinding の下の includes 文と一致しており、かつ excludes 文によって除外されていない場合は、コンテンツ拡張機能または共通フィルターは可視 です。コンテンツ拡張機能または共通フィルターが、ビューアーに対して可視 でない場合は、拡張機能はそのビューアーのコンテンツ・サービスによってコンテンツを求められることがなく、また使用可能なフィルター・ダイアログ内でユーザーに表示されることもありません。

クライアントは、ビューアーに対してどの拡張機能が可視 であるかを選択するように includes 要素を定義し、また同様に、ビューアーに対して可視 にすべきではない拡張機能の excludes 要素を定義することができます。クライアントはさらに、ルート要素について明示的に照会する必要のある拡張機能を、「isRoot」属性によって (ITreeContentProvider.getElements() を介して) 定義できます。 1 つ以上の contentExtension 要素が、includes 文内で true に設定された「isRoot」を持っている場合、これらの拡張機能でのみ、ルート要素が照会されます。「isRoot」属性には、除外の効果はありません。

ビューアーには、複数の viewerContentBindings が定義されることがあります。また、その 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」属性と一致するビューアーのコンテンツ拡張機能を検索する際に組み込む必要のあるパターンのセットを定義します。 include 文と exclude 文が交差するする場合、include 文に優先順位が与えられます。



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

「viewerId」属性と一致するビューアーのコンテンツ拡張機能を検索する際に除外する必要のあるパターンのセットを定義します。 include 文と exclude 文が交差する場合、include 文に優先順位が与えられます。



<!ELEMENT contentExtension EMPTY>

<!ATTLIST contentExtension

pattern CDATA #REQUIRED

isRoot  (true | false) >

ビューアーのルートについて ITreeContentProvider.getElements() または ITreeContentProvider.getChildren() によって照会される必要のあるコンテンツ拡張機能の ID (または一致するパターン)、あるいは「使用可能なフィルター」ダイアログ内でユーザーに対して使用可能にする共通フィルターの ID (または一致するパターン) を示します。

クライアントは、(ビューアー入力要素の一致する triggerPoints 式を基にして) ビューアー入力要素に対して使用可能となる拡張機能を上書きするため、特定のルート拡張機能を選択するように「isRoot」を指定することができます。

詳細は、viewerContentBinding の文書を参照してください。



<!ELEMENT actionExtension EMPTY>

<!ATTLIST actionExtension

pattern CDATA #REQUIRED>

コンテキスト・メニューおよびアクション・バーにコントリビュートするための機会を与えられるべきアクション拡張機能を示します。

詳細は、viewerActionBinding の文書を参照してください。



<!ELEMENT popupMenu (insertionPoint*)>

<!ATTLIST popupMenu

id                          CDATA #IMPLIED

allowsPlatformContributions (true | false) >

ビューアー要素の「popupMenuId」属性が指定されていない場合のみ、popupMenu 要素が定義されます。

popupMenu 要素によって、ビューアーに関連付けられたコンテキスト・メニューをさらにカスタマイズすることができます。オプションが正しく適用されるように、ビューアーのインスタンスは org.eclipse.ui.navigator.NavigatorActionService に委任する必要があります。これは標準の org.eclipse.ui.ActionGroup のように振る舞います。この機能の活用法についての詳細は、この API クラスの文書を参照してください。 org.eclipse.ui.navigator.CommonNavigator のインスタンスを使用するクライアントは、追加の作業を行う必要がありません。

popupMenu は、意味のある、使いやすい、一貫性のあるリストへコントリビューションを編成するするために、コントリビューターによって使用される 1 つ以上の insertionPoints を宣言します。
クライアントがビューアー要素の「popupMenuId」属性を指定するだけの場合は、コンテキスト・メニューによって使用される insertionPoints のセットは、特定の順序での以下のリストにデフォルト設定されます。

"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.CommonViewerorg.eclipse.jface.util.LocalSelectionTransfer タイプを提供するので、この要素は必須ではありません。

クライアントは、浅い依存ツリーのある軽量のプラグインでこの拡張機能を定義することのみ必要です。ドラッグ支援機能は、ビューアーが作成されるとき、前もってロードされている必要があります。これにより、影響を受けるプラグインのロードが強制されます。



以下の例は、ビューアーのためのポップアップ・メニュー ID を構成します。


   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer id=

"org.eclipse.testViewer"

popupMenuId=

"org.eclipse.testViewer#PopupMenu"

/>

</extension>

ビューアーの popupMenu 子要素が上記の例で使用されなくなったので、insertionPoints のデフォルト設定が使用されます。この設定は以下のように定義されます。詳しくは、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 要素で並行的に指定されていないことに注目してください。両方ではなく、どちらか 1 つのみが有効な構成です。

   

<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>

以下の例では、1 つのコンテンツ拡張機能 (ID は「org.eclipse.ui.navigator.resourceContent」) が、ID 「org.eclipse.ui.navigator.resourceContent」が一致するビューアーとバインドされることを宣言しています。 (この例では、コンテンツ拡張機能とビューアーの ID が一致していますが、これは必要ではありません。) さらに、「org.eclipse.ui.navigator.tests.」で始まる ID を持つコンテンツ拡張機能はすべて、無視されます。

   

<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.*」とは一致しない、(navigatorContent 拡張機能の下でネストされていない) すべての actionProvider に対する viewerActionBinding を宣言します。この式は、その ID が「org.acme.actions.」で始まり、「org.acme.actions.tests.」では始まらないすべての actionProvider を、ID「org.acme.viewer」を持つビューアーに対して可視 にします。もちろん、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>

以下の例は、「id」属性を持たないすべての actionProvider を、ビューアー「org.acme.viewer」に対して可視 にします。「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

"Link with Editor"

action from the toolbar of the viewer -->

<property name=

"org.eclipse.ui.navigator.hideLinkWithEditorAction"

value=

"true"

/>

<!-- Hide the

"Collapse All"

action from the toolbar of the viewer -->

<property name=

"org.eclipse.ui.navigator.hideCollapseAllAction"

value=

"true"

/>

</options>

</viewer>

</extension>