Common Viewer Configuration

Identifier:

org.eclipse.ui.navigator.viewer

Since:

3.2

Description:

The viewer element defines the configuration for a common viewer. The extension may provide a custom popup menu id, override whether the viewer provides link with editor support, provides a filter dialog, and/or provides an "Filters and Customization" dialog. In addition, nested configuration elements give full control over the structure and behavior of the popup context menu.

viewerContentBinding binds defined content extensions (through the navigatorContent extension point) to viewers. viewerContentBinding also binds a linkHelper extension point to a viewer. Any content extension bound to a viewer is described as visible. A content service (org.eclipse.ui.navigator.INavigatorContentService) will not return any extensions which are not visible for its viewer id.

Configuration Markup:

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

inheritBindingsFromViewer IDREF #IMPLIED

helpContext CDATA #IMPLIED>

Provides basic configuration to establish the characteristics of a viewer. Clients must also define an org.eclipse.ui.views extension to create the view part.

viewerId - The id of the common viewer. If the viewer is in a common navigator then the id must match the navigator's id defined in its org.eclipse.ui.views extension.
popupMenuId - The popupMenuId of the defined viewer. If not specified, the popupMenuId defaults to the id of the viewer. Clients may specify only the "popupMenuId" OR a popupMenu element, but not both. The default list of insertion points is declared in the documentation for the popupMenu element.
inheritBindingsFromViewer - Causes all of the action and content bindings from the specified viewer to be used by this viewer.
helpContext - The help context Id to be associated with the Control associated with the viewer.

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

<!ATTLIST viewerContentBinding

viewerId CDATA #REQUIRED>

Clients must define one or more viewerContentBinding elements to describe which content extensions, common filters, and link helpers are visible to the viewer. A content extension or common filter is visible if the id of the content extension or common filter matches an includes statement under a viewerContentBinding and is not excluded by an excludes statement. If a content extension or common filter is not visible to a viewer, then the extension will never be asked for content by a content service for that viewer or be presented to the user in the available filters dialog.

Clients may define an includes element to select which extensions are visible to the viewer, and similarly an excludes element for extensions that should not be made visible to the viewer. Clients may further define the extensions that should be explicitly queried for root elements (through ITreeContentProvider.getElements()) by the "isRoot" attribute. If one or more contentExtension elements have "isRoot" set to true within the includes statement, only those extensions will be queried for root elements. The "isRoot" attribute has no effect for exclusions.

A viewer may have multiple viewerContentBindings defined, and their includes/excludes statements will be aggregated to produce the final behavior.

viewerId - The id of the common viewer. If the viewer is in a common navigator then the id must match the navigator's id defined in its org.eclipse.ui.views extension.

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

<!ATTLIST viewerActionBinding

viewerId CDATA #REQUIRED>

Clients must define which action providers are visible to their viewer. Clients may define an includes element to select which extensions are visible to the viewer, and similarly an excludes element for extensions that should not be made visible to the viewer.

A viewer may have multiple viewerActionBindings defined, and their includes/excludes statements will be aggregated to produce the final behavior.

For actionProvider definitions which are not nested under a navigatorContent definition, clients may specify a custom id. If clients do not specify an id, the id defaults to "org.eclipse.ui.navigator.actionProvider.X". For clients that wish to pick up actionProviders with no specific id, clients must define a viewerActionBinding for the default id. See the examples section for how this is done.

viewerId - The id of the common viewer. If the viewer is in a common navigator then the id must match the navigator's id defined in its org.eclipse.ui.views extension.

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

Define a set of regular expressions that should be included when looking for content extensions for the viewer that matches the "viewerId" attribute. When the includes and excludes statements intersect, the excludes statement will be given precedence.

Note: these are regular expressions and not wildcards. So if you want to include something like com.mycompany.content*, the expression would be com\.mycompany\.content.*.

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

Define a set of regular expressions that should be excluded when looking for content extensions for the viewer that matches the "viewerId" attribute. When the includes and excludes statements intersect, the excludes statement will be given precedence. To be meaningful this will be a subset of the includes pattern.

Note: these are regular expressions and not wildcards. So if you want to include something like com.mycompany.content*, the expression would be com\.mycompany\.content.*.

<!ELEMENT contentExtension EMPTY>

<!ATTLIST contentExtension

pattern CDATA #REQUIRED

isRoot (true | false) >

