FTreePlugin Documentation

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:

    The nodes on the tree have the following main properties:

    By default nodes in the tree are pretty boring objects:

To make nodes more interesting plugins have to register adapters with the tree. Adapters are assigned to nodes based on the node's type; they are used to define the node's appearance and behavior. Through the adapter it is possible to define the following features:

    When more than one adapter is compatible with a given node's type, they are arranged by the adapter's priority; please refer to the FTreeNodeAdapter's API for a detailed description on how the priority is used for each of the features above.

    We will first provide an overview of the main features of the navigation tree; we will then provide a set of 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.

Cached information

    The following information is cached in the nodes after the first time:

(Should it be possible to reset the cached information? For what?)

Sorting

    Nodes can be sorted with an extensible set of sorting algorithms. The following sorting algorithms are provided:

    A plugin can add other sorting algorithms to the set of provided ones; these can be applied alone or in combination with the ones above (for example it is possible to sort the folder first and also apply the alphabetical sorting). The sorting algorithm can be selected by right clicking on any node selecting the "sorting..." menu item; the sorting can be applied to the whole tree or to individual folders, recursively or not.

    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.

Adding and removing FTreeNodes

    To add a node to the FTree it is necessary to send an FTreeNodeAddedNotification to the tree specifying the type of the node and its location within the tree (optionally it is possible to provide the object contained in the node). The path can either be a String in the standard unix notation (directories separated by "/") or an FTreePath. The type defines the behavior of the node; two default type are provided: FTreeLeafNode for leaves in the tree, and FTreeFolderNode for folders.

tree.treeChanged( new FTreeNodeAddedNotification(this, "/baseDir/subDir", FTreeLeafNode.class) );

When adding a node to the tree, intermediate folders will be automatically created if missing. Try the following code for a complete example.

    To remove an FTreeNode from the tree use an FTreeNodeRemovedNotification as shown in the following code.

Adding nodes on two navigation trees

    As mentioned earlier the tree provider allows the user to create new navigation tree; the following code shows how to create two navigation trees adding nodes to them.

Create adapter to define double click on tree node

    In the above examples the nodes added on the tree had very little functionality. The code in this example shows how to create an adapter to add the double click action to the leaf nodes. In the example we create a new node adapter by extending the DefaultFTreeNodeAdapter, the default implementation of the FTreeNodeAdapter, overwriting its doubleClick method. When double clicking on the nodes created when running the example an empty editor window will appear whose title is the node's name.

Adding a new sorting algorithm

    In the following code a new sorting algorithm is added to the JAS3 lookup table. Running the example a few nodes will be added to the JAS3 navigation tree. By right clicking on the "sortable nodes" folder and selecting the Sorting... menu item you will notice the presence of the algorithm we just added: "Name-length". It sorts nodes based on the length of their name. To achieve this all we had to do was to implement the FTreeNodeSorter interface and register an instance with the lookup table.