Common Navigator Framework

The Common Navigator Framework (CNF) provides a general purpose configurable navigator view which can be shared by many applications working with the same set of resources or other objects, presenting a integrated view to the end user. It is implemented by the org.eclipse.ui.navigator plugin.

The main part of the CNF is the CommonNavigator which is a IViewPart implementation. The Common Navigator instance in the IDE workbench is called the Project Explorer. Note that the Package Explorer in the IDE is part of the org.eclipse.ui.views.navigator package and is unrelated to the Common Navigator.

With the CNF you can define one or more view parts and associate each view part with content extensions, filters, wizards, and sets of actions. Each view instance is defined by an extension. Each content extension, filter, wizard and action provider is defined by another extension which allows these to be shared among the view part(s).

Components of the Common Navigator Framework

The CNF has the following major parts:

  1. View Part - CommonNavigator .
  2. Viewer -CommonViewer the implementation of a viewer that is contained in the above view part.
  3. Content Service - INavigatorContentService a service that manages content extensions and allows them to be discovered based on objects associated with a viewer. Most users do not interact directly with the Content Service, but it is possible to use it independently from the common navigator view part.

Content Extensions

The CNF allows you to include not only resources but any type of object. One typical use case is that of a resource (consider a Java file for example) which has several subordinate objects presented as tree nodes representing aspects of the class like imports, methods, etc. The CommonViewer (portion of the Common Navigator) will include the IResource object representing the Java file, and then as its children an object for each import, method, etc. The mechanism for defining this is a content extension.

Each content extension also provides a means of associating objects with appropriate icons, labels and menu items.

Content extensions are invoked based on an enablement expression which is defined using core expressions in the extension point. Enablement expressions are commonly defined by sensing the class of an object.

A priority may be associated with a content extension which indicates the category of importance of the extension related to other extensions. It's possible that more than one content extension may be enabled for a given object and situation. In this case the priority mechanism is used to select the one extension to use. Priorities are defined with words like "high" or "normal". A high priority would be associated with an extension that defines the primary UI for frequently manipulating an object. A low priority would be given to relatively infrequent utility sorts of UI.

Content extensions may be activated and deactivated for a given view part in the UI using the Customize View menu item in the header menu associated with the view part. Common filters are also may also be activated and deactivated the same way.

Common Filters

Filters allow the user to specify which resources or objects to exclude. Like content extensions, filters may be specified centrally and shared.

Common Wizards

References to wizards for new/import/export may be defined. These are included in the appropriate popup menu based on the enablement.

Action Providers

Action providers provide a means to configure the retargetable actions and programmatically configure the popup menu in a CNF viewer. These are useful for when you must perform a computation to determine which items are added to the menu, or to adjust the retargetable actions to ensure that the user keystrokes are handled properly (like for Cut/Copy/Paste).

Drag and Drop Support

A drop assistant may be associated with a content extension to provide handling of additional (non-standard) transfer types or validation in the event of a drop.

Link with Editor Support

The link helper extension point provides a flexible mechanism of determining the appropriate selection in the navigator when an editor is activated. Conversely, it also provides the appropriate editor to be activated when the selection changes.

Built in Resource Support

Resources are one of the main types of objects managed by the CNF. To support this the org.eclipse.ui.navigator.resources plug-in provides all of the necessary definitions. The Project Explorer in the IDE is configured using these definitions.

Configuring the Common Navigator

Configuring the Common Navigator gives the overview of how the CNF is configured. For further details, see the extension point documentation:

Rich Client Platform Configuration Steps

The Common Navigator can be used in RCP applications to allow full access and manipulation of the resource workspace. This can be accomplished very quickly by using the Using the Common Navigator in RCP instructions.