Indicates the id (or matching pattern) of a content extension that should be queried by ITreeContentProvider.getElements() or ITreeContentProvider.getChildren() for the root of the viewer or a common filter that should be available to the user in the "Available Filters" dialog.

Clients may specify "isRoot" to select specific root extensions to override the extensions which would otherwise be enabled for the viewer input element (based on the matching triggerPoints expression for the viewer input element).

See the documentation for viewerContentBinding for more information.

pattern - Content extensions may be selected exactly by using their content extension id. Clients may also use a regular expression pattern to select any content extensions that have ids that match the pattern.
Patterns are regular expressions which match unique identifiers. Please see the Java(tm) Platform documentation for java.util.regex.Pattern for further details.
isRoot - A value of true indicates the content extension will provide root content, and override the default triggerPoints expressions defined in the bound content extensions for a given viewer.

<!ELEMENT actionExtension EMPTY>

<!ATTLIST actionExtension

pattern CDATA #REQUIRED>

Indicates that the action extension that should be given opportunities to contribute to the context menu and action bars.

See the documentation for viewerActionBinding for more information.

pattern - Content extensions may be selected exactly by using their content extension id. Clients may also use a regular expression pattern to select any content extensions that have ids that match the pattern.
Patterns are regular expressions which match unique identifiers. Please see the Java(tm) Platform documentation for java.util.regex.Pattern for further details.

<!ELEMENT popupMenu (insertionPoint*)>

<!ATTLIST popupMenu

id CDATA #IMPLIED

allowsPlatformContributions (true | false) >

A popupMenu element may only be defined if the "popupMenuId" attribute of the viewer element is not specified.

The popupMenu element allows further customization of the context menu associated with the viewer. For the options to be applied correctly, an instance of the viewer must delegate to a org.eclipse.ui.navigator.NavigatorActionService, which behaves like a normal org.eclipse.ui.ActionGroup. See the documentation for this API class for more information on exploiting this functionality. For clients that use an instance of org.eclipse.ui.navigator.CommonNavigator do not need to do any extra work.

A popupMenu declares one or more insertionPoints that will be used by contributors to organize their contributions into a meaningful, more user-friendly, consistent list.
If clients only specify the "popupMenuId" attribute of the viewer element, then the set of insertionPoints used by the context menu will default to the following list in the given order:


"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 that wish to refer to these values programmatically may use the corresponding constants in org.eclipse.ui.navigator.ICommonMenuConstants.

Clients that wish to customize their menus are encouraged to start with this list and add or remove insertion points as necessary. Clients are also encouraged to follow the pattern of beginning each group name with "group.".

If the popupMenu element is specified and contains NO insertionPoint children elements, then the context menu will have no published insertion points. Of course, programmatic clients are not restricted from adding their own insertion points as necessary. Clients defining viewers are encouraged to publish their insertion points for documentation purposes and clarity for downstream extensions to their viewers/navigators, or to explicitly document which insertion points are considered API and which are considered internal.

id - The id of the menu. Has the same function as the "popupMenuId" attribute of viewer, but if a popupMenu nested element is used, you must use this "popupMenuId" attribute and NOT specify the "popupMenuId" of viewer.
allowsPlatformContributions - A value of true will register the declared popupMenu (by id) for object or viewer contributions as declared by the org.eclipse.ui.popupMenus extension point. A value of false will restrict the popupMenu to programmatic contributions as declared by org.eclipse.ui.navigator.CommonActionProviders (see org.eclipse.ui.navigator.navigatorContent/actionProvider and org.eclipse.ui.navigator.navigatorContent/navigatorContent/actionProvider).

<!ELEMENT insertionPoint EMPTY>

<!ATTLIST insertionPoint

name CDATA #REQUIRED

separator (true | false) >

Defines an insertion point for the context menu. Indcludes the name of the point for clients to refer to, and whether the insertion point should be rendered as a separator or a group marker.

name - Indicates the name of the insertion point. Clients will use the name to refer to the insertion point as part of a menu path when providing either programmatic contributions via org.eclipse.ui.navigator.CommonActionProvider or declarative contributions via the org.eclipse.ui.popupMenus extension point.
separator - A value of true will cause the insertion point to be represented as a bar in the menu. This allows clients to visually group items in the context menu, based on their relevance to the user. By default, the value is false.

<!ELEMENT options (property+)>

