Konfiguration für allgemeine Anzeigefunktionen

org.eclipse.ui.navigator.viewer

3.2

Das Element viewer definiert die Konfiguration für eine allgemeine Anzeigefunktion. Die Erweiterung kann eine ID für ein angepasstes Kontextmenü angeben sowie überschreiben, ob die Anzeigefunktion einen Link zur Editorunterstützung, einen Filterdialog und/oder einen Dialog "Verfügbare Anpassungen " bereitstellt. Außerdem erhalten verschachtelte Konfigurationselemente die vollständige Steuerung über die Struktur und das Verhalten des Kontextmenüs.

Ein Element viewerContentBinding bindet (über den Erweiterungspunkt navigatorContent) definierte Inhaltserweiterungen an Anzeigefunktionen (die über den Erweiterungspunkt org.eclipse.ui.views definiert sind). Jede an eine Anzeigefunktion gebundene Inhaltserweiterung wird mit dem Wert visible beschrieben. Ein Inhaltsservice (org.eclipse.ui.navigator.INavigatorContentService) gibt keine Erweiterungen zurück, die für die ID seiner Anzeigefunktion nicht mit dem Wert "visible" als sichtbar definiert sind.

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

Stellt die Basiskonfiguration bereit, um die Kenndaten einer Anzeigefunktion zu erstellen. Clients müssen außerdem eine Erweiterung org.eclipse.ui.views definieren, um die Sichtkomponente zu erstellen.



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

<!ATTLIST viewerContentBinding

viewerId CDATA #REQUIRED>

Clients müssen eines oder mehrere Elemente viewerContentBinding definieren, um die Inhaltserweiterungen und allgemeinen Filter zu beschreiben, die für die Anzeigefunktion sichtbar sind. Eine Inhaltserweiterung oder ein allgemeiner Filter ist sichtbar, falls die ID der Inhaltserweiterung bzw. des allgemeinen Filters mit einer untergeordneten Anweisung includes von viewerContentBinding übereinstimmt und nicht durch eine Anweisung excludes ausgeschlossen wird. Ist eine Inhaltserweiterung oder ein allgemeiner Filter für eine Anzeigefunktion nicht sichtbar, fordert weder ein Inhaltsservice für diese Anzeigefunktion jemals Inhalt von der Erweiterung an, noch wird die Erweiterung für den Benutzer im Dialog mit den verfügbaren Filtern angezeigt.

Clients können ein Element includes definieren, um die Erweiterungen auszuwählen, die für die Anzeigefunktion sichtbar sein sollen. Analog können sie ein Element excludes für Erweiterungen definieren, die für die Anzeigefunktion nicht sichtbar sein sollen. Clients können des Weiteren die Erweiterungen definieren, die nach Stammelementen (über die Methode "ITreeContentProvider.getElements())" durch das Attribut "isRoot") explizit abgefragt werden sollen. Falls für eines oder mehrere Elemente contentExtension der Wert für "isRoot" in einer Anweisung includes auf "true" gesetzt ist, werden nur diese Erweiterungen nach Stammelementen abgefragt. Das Attribut "isRoot" hat auf Ausschlüsse keine Auswirkung.

Für eine Anzeigefunktion können mehrere Elemente "viewerContentBindings" definiert sein. Das endgültige Verhalten wird durch eine Zusammenfassung ihrer Anweisungen "includes" und "excludes" erstellt.



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

<!ATTLIST viewerActionBinding

viewerId CDATA #REQUIRED>

Clients müssen definieren, welche Aktionsprovider für ihre Anzeigefunktion sichtbar sein sollen. Clients können ein Element includes definieren, um die für die Anzeigefunktion sichtbaren Erweiterungen auszuwählen. Analog kann ein Element excludes für Erweiterungen definiert werden, die für die Anzeigefunktion nicht sichtbar sein sollen.

Für eine Anzeigefunktion können mehrere Elemente viewerActionBindings definiert sein. Das endgültige Verhalten wird durch eine Zusammenfassung ihrer Anweisungen includes und excludes erstellt.

Bei Definitionen von actionProvider, die nicht in einer übergeordneten Definition von navigatorContent verschachtelt sind, können Clients eine angepasste ID angeben. Falls Clients keine ID angeben, wird für die ID standardmäßig der Wert "org.eclipse.ui.navigator.actionProvider.X" verwendet. Clients, die Elemente actionProvider ohne bestimmte IDs übernehmen wollen, müssen für die Standard-ID ein Element viewerActionBinding definieren. Im Abschnitt mit den Beispielen erfahren Sie, wie Sie hierzu vorgehen müssen.



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

Definiert eine Reihe von Mustern, die bei der Suche nach Inhaltserweiterungen für die mit dem Attribut "viewerId" angegebene Anzeigefunktion berücksichtigt werden sollen. Wenn sich die Anweisungen "includes" und "excludes" überschneiden, hat die Anweisung "includes" Vorrang.



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

