Introduction
The built-in FTreePlugin provides the navigation tree that appears on the left side of the JAS3 panel; such tree is meant to be the place where plugins interact with each other and make objects available to the user. Plugins can interact with the navigation tree in several ways:
...
- node's icon for the open/close, selected/unselected node's states
- the text appearing next to the icon; this is an alternative to the node's name (should this be used when sorting?)
- decide if the node is allowed to have children. If a node is allowed to have children any node will be able to add children to the existing node, otherwise no children will be allowed (when a node is added to a node that does not allow it an exception is thrown, how can it be cought?)
- define the result of a double click action on the node
- define the result of a single click action in the node
- modify the default popup menu
- assign an object to the node that can be accessed by other plugins
- provide a tooltip message to be displayed when the mouse is hovering over the node
- provide a status message to be displayed a the bottom left corner of the JAS3 panel when the node is selected
- define what objects can be transferred in a drag and drop operation
- provide a command processor to define a set of commands to appear on the toolbar; these commands are active when the given node is selected
- decide if the text next to the icon can be edited
- define the selection behavior when one or more nodes are selected
- provide the node's internal structure (see the structure provider below)
...
We will first provide an overview of the main features of the navigation tree; we will then provide a set of examples #examples to show how plugins interact with the navigation tree.
Overview of the main features
We provide here an overview of the main features of the navigation tree. For a detailed list of all its interfaces and classes and their methods please refer to the APIs.
Events and Notifications
Two possible communication channels are available between the tree and the plugins: notifications and events. Notifications are passed to the tree by plugins to inform the tree of what should happen to its structure, while events are sent by the node's tree to the registered listeners when the node's substructure has changed.
* Notifications
A plugin should use notifications when the tree structure is to be changed. Such structural changes involve
o adding and removing nodes
o moving nodes from one folder to another (this operation preserves the original node's information. It is different from removing the node form the original path, adding it back again. This last operation does not preserve the information of the original node as it is lost when the node is removed.)
o renaming a node
o repaint a node or its entire substructure when either icons or text have changed
o changing the current selection by selecting or unselecting a given path
Notifications can be sent to the tree from any thread. Internally they are queued and executed asynchronously on the event dispatching thread. This is to avoid user's programs or scripts having to wait for the GUI to update.
* Events
Events are sent by the nodes on the tree to their registered listeners to communicate one of the following changes to the node's substructure:
o a sub-node has been added or removed
o a sub-node has been changed in the way it appears
o the substructure of a node has changed
...
The following list shows which events are fired when a notification is processed by the tree
o a node added event is fired every time a node added notification is processed. The parent node is the source of the event and the added node is passed along with the event. If, as a result of a node added notification, more nodes are added to the tree, an event will be fired for each of the added nodes
o a node removed event is fired every time a node removed notification is processed. The parent node is the source of the event with the deleted node being part of the event.
o a node changed event is fired when
+ a node renamed notification is process. In this case the renamed node is the source of the event.
+ a notification that repainted a single node has been processed. The repainted node is the source of the event.
o a node structure changed event is fired when
+ a node's substructure has been repainted by a corresponding notification. The root node of the substructure that has been repainted is the source of the event.
+ a node structure change notification has been processed. Even in this case the root node of the substructure that has changed is the source of the event.
+ as a consequence of a notification that expanded a node. The expanded node is the source of the event.
Cached information
The following information is cached in the nodes after the first time:
- if the node allows children
- the node's name, i.e. the final part of the node's path
- the node's type
- if the node has already checked for its children
- the node's structure provider
...
Sorting
Nodes can be sorted with an extensible set of sorting algorithms. The following sorting algorithms are provided:
...
The nodes are sorted when added to the tree based on the selected combination of sorting algorithms. The default ordering is the one given by the structure provider for the given set of nodes.
Structure Provider
Via the structure provider it is possible to control the structure or a node, i.e. the list of its children and their order. The structure provider for a given node basically holds the list of the node's children. This list is used to display the node's children in the tree in the order in which they are provided. When a node is added the structure provider is asked to add the node to the list of children; the structure provider can decide not to add the children to its list (should this be? should an exception be thrown?). Similarly when a node is removed from its parent, the parent's structure provider is asked decide whether to remove that node from its list or not.
Adding children on demand (checkForChildren)
A plugin can add nodes to the tree at any time. For example it can add all the nodes required by its needs at once, in the initialization process. If there are several nodes involved in this operation and, especially, if the plugin is accessing the node's information over a network, adding all the nodes during initialization could be a rather time consuming operation. To avoid this waste of time the plugin can alternatively decide to add the nodes on demand, i.e. when they are really needed.
This can be done through the node's adapter. When the tree really needs the information regarding the children of a given node (for example when the node is expanded), it asks all the adapters registered for the give node to check for the node's children. At this point the plugin can add the required nodes, just when they are needed. This information will be required by the tree only once (should it be possible, would it be useful to reset this, allowing check for children to be invoked again?).
The tree provider
The FTreeProvider interface is the access point for the user to the JAS3 navigation tree: it allows to access existing trees, create new ones and access the node adapter registry with which it is possible to register node adapters that define the behavior of nodes on the tree. To tree provider can be obtained through the JAS3 lookup table as shown in the following line:
FTreeProvider treeProvider = (FTreeProvider) getApplication().getLookup().lookup( FTreeProvider.class );
Examples
The following examples show how to interact with the navigation tree; the code provided in each of them can be compiled in run within JAS3.
...