Provide options to the viewer to custom how it is presented to the user. See org.eclipse.ui.navigator.INavigatorViewerDescriptor for the available properties.

<!ELEMENT property EMPTY>

<!ATTLIST property

name CDATA #REQUIRED

value CDATA #REQUIRED>

Provide a name=value pair. The value will be provided as-is to the viewer (so empty strings will be propagated as empty strings). See org.eclipse.ui.navigator.INavigatorViewerDescriptor for the available properties and their descriptions.

name -
value -

<!ELEMENT dragAssistant EMPTY>

<!ATTLIST dragAssistant

class CDATA #REQUIRED

viewerId IDREF #REQUIRED>

A Drag and Drop assistant provides lightweight hook to supply extra transfer types and logic to set the drag data. This element is not required as the basic org.eclipse.ui.navigator.CommonViewer provides a org.eclipse.jface.util.LocalSelectionTransfer type.

Clients should only define this extension in lightweight plugins with shallow dependency trees. The drag assistants must be loaded up front when the viewer is created, which will force the load of affected plugins.

class - Provide an implementation of org.eclipse.ui.navigator.CommonDragAdapterAssistant.
viewerId - Associate this drag assistant with a particular viewer id.

Examples:

The following example configures the popup menu id for a viewer.



   <extension
         point="org.eclipse.ui.navigator.viewer">
      <viewer 
         id="org.eclipse.testViewer" 
         popupMenuId="org.eclipse.testViewer#PopupMenu"/>
   </extension>

Since the popupMenu child element of viewer is not used in the above example, the default set of insertionPoints will be used. This set is defined as follows. See the documentation for the popupMenu element for more information.


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

The following example demonstrates a viewer configuration which declares custom popupMenu/insertionPoints, but restricts object and viewer contributions with the "allowsPlatformContributions" attribute. Clients may only contribute to the defined menu via org.eclipse.ui.navigator.CommonActionProviders declared for the viewer (either top-level or associated with content extensions).

Note that the "popupMenuId" attribute is not concurrently specified with the popupMenu element. Only one or the other, but not both, is a valid configuration.


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

The following example declares that one content extension (id: "org.eclipse.ui.navigator.resourceContent") is bound to a viewer matching the id "org.eclipse.ui.navigator.resourceContent". (In this example the content extension and viewer ids match, but this is not required.)


   <extension
         point="org.eclipse.ui.navigator.viewer">
       <viewerContentBinding 
             viewerId="org.eclipse.ui.navigator.resourceContent">
            <includes>
                <contentExtension pattern="org.eclipse.ui.navigator.resourceContent" />
            </includes>
       </viewerContentBinding>
   </extension>

The following example declares a viewerActionBinding for all actionProviders (not nested under a navigatorContent extension) that match the regular expression "org.acme.actions.*" but not "org.acme.actions.tests.*". This expression will make any actionProvider whose id begins with "org.acme.actions." but not "org.acme.actions.tests." visible to the viewer with the id "org.acme.viewer". Of course, the viewerActionBindings only apply to actionProvider elements that are not nested under a navigatorContent element. The visibility of nested actionProvider elements is controlled by viewerContentBindings for the enclosing navigatorContent element.


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

The following example makes any actionProvider with no "id" attribute visible to the viewer "org.acme.viewer". The actionProviders with no "id" attribute have a default id of "org.eclipse.ui.navigator.actionProvider.X". Of course, the viewerActionBindings only apply to actionProvider elements that are not nested under a navigatorContent element. The visibility of nested actionProvider elements is controlled by viewerContentBindings for the enclosing navigatorContent element.


   <extension
         point="org.eclipse.ui.navigator.viewer">
       <viewerActionBinding 
             viewerId="org.acme.viewer">
            <includes>
                <actionExtension pattern="org.eclipse.ui.navigator.actionProvider.*" />
            </includes> 
       </viewerActionBinding>
   </extension>

The following example demonstrates the standard properties available to the viewer.


   <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 "Filters and Customization" 
                 dialog (available from the "Filters" action -->
            <property
                  name="org.eclipse.ui.navigator.hideAvailableExtensionsTab"
                  value="true"/>
            <!-- Hide the "Filters and Customization" 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>

Copyright (c) 2002, 2009 IBM Corporation and others.
This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-v20.html/ SPDX-License-Identifier: EPL-2.0