TreeView

General

A TreeView is a hierarchical view on data, organized like a tree. A tree consists of nodes and leaves. Nodes can contain other nodes and leafs, leafs are really the leafs and cannot contain other elements. The elements of a treeview can be expanded and collapsed, and you can put ActionEvents of every element. In the Example Section you will find an introduction into configuring a TreeView with the graphical designer as well as a code example.

Example

Properties of the TreeView can be easily set in the Property-Editor of the W4T Eclipse Perspective. Here is a description how to create a Treeview manually for an application:

Just add the TreeView Component to an arbitraty WebForm / WebPanel and select the item property (the three dots ...) from the property view. A window will appear where you can enter, delete and change the order of elements. If you create a node named item1 this node will appear in the outline view on the left side. Selecting this TreeNode you will realize, that this TreeNode has an item property again, so you can add more items to all elements of the treeview likewise.

Example 2

Below you find an example of how to use a TreeView. You can try this example online: http://www.innoopract.com/w4content/

This example shows how to add and remove nodes and leafs from and to a treeview programmatically. The code is located in the in the event handler section and executed when buttons or checkboxes are clicked.

  private void doTvExampleWebActionPerformed( WebEvent e ) throws Exception {
    Item item = ( Item )e.getSource();
    // set the clicked item marked
    item.mark();
    // display the label of the clicked item
    String label = item.getLabel();
    wlbValueDisplayControl.setValue( label );
  }
  
  private void doTreeNode2WebTreeNodeCollapsed( WebEvent e ) throws Exception {
    String label = treeNode2.getLabel();
    String newLabel = replace( label, " (expanded)", " (collapsed)" );
    treeNode2.setLabel( newLabel );
  }
  
  private void doTreeNode2WebTreeNodeExpanded( WebEvent e ) throws Exception {
    String label = treeNode2.getLabel();
    String newLabel = replace( label, " (collapsed)", " (expanded)" );
    treeNode2.setLabel( newLabel );
  }
  
  private void doWslImageSetControlWebItemStateChanged( WebEvent e ) throws Exception {
    String imageSet = wslImageSetControl.getValue();
    if( imageSet.equals( "Explorer" ) ) {
      tvExample.setImageSetName( "images/treeview/explorer/Explorer" );
    } else {
      tvExample.setImageSetName( "images/treeview/swing/Swing" );
    }
  }
  
  private void doWbtMarkedNodeLabelControlWebActionPerformed( WebEvent e ) throws Exception {
    String newLabel = wtxMarkedNodeLabelControl.getValue();
    Item markedNode = tvExample.getMarkedItem();
    markedNode.setLabel( newLabel );
  }
  
  private void doWbtAddNodeControlWebActionPerformed( WebEvent e ) throws Exception {
    TreeLeaf newLeaf = new TreeLeaf();
    newLeaf.setLabel( "Newly added TreeLeaf" );
    
    Item markedItem = tvExample.getMarkedItem();
    TreeNode node;
    if( markedItem instanceof TreeNode ) {
      node = ( TreeNode )markedItem;
    } else {
      node = ( TreeNode )markedItem.getParentNode();
    }

    node.addItem( newLeaf );
    newLeaf.setMarkedBgColor( node.getMarkedBgColor() );
  }
  
  private void doWbtMarkedBgColorControlWebActionPerformed( WebEvent e ) throws Exception {
    String bgColor = wtxMarkedBgColorControl.getValue().trim();
    WebColor bgWebColor = new WebColor( bgColor );
    setMarkedBgColorRec( tvExample, bgWebColor );
  }
  

API documentation

The API documentation for TreeView can be found here.

Images on the TreeView

An image set contains the images for lines, icons, plus and minus for expanding and collapsing nodes etc. Images with standardized names are used by the library to render them into the TreeView's HTML representation.

  1. If you want to have your treeview using your own images, this involves creating the images, putting them into a directory, and tell the TreeView that directory (and possibly some prefix which every image in the set begins with).

    A complete image set contains the following images:

    Two further elements of an image set are not listed on the image above: _PlusInner.gif and _IconExpWithoutChildren.gif. The former is exactly like the _MinusInner.gif (but with plus instead of minus), the latter is similar to the _IconExpWithChildren.gif, but is intended for nodes that have no sub-nodes, which means usually no line fragment at the bottom.

    Image names start with an underscore only for historical reasons (backwards compatibility).

    Example: A custom image set for an entire tree:

    • Create a folder (e.g. images/tree/mytree/ ).
    • Put the images _Empty.gif, _Line.gif etc. into that folder.
    • Set the name of the folder to the TreeView as imageSetName:

          // ...
          TreeView tv = new TreeView();
          tv.setImageSetName( "images/tree/mytree/" );
          // ...
            

  2. You can set special images for single nodes and branches. Here's how:

        // ...
        TreeView tv = new TreeView();
        tv.setImageSetName( "images/tree/mytree/" );
        TreeNode tn1 = new TreeNode();
        tv.addItem( tn1 );
        TreeNode tn2 = new TreeNode();
        tv.addItem( tn2 );
        tn2.setImageSetName( "images/tree/thytree/" );
        // ...
          

    TreeNode tn1 inherits then the image set from the TreeView, tn2 has its own one. Note that an image set applies always to the whole branch below the node you assign it to. All children of tn2 (if it had children) would render images from "images/tree/thytree/".

  3. ImageSets can be organized to share common images (i.e. for lines, plus und minus images), while other images can be specifically set for single nodes or branches. This means that a TreeView can use line and empty images from the shared directory all over the tree and nonetheless put a special icon image to each node, without making it necessary to create a complete image set directory for each node.

    Example: Three nodes with different icons, but the rest shared.

    • Create a folder (e.g. images/tree/mytree/ ).

    • Put the shared images into that folder (e.g. _Empty.gif, _Line.gif etc.).

    • Create a subfolder for each special image set:
      images/tree/mytree/sub1
      images/tree/mytree/sub2
      images/tree/mytree/sub3

    • Put the special images (e.g. the icons) in the respective subfolders.

    • Set the name of the folder to the TreeNodes:

          // ...
          TreeView tv = new TreeView();
          TreeNode tn1 = new TreeNode();
          tv.addItem( tn1 );
          tn1.setImageSetName( "images/tree/mytree#sub1" );
          TreeNode tn2 = new TreeNode();
          tv.addItem( tn2 );
          tn2.setImageSetName( "images/tree/mytree#sub2" );
          TreeNode tn3 = new TreeNode();
          tv.addItem( tn3 );
          tn3.setImageSetName( "images/tree/mytree#sub3" );
          // ...
          

    In the image set name, the part after the # character names the subdirectory for special images, the part before it names the path for common images.

    Therefore, if you set "images/tree/mytree#sub3" as image set name, and an icon image is to be used, the image

    images/tree/mytree/sub3/_LeafIcon.gif

    is used, if it exists, else

    images/tree/mytree/_LeafIcon.gif.

    Since all images but the icons are in the shared directory, you need to put only the special images into their subdirectories and don't have to have duplicate or multiple images of the shared type on disc.

Drag & Drop on treeviews

The example application tutorial contains a trail about Drag & Drop for the tree.


Copyright (c) 2003 by Innoopract Informationssysteme GmbH. All rights reserved.