Configuring the Common Navigator

This section defines the configuration at a conceptual level; some level of detail is omitted for clarity and conciseness. For the complete details see the extension point documentation or the Operational Topics section.

Viewer Configuration

As the CommonNavigator is a View, it is added using the org.eclipse.ui.views extension point. The CNF configuration aspects of the view instance are specified with a corresponding org.eclipse.ui.navigator.viewer extension point.

It is possible to use the CNF facilities for an arbitrary TreeViewer (??? could this be any StructuredViewer). In this case you still need to use this extension point, but it is used only to bind the CNF view information with the NCEs. You then programmatically (??? how) bind your Viewer with the NavigatorContentService.

The view may be associated with Navigator Content Extensions that define how its content is found and rendered. The entries here are used to look up NCEs, common filters and common wizards.

The view may also be associated with Action Providers that define code for programmatic updating and provision of actions or retargetable actions. The entries here are used to look up action providers.

The view may also be associated with Link Helpers that define the relationship between the selection in the view and the active editor.

Content extensions, common wizards, common filters, action providers and link helpers are bound to the view using an include/exclude mechanism and with the capability of pattern matching. This allows the actual content extensions (defined below) to be specified in a granular fashion such that views can select only those they actually need. The point of the exclude part of the mechanism is to exclude undesired items that were specified in the include statement. For example, the include statement could specify "com.mycompany.content.*" and exclude could remove the test content extensions by saying "com.mycompany.content.test.*".

A view is always associated with a popup menu. One important part of the popup menu configuration at this level is the insertion points, which are the locations where menu items can be added depending on when and where the menu is shown. By default, a standard set of insertion points is provided (described in the extension point documentation). However, you can can define your insertion points directly using popupMenus.

You can also direct the view to use a specific popup menu by id using popupMenuId, and you can indicate whether to ignore platform action contributions to the menu.

In the startup case, it is necessary to call some content extensions on the root node of the tree of the view in order to get the initial set of children. This set of content extensions is specified by setting the isRoot() property on the viewerContentBinding.

This defines:

  1. viewerContentBinding - bind a Content Extension or Common Filter specified with the org.eclipse.ui.navigator.navigatorContent/navigatorContent extension point;
  2. viewerActionBinding - bind action providers specified with the org.eclipse.ui.navigator.navigatorContent/actionProvider extension point;
  3. popupMenus - defines the insertion points (standard places where menu items can be added) for the popup menu associated with the viewer. Mutually exclusive with popupMenuId.
  4. popupMenuId - causes the view to use the menu defined by the org.eclipse.ui.popupMenus extension point. Mutually exclusive with popupMenus.
  5. dragAssistent - points to code that may provide extra transfer types to be used when starting a drag from the viewer.
  6. options - specifies options used to control the presentation of the view. For example these allow hiding of menus and buttons shown at the top of the view. Theses options are defined by INavigatorViewerDescriptor

Navigator Content Extension (NCE)

A navigator content extension, specified with org.eclipse.ui.navigator.navigatorContent/navigatorContent defines a named collection of attributes (content provider class, label provider class, icon, etc) to be enabled under certain conditions (typically in response to selection in the navigator). An example of a content extension is that for a resource. Content extensions are useful to describe other model objects that might be included in the view.

The definition of content extensions is separated from their association with a particular view instance allowing them to be shared and reused. Each content extension has an id, which is used to bind it with a view, and a display name which is presented to the user to allow the content extensions to be activated or deactivated by the user interface associated with the each view.

Content extensions may be active or not. This can be controlled by the user using the Customize View menu item of the navigator. Inactive content extensions are not considered when processing the view.

The content extension defines the following:

  1. triggerPoints - specifies the conditions when this content extension is enabled based on a given object. You can specify tests with core expressions on the object for which the content extension should be enabled.
  2. possibleChildren - like triggerPoints, but used for the case where the parent of the desired content extension is known, like in the drop case where we need to determine which content extension is required to handle the drop based on the drop target which is the parent of the eventual object that will be added to the tree.
  3. enablement - specifies an enablement that is both a triggerPoints and possibleChildren.
  4. labelProvider - an ILabelProvider provides the text to be shown in the view.
  5. contentProvider - anITreeContentProvider provides the means of getting the parent and child objects for the viewer. Other interfaces are possible, see the extension point documentation for these.
  6. descriptionProvider - IDescriptionProvider provides a description that is shown in the status bar.
  7. activeByDefault - indicates this content extension should be made active in the default configuration of the workbench (e.g. a new workspace).
  8. priority - used to determine which content extension to use in the event that multiple extensions are enabled (based on their enablement conditions).
  9. icon - used to associate the object with a specific icon.
  10. providesSavables - indicates the content provider provides saveables. If true the content provider must adapt to SavablesProvider.

Common Filter

A common filter, specified with org.eclipse.ui.navigator.navigatorContent/commonFilter defines a filter that is controllable by the user in the view. The filter definition contains an id, a description that describes the filter, a description that describes what is filtered out, and the conditions (using core expressions) that identify objects the filter suppresses.

The common filter is bound to the view using the viewerContentBinding element of the viewer configuration.

Common Wizard

A common filter, specified with org.eclipse.ui.navigator.navigatorContent/commonWizard defines wizard that is to be shown in the new, import, or export menu.

The common wizard is bound to the view using the viewerContentBinding element of the viewer configuration.

Action Providers

An action provider, specified with org.eclipse.ui.navigator.navigatorContent/actionProvider allows you to specify a class, subclassing org.eclipse.ui.navigator.CommonActionProvider that is invoked at right-click and selection time to allow you to contribute to the popup menu or to the action bars.

Action providers may be defined at the top level of the extension point, not associated with any content extension. These action providers are named and then bound to the CommonViewer using the org.eclipse.ui.navigator.viewer/viewerActionBinding.

Action providers may also be associated with a content extension, in which case they are active with the content extension. This is done by including the action provider inside of the org.eclipse.ui.navigator.navigatorContent/navigatorContent extension point.

Link Helpers

A link helper, specified with org.eclipse.ui.navigator.linkHelper allows you to control how the "Link with Editor" matches the selection in the navigator with an editor and matches an active editor with the selection in the navigator.