Would you like to tell us how we are doing?

You bet No thanks

Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Tree views

Use a tree view to display objects, such as folders, in a hierarchical manner.

Objects in the tree view are nodes. The highest node is the root node. A node in the tree can have child nodes under it. A node that has a child is a parent node.

Users can perform the following action in a tree view:

Action

BlackBerry devices with a trackpad only

BlackBerry devices with a touch screen and a trackpad

Expand or collapse an object with a plus sign (+) or minus sign (-) in a hierarchy.

Press the Space key or click the trackpad.

  • Tap the object.
  • Press the Space key.
  • Click the trackpad.

This screen shows an example of a tree view.

Best practice: Implementing tree views

  • Use the TreeField class to create tree views.
  • Provide a pop-up menu if users can perform multiple actions when they click a parent node.
  • Include a root node only if users need the ability to perform actions on the entire tree. Otherwise, exclude the root node.

Create a field to display a tree view

Use a tree view to display objects, such as a folder structure, in a hierarchical manner. A TreeField contains nodes. The highest node is the root node. A node in the tree can have child nodes under it. A node that has a child is a parent node.

  1. Import the required classes and interfaces.
    import net.rim.device.api.ui.component.TreeField;
    import net.rim.device.api.ui.component.TreeFieldCallback;
    import net.rim.device.api.ui.container.MainScreen;
    import java.lang.String;
  2. Implement the TreeFieldCallback interface.
  3. Invoke TreeField.setExpanded() on the TreeField object to specify whether a folder is collapsible. Create a TreeField object and multiple child nodes to the TreeField object. Invoke TreeField.setExpanded() using node4 as a parameter to collapse the folder.
    String fieldOne =  new String("Main folder");
    ...
    TreeCallback myCallback = new TreeCallback();
    TreeField myTree = new TreeField(myCallback, Field.FOCUSABLE);
    int node1 = myTree.addChildNode(0, fieldOne);
    int node2 = myTree.addChildNode(0, fieldTwo);
    int node3 = myTree.addChildNode(node2, fieldThree);
    int node4 = myTree.addChildNode(node3, fieldFour);
    ...
    int node10 = myTree.addChildNode(node1, fieldTen);
    myTree.setExpanded(node4, false);
    ...
    mainScreen.add(myTree);
    
  4. To repaint a TreeField when a node changes, create a class that implements the TreeFieldCallback interface and implement the TreeFieldCallback.drawTreeItem method. The TreeFieldCallback.drawTreeItem method uses the cookie for a tree node to draw a String in the location of a node. The TreeFieldCallback.drawTreeItem method invokes Graphics.drawText() to draw the String.
    private class TreeCallback implements TreeFieldCallback 
    {
        public void drawTreeItem(
             TreeField _tree, Graphics g, int node, int y, int width, int indent) 
        {
            String text = (String)_tree.getCookie(node); 
            g.drawText(text, indent, y);
        }
    }