Definiert eine Reihe von Mustern, die bei der Suche nach Inhaltserweiterungen für die mit dem Attribut "viewerId" angegebene Anzeigefunktion ausgeschlossen werden sollen. Wenn sich die Anweisungen "includes" und "excludes" überschneiden, hat die Anweisung "includes" Vorrang.



<!ELEMENT contentExtension EMPTY>

<!ATTLIST contentExtension

pattern CDATA #REQUIRED

isRoot  (true | false) >

Gibt die ID (oder das passende Muster) einer Inhaltserweiterung an, die durch die Methode ITreeContentProvider.getElements() oder ITreeContentProvider.getChildren() nach dem Stammelement der Anzeigefunktion oder eines allgemeinen Filters abgefragt werden soll, das für den Benutzer im Dialog "Verfügbare Anpassungen" verfügbar sein soll.

Mit dem Attribut "isRoot" können Clients bestimmte Stammerweiterungen für das Überschreiben der Erweiterungen angeben, die andernfalls für das Eingabeelement der Anzeigefunktion aktiviert wären (basierend auf dem entsprechenden Ausdruck triggerPoints für das Eingabeelement der Anzeigefunktion).

Weitere Informationen enthält die Dokumentation über das Element viewerContentBinding.



<!ELEMENT actionExtension EMPTY>

<!ATTLIST actionExtension

pattern CDATA #REQUIRED>

Gibt die Aktionserweiterung an, die Gelegenheit erhalten soll, das Kontextmenü und die Aktionsleisten zu ergänzen.

Weitere Informationen enthält die Dokumentation über das Element viewerActionBinding.



<!ELEMENT popupMenu (insertionPoint*)>

<!ATTLIST popupMenu

id                          CDATA #IMPLIED

allowsPlatformContributions (true | false) >

Ein Element "popupMenu" kann nur dann definiert werden, wenn das Attribut "popupMenuId" des Elements viewer nicht angegeben ist.

Mit dem Element popupMenu kann das Kontextmenü, das der Anzeigefunktion zugeordnet ist, weiter angepasst werden. Damit die Optionen korrekt angewendet werden, muss ein Exemplar der Anzeigefunktion eine Delegierung an eine Klasse org.eclipse.ui.navigator.NavigatorActionService vornehmen, die sich wie eine normale Klasse org.eclipse.ui.ActionGroup verhält. Weitere Informationen dazu, wie Sie diese Funktionalität nutzen können, enthält die Dokumentation über diese API-Klasse. Clients, die ein Exemplar von org.eclipse.ui.navigator.CommonNavigator einsetzen, müssen keine weiteren Aktionen ausführen.

Ein Element popupMenu deklariert eines oder mehrere Elemente insertionPoint, mit deren Hilfe die entsprechenden Ergänzungen in einer aussagekräftigen und benutzerfreundlicheren konsistenten Liste bereitgestellt werden.
Falls Clients nur das Attribut "popupMenuId" des Elements viewer angeben, wird vom Kontextmenü für die Elemente insertionPoints standardmäßig die folgende Liste in der angegebenen Reihenfolge verwendet:

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


Clients, die über das Programm auf diese Werte verweisen wollen, können die entsprechenden Konstanten in org.eclipse.ui.navigator.ICommonMenuConstants verwenden.

Bei Clients, deren Menüs angepasst werden sollen, ist es sinnvoll, ausgehend von dieser Liste Einfügemarken nach Bedarf hinzuzufügen oder zu entfernen. Außerdem ist es sinnvoll, das Muster zu befolgen, demgemäß jeder Gruppenname mit "group" beginnt.

Falls das Element popupMenu angegeben ist und KEINE untergeordneten Elemente insertionPoint enthält, enthält das Kontextmenü keine publizierten Einfügemarken. Programmgestützte Clients können natürlich dennoch eigene Einfügemarken nach Bedarf hinzufügen. Clients, die Anzeigefunktionen definieren, sollten ihre Einfügemarken aus Dokumentationszwecken und im Hinblick auf eine Eindeutigkeit für nachgeordnete Erweiterungen ihrer Anzeigefunktionen/Navigatoren publizieren oder explizit dokumentieren, welche Einfügemarken für APIs gedacht sind und welche Einfügemarken der internen Verwendung vorbehalten sind.



<!ELEMENT insertionPoint EMPTY>

<!ATTLIST insertionPoint

name      CDATA #REQUIRED

separator (true | false) >

Definiert eine Einfügemarke für das Kontextmenü. Enthält den Namen der Marke, auf den die Clients verweisen können. Außerdem ist angegeben, ob die Einfügemarke als Trennlinie oder als Gruppenmarke dargestellt werden soll.



<!ELEMENT options (property+)>

Stellt Optionen bereit, mit denen die Darstellung der Anzeigefunktion für den Benutzer angepasst werden kann. Die verfügbaren Eigenschaften sind in den Angaben zu org.eclipse.ui.navigator.INavigatorViewerDescriptor aufgeführt.



<!ELEMENT property EMPTY>

<!ATTLIST property

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Stellt ein Paar mit dem Format "name=wert" bereit. Der Wert wird der Anzeigefunktion unverändert zur Verfügung gestellt (leere Zeichenfolgen werden somit als leere Zeichenfolgen weitergegeben). Die verfügbaren Eigenschaften sind zusammen mit Beschreibungen in den Angaben zu org.eclipse.ui.navigator.INavigatorViewerDescriptor aufgeführt.



<!ELEMENT dragAssistant EMPTY>

<!ATTLIST dragAssistant

class    CDATA #REQUIRED

viewerId CDATA #REQUIRED>

Ein Assistent für Ziehen und Übergeben stellt einen unproblematischen Anbindungspunkt dar, mit dem zusätzliche Übertragungstypen und Logik zum Festlegen der zu ziehenden Daten bereitgestellt werden können. Dieses Element ist nicht erforderlich, weil die Basisfassung von org.eclipse.ui.navigator.CommonViewer einen Typ org.eclipse.jface.util.LocalSelectionTransfer bereitstellt.

Clients sollten diese Erweiterung nur in Lightweight-Plug-ins definieren, die Abhängigkeitsstrukturen mit wenigen Verzweigungen enthalten. Die Assistenten für das Ziehen müssen bei der Erstellung der Anzeigefunktion ebenfalls geladen werden, was das Laden der betreffenden Plug-ins verursacht.



Die folgenden Beispiele konfigurieren die Kontextmenü-ID für eine Anzeigefunktion.


   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer id=

"org.eclipse.testViewer"

popupMenuId=

"org.eclipse.testViewer#PopupMenu"

/>

</extension>

Da das untergeordnete Element popupMenu der Anzeigefunktion im obigen Beispiel nicht verwendet wird, wird die Standardgruppe der Elemente insertionPoints verwendet. Diese Gruppe ist folgendermaßen definiert (weitere Informationen finden Sie in der Dokumentation über das Element 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"

Das folgende Beispiel zeigt die Konfiguration einer Anzeigefunktion, die angepasste Elemente popupMenu/insertionPoint deklariert, die Objekt- und Anzeigefunktionsergänzungen jedoch mit dem Attribut "allowsPlatformContributions" einschränkt. Clients können eine Ergänzung für das definierte Menü nur über die Objekte org.eclipse.ui.navigator.CommonActionProvider bereitstellen, die für die Anzeigefunktion definiert sind (entweder auf höchster Ebene oder durch die Zuordnung zu Inhaltserweiterungen).

Bitte beachten Sie, dass eine gleichzeitige Angabe des Attributs "popupMenuId" und des Elements popupMenu nicht möglich ist. Eine gültige Konfiguration kann eines, jedoch nicht beide Elemente enthalten.

   

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

Das folgende Beispiel deklariert, dass 1 Inhaltserweiterung (mit der ID "org.eclipse.ui.navigator.resourceContent") an eine Anzeigefunktion gebunden ist, deren ID mit "org.eclipse.ui.navigator.resourceContent" übereinstimmt. (Im Beispiel sind die IDs der Inhaltserweiterung und der Anzeigefunktion identisch, was allerdings nicht erforderlich ist.) Außerdem werden alle Inhaltserweiterungen, deren ID mit "org.eclipse.ui.navigator.tests" beginnt, ignoriert.

   

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

Das folgende Beispiel deklariert ein Element viewerActionBinding für alle Elemente actionProvider (nicht unter einer Erweiterung navigatorContent verschachtelt), die mit dem regulären Ausdruck "org.acme.actions.*", jedoch nicht mit "org.acme.actions.tests.*" übereinstimmen. Dieser Ausdruck macht alle Elemente actionProvider, deren ID mit "org.acme.actions.", jedoch nicht mit "org.acme.actions.tests." beginnt, für die Anzeigefunktion mit der ID "org.acme.viewer" sichtbar. Die Elemente viewerActionBinding werden natürlich nur auf Elemente actionProvider angewendet, die nicht unter einem Element navigatorContent verschachtelt sind. Die Sichtbarkeit von verschachtelten Elementen actionProvider wird durch die Elemente viewerContentBinding für das übergeordnete Element navigatorContent gesteuert.

   

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

Das folgende Beispiel macht alle Elemente "actionProvider" ohne das Attribut "id" für die Anzeigefunktion "org.acme.viewer" sichtbar. Die Elemente actionProvider ohne Attribut "id" verwenden die Standard-ID "org.eclipse.ui.navigator.actionProvider.X". Die Elemente viewerActionBinding werden natürlich nur auf Elemente actionProvider angewendet, die nicht unter einem Element navigatorContent verschachtelt sind. Die Sichtbarkeit von verschachtelten Elementen actionProvider wird durch die Elemente viewerContentBinding für das übergeordnete Element navigatorContent gesteuert.

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewerActionBinding viewerId=

"org.acme.viewer"

>

<includes>

<actionExtension pattern=

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

/>

</includes>

</viewerActionBinding>

</extension>

Das folgende Beispiel stellt die verfügbaren Standardeigenschaften für die Anzeigefunktion dar.

   

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