Common Navigator Framework
A JFace Viewer provides the user with a view of objects using a single
content provider, label provider, sorter and filter. The Common
Navigator Framework (CNF) extends this idea by allowing a single view to
dynamically use multiple and unrelated sets of content providers, label
providers, sorters and filters. These can be activated in the view
depending on declarative expressions or using API calls. The CNF
implemented by the
org.eclipse.ui.navigator
plugin.
The CNF uses the idea of Navigator Content Extensions
(NCE) which can refer to a content provider, label provider, sorter, or
drag adaptor (note that filters are configured separately). An NCE has
associated expressions that tell it when it is active. NCEs are also
presented to the user in the view context menu so that user can turn
them on or off in order to show the view in different ways. Examples of
NCEs are a resource content extension that controls how resources are
presented and Java content extension that shows Java projects. In the
IDE's Project Explorer, you can turn off the Java content extension
getting a pure resource view of the workspace.
By using the NCEs it's possible to include different model
objects directly in the view. These model objects might be related in a
cascading fashion. For example a resource object (an IFile
)
might refer to a Java class object. This Java class object can be
presented directly in the view by defining an NCE. The Java class object
can have children (representing methods, fields, etc) all of which
appear in the view. You can then add another NCE to display model
objects related to the Java (or resource object) that display content
related to a Java Server Page object. This can all be done without the
"lower level" NCEs (resources, Java) being aware of the existence of the
"outer" NCEs (JSP). Further, it's possible for outer NCEs to override by
suppressing processing associated with lower level NCEs according to
their requirements. And even further, it's possible (using the
pipelining mechanism) for even level in this cascaded set of NCEs to
arrange the presentation of the objects according to their
specifications, moving, adding, or suppressing objects as necessary.
The CNF has depends only on org.eclipse.ui
and is
therefore suitable for use both within the IDE and in an RCP
application.
The CNF is highly configurable and many of its components can be
used separately (though this is not the typical case). For example, it's
possible use the service that manages content extensions with a viewer
other than the standard CommonViewer
.
The CNF documentation has the following sections:
Major Components of the Common Navigator Framework
The CNF has the following major parts:
-
View Part -
CommonNavigator
.
-
Viewer -
CommonViewer
the implementation of a viewer that is contained in the above view
part. You can also use the CNF with your own viewer that can be
displayed anywhere.
-
Navigator Content Extensions -
org.eclipse.ui.navigator.navigatorContent
This extension point is where you configure the collections of content
you want to make visible.
-
Navigator Viewer -
org.eclipse.ui.navigator.navigatorContent
This extension point is used to declare the relationship between the
NCEs and a particular viewer. Regular expressions may be used here to
allow a viewer to dynamically detect NCEs that it does not know about
beforehand. visible.
-
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 is configured using these
definitions.
Navigators - Where the CNF Fits
There are currently 3 major navigators in the Eclipse IDE.
-
Project Explorer - This is an instance of the
CommonNavigator that is provided by the
org.eclipse.ui.navigator.resources
plugin. It provides a view of the
workspace and has a large number of NCEs contributed for resources,
Java, C, Web Tools, Data Tools, PHP, etc.
-
Package Explorer - Provided by the Java Development
Tools (JDT) UI project, this provides a view of Java classes for the
workspace. Generally speaking, the presentation of the Package Explorer
and Project Explorer for Java objects is substantially similar. The JDT
is not used for projects beyond Java.
-
Navigator - This view is an implementation of the now
deprecated (as of 3.5)
org.eclipse.ui.views.navigator
ResourceNavigator class provided in the
org.eclipse.ui.ide
plugin. It shows only the workspace resources and does not support
extensibility to show other content. In a future release, the Navigator
view will be provided by an implementation of the CommonNavigator.
We also provide
instructions for migration from the ResourceNavigator to the CNF.
The only navigator intended for general purpose client use if the
CNF, which can be used either by adding NCEs visable in the Project
Explorer (if developing an IDE plugin), or using a separate instance of
the CommonNavigator as a view.
Navigator Content Extensions (NCE)
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
navigator contentextension
.
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 helps
to determine the order of invocation of the NCEs. It's possible that
more than one content extension may be enabled for a given object and
situation. 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
Though the CNF provides a mechanism to work with actions, it is
recommended that you instead use the
Workbench Commands
instead of actions.
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.