Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.netbeans.spi.navigator/1 1.2.22
PREV NEXT | FRAMES NO FRAMES

# NetBeans Navigator API

See:
Description

Navigator API
org.netbeans.spi.navigator |

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.

Client's views are registered through declarative xml layers approach.

org.netbeans.spi.navigator.NavigatorPanel

### 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 complete following steps:

- Write NavigatorPanel implementation
- Register implementation class in xml layer

#### Writing NavigatorPanel implementation

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

Advices on important part of panel implementation:

- Instantiation: Your implementation of NavigatorPanel is instantied automatically by the system if you register it in a layer (described in next step). See detailed Instantiation rules to understand which kind of instantiation possibilities are on the plate.

- getComponent method: Simply create and return your UI representation of your data in Swing's JComponent envelope. Just be sure that you don't create new JComponent subclass per every call, as performance will suffer then.

- panelActivated and panelDeactivated methods wraps an 'active' life of your panel implementation. In panelActivated, grab your data from given Lookup, usually by looking up its asociated DataObject or FileObject to take data from. Also remember to attach listeners to lookup result, perhaps also to data itself and trigger UI update with new data. Code will typically look like this:

              /** JavaDataObject used as example, replace with your own data source */
              private static final Lookup.Template MY_DATA = new Lookup.Template(JavaDataObject.class);

              public void panelActivated (Lookup context) {
                  // lookup context and listen to result to get notified about context changes
                  curResult = context.lookup(MY_DATA);
                  curResult.addLookupListener(/** your LookupListener impl here*/);
                  Collection data = curResult.allInstances();
                  // ... compute view from data and trigger repaint
              }

  Do *not* perform any long computation in panelActivated directly, see below.
  In panelDeactivated, be sure to remove all listeners to context given to you in panelActivated.

- Long computation of content: What if rendering your Navigator view takes long time, more than several milliseconds? Right approach is to create and run new task using RequestProcessor techniques, each time when panelActivated call arrived or your listeners on data context got called.
  While computing, UI of Navigator view should show some please wait message.

#### Registering NavigatorPanel impl in a layer

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

Writing layer registration itself is easy, you can again copy from template layer Basic Navigator Registration Layer.

Additional important info:

- System looks up for navigator providers only in Navigator/Panels folder, nowhere else.

- Content type is specified as cascade of subdirectories under Navigator/Panels directory. Mime-type syntax is recommended and handy for specifying content type.
  It is not compulsory though, so if you need to make up a name for your content type, just go for it. (more 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:

- Choose your content type, could be either well known or arbitrary, say 'text/my-amazing-type' and do all basic steps described in above use case.

- Implement NavigatorLookupHint interface like this:

              class AmazingTypeLookupHint implements NavigatorLookupHint {
                  public String getContentType () {
                      return "text/my-amazing-type";
                  }
              }

- Alter your TopComponent to contain your NavigatorLookupHint implementation (AmazingTypeLookupHint in this case) in its lookup, returned from TopComponent.getLookup() method.

- Another option you have is to alter lookup of your `Node` subclass instead of directly altering lookup of your `TopComponent`. See Node.getLookup() method. Then Navigator will show your desired content whenever your `Node` subclass will be active in the system.
  However, keep in mind that this option is less preferred, because it only uses implementation detail knowledge that default implementation of `TopComponent.getLookup()` includes also results from lookup of asociated `Node`. So this approach will stop working if you change default behaviour of `TopComponent.getLookup()` method.

### 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 Name | In/Out | Stability | Specified in What Document?
org.netbeans.spi.navigator.NavigatorPanel | Exported | Stable |

##### Group of lookup interfaces

Interface Name | In/Out | Stability | Specified in What Document?
activated_node | Exported | Under 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 NetBeans CVS in core/navigator directory.

##### What do other modules need to do to declare a dependency on this one?

Just regular dependency in project metadata to code base name: org.netbeans.api.navigator

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.netbeans.spi.navigator/1 1.2.22
PREV NEXT | FRAMES NO FRAMES

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.