org.netbeans.spi.navigator/1 1.27.1

Navigator API


Navigator API


Navigator API is good for clients (module writers) that want to show some structure or outline of their document in dedicated window, allowing end user fast navigation and control over the document.

API allows its clients to plug in their Swing based views easily, which then will be automatically shown in specialized Navigator UI.

org.netbeans.spi.navigator.NavigatorPanel org.netbeans.spi.navigator.NavigatorHandler

What is New (see all changes)?

Use Cases

Basic Usage Steps
In order to plug in a view into Navigator UI for certain document (data) type, module writers need to write a NavigatorPanel implementation marked with @Registration.

Writing NavigatorPanel implementation

Implementing NavigatorPanel interface is easy, you can copy from template basic implementation

Advices on important part of panel implementation:

Registering NavigatorPanel impl

Declarative registration of your NavigatorPanel impl connects this implementation with specific content type, which is type of the document, expressed in mime-type syntax, for example 'text/x-java' for java sources. Infrastructure will automatically load and show your NavigatorPanel impl in UI, when currently activated Node is backed by primary FileObject whose FileObject.getMimeType() equals to content type specified in your registering annotation (see more options below).

Advanced Content Registration - Linking to Node's Lookup

There may be situations where linking between your Navigator view and activated Node's primary FileObject is not enough or not possible at all. This simply happens when the data you want to represent in Navigator are not accessible through primary FileObject or DataObject. Usual example is Multiview environment, where more views of one document exists.

The solution is to bind content of your Navigator view directly to your TopComponent. Then, whenever your TopComponent gets activated in the system, Navigator UI will show th content you connected to it.

Steps to do:
Programmatic activation of NavigatorPanel

Programmatic activation of specific navigator panel activates and shows navigator panel in navigation area, as if user had selected the panel manually. API clients are expected to use programmatic activation to activate/select preferred panel from a set of available panels.

Example: Several TopComponents in multiview arrangement, TopComponentA and TopComponentB. Both components provide the same NavigatorLookupHint impl, which is recognized by two providers NavigatorPanelA and NavigatorPanelB. Now when TopComponentA becomes activated (has a focus), it's desirable to select/show NavigatorPanelA from navigator panels. On the other side, when TopComponentB is activated, NavigatorPanelB should be activated automatically.

Steps to do to activate panel programmatically:
Setting activated node of Navigator window

Sometimes clients need to alter activated Nodes of Navigator window, to better represent Navigator area content within the whole application. See TopComponent.getActivatedNodes() and TopComponent.Registry.html#getActivatedNodes() to find out what activated nodes of TopComponent and whole system mean.

Use Case Example: NavigatorPanel implementation shows list or tree of some Nodes in Navigator area. When user selects a Node in the list or tree, it is desirable to show selected Node's properties in Properties window and enable proper actions in main menu. Exactly this can be done by presenting Node selected in the list/tree as activated Node of Navigator window.

Steps to specify activated Nodes of Navigator window:
Adding UndoRedo support to the navigation view

Some complex navigation views need support for undoing and redoing edit changes done either directly in the view or in document which the view is representing.

Steps to support undo and redo in navigation view:
Removing active Node/DataObject related NavigatorPanels from Navigator window

In certain situations it's not desired to show NavigatorPanel implementations related to DataObject of active Node in Navigator window. Typically you need to have active Node of some type, so that actions in the system works properly. But you don't want to show NavigatorPanels that "come" with such active Node.

Steps to remove such NavigatorPanels:
Integration of Explorer view into Navigator

Explorer views comes handy when showing Nodes in varienty of situations and it is just natural to be able to integrate them into Navigator window. Working with explorer views is described at ExplorerUtils javadoc. Integration with Navigator is easy and there are only subtle differencies from integration into TopComponent.

Steps to integrate some kind of Explorer View into Navigator:

Exported Interfaces

This table lists all of the module exported APIs with defined stability classifications. It is generated based on answers to questions about the architecture of the module. Read them all...
Group of java interfaces
Interface NameIn/OutStabilitySpecified in What Document?
org.netbeans.spi.navigator.NavigatorHandlerExportedUnder Development

Group of lookup interfaces
Interface NameIn/OutStabilitySpecified in What Document?
activated_nodeExportedUnder Development

Navigator listen to system activated node changes and sets activated node for Navigator top component accordingly. Local activated node is set from system activated node if any provider agrees to display content for data object behind the node. Navigator relies on default lookup mechanism of TopComponent to populate its activated node. Currently it means that if node backed by JavaDataObject is activated node in the system, it is also activated node for Navigator's top component. So main menu actions like Compile File, Move Class etc. work as usual when Navigator window is active. Also, lookup of currently selected Node is searched for NavigatorPanel SPI instances.

Implementation Details

Where are the sources for the module?

The sources for the module are in the NetBeans Mercurial repositories.

What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?


Read more about the implementation in the answers to architecture questions.

org.netbeans.spi.navigator/1 1.27.1

Built on June 6 2013.  |  Portions Copyright 1997-2013 Oracle. All rights reserved.