Main Page Java Education JBuilder Articles

Introduction

JBuilder's TreeControl has become my favorite user interface component of late.  It's a great component for presenting hierarchical data structures to end-users, for things like computer filesystems, indexes of books, indexes to hypertext documents and web sites, and as a database interface.  You see many examples of TreeControl components throughout JBuilder's AppBrowser , such as in the Navigation or Structure panes.

In this article we'll use JBuilder's TreeControl component to build a TreeControl frame to act as an index for a hypothetical book, code-named "My Life and Times."  In this example you'll learn how to create and populate a TreeControl component for use in your own applications.
 

Adding a TreeControl to a frame

We'll start our project by opening a new application in JBuilder.  The easiest way to do this is to start JBuilder, then select File | New ....  When the New... frame opens, click on the Application icon, then click OK.

At the Project Wizard frame, change the name of the Project file to C:\JBuilder\myprojects\TreeControl\TreeControl.jpr.  Note that your location may vary slightly depending on your JBuilder installation path.  Leave the rest of the fields as they are, then click Finish.

After the Project Wizard finishes setting up your initial Project environment, the Application Wizard prompts you for application-related information.  At the Application Wizard: Step 1 of 2 window, change the Class Name field to MyTreeControl, and then click Next.

At the Application Wizard: Step 2 of 2 window, change the Class field to TreeControlFrame.  Then, change the Title field in the Frame Style section to "Index of My Life", and then click Finish.  You're now presented with JBuilder's AppBrowser IDE.
In the IDE, click once on the TreeControlFrame.java text field in the Navigation pane.  This displays the Java source code for the TreeControlFrame in the Source pane.  Next, click on the Design tab below the Source pane to switch to the UI Designer interface.

In the UI Designer, re-size the TreeControlFrame, and then re-size both the UI Designer and the Inspector, until your display looks like Figure 1.  (Note:  If you can't initially grab any of the corners of the TreeControlFrame with your mouse, I've found it helpful to click on the middle of the frame first, then click on the title bar of the frame.)

 

Figure 1:	A view of the JBuilder AppBrowser after resizing the windows.

 
Now we'll add the JBuilder TreeControl component to the TreeControlFrame.  From the Controls tab of the Component Palette, left-click on the TreeControl component.  This component is shown in Figure 2.  Next, move your mouse pointer to the TreeControlFrame in the UI Designer, and left-click your mouse in the middle of the TreeControlFrame.  This drops the new TreeControl component into your frame, and places the component inside of the bevelPanel1 component.
 

Figure 2:	JBuilder's TreeControl component is at the right-end of the Controls tab group in the Component Palette.

 
Before running the application to see what it looks like, this is a good time to save your work.  Select File | Save All to save everything in the project.

After saving your project, click the Run icon, or select Run | Run "MyTreeControl" to see what the application looks like right now.  Immediately you'll notice two problems.  First, there is no tree!  Stand by - we'll take care of this problem in a minute.
The second problem is that the TreeControl component appears as a small window that does not re-size when the frame is re-sized.  As a test, try resizing the frame to see what happens.  Fortunately, this problem is easily corrected, and we'll fix it first.
 

Getting the TreeControl to re-size with the TreeControlFrame

First, close the running application.  Then, in the Component Tree of the AppBrowser, click on the bevelPanel1 component, labeled bevelPanel1(XYLayout).  Then move to the Inspector window, and double-click in the layout field to activate the pull-down choice control.  Change the layout property to BorderLayout, and watch what happens to your TreeControlFrame in the UI Designer.  The TreeControl is re-sized automatically to fill the entire contents of bevelPanel1.  That's all you need to do to fix this problem.

To test this simple change, click on the Run icon and try resizing your TreeControlFrame.  The TreeControl should now automatically re-size when you re-size the window.

Populating the tree

With the window resizing problem behind us, we can move on to populating the nodes of the tree with useful information.
For our "Index of My Life" application, we'll first populate several root tree nodes.  For the purposes of this article, we'll condense our lives by creating only three root nodes named The Early Years, Marriage, and The Children.

To start adding the root nodes, we need to edit the TreeControlFrame.java source code.  After you've closed the running application from the previous section, click on the TreeControlFrame.java text in the Navigation pane.  Then click on the Source tab under the UI Designer to display the Java source code for the TreeControlFrame.java file.  It's useful to click the maximize icon of the AppBrowser at this time to enlarge the Source window.

In the TreeControlFrame.java source file, move down to a point just below the jbInit() method definition, and add the code for a new method named fillTree(), as shown below:

private void fillTree() {
  GraphLocation root = treeControl1.setRoot("My Life");
}

Next, we'll make a few other adjustments to the source code before running our application.  First, move to the top of the source file and add the following import statement below the existing import statements:

import borland.jbcl.model.*;

This line is necessary to include the GraphLocation class definition.  Next, move down to the TreeControlFrame() constructor method, and add the following line just below the jbInit(); method call in the constructor:

fillTree();

After this change, the TreeControlFrame constructor will look like this:

//Construct the frame
public TreeControlFrame() {
  try {
    jbInit();
    fillTree();
  }
  catch (Exception e) {
    e.printStackTrace();
  }
}

This change runs the fillTree() method after the jbInit() method is finished running.
Once you've made these changes, save your project information by selecting File | Save All, and then click the Run icon to run your application.  Your TreeControlFrame should now have a root node labeled My Life.  Nothing fancy yet, but it's a good start.

Next we'll add a few child nodes to the root node.  We'll add one child node for each main period of our life.  Using the names presented earlier for the three primary periods of our life, our modified fillTree() method is shown in Listing 1.
 
 
 

private void fillTree() {    GraphLocation root = treeControl1.setRoot("My Life");    GraphLocation earlyYears  = treeControl1.addChild(root, "The Early Years");    GraphLocation marriage    = treeControl1.addChild(root, "Marriage");    GraphLocation theChildren = treeControl1.addChild(root, "The Children");  }

 

Listing 1:	The fillTree() method with three child nodes off the root.

 
Notice that we're using the addChild() method to add the child nodes earlyYears, marriage, and theChildren to the root object of treeControl1.  As the name addChild() implies, these statements define each of these nodes to be children of the root node.  These children are also siblings - you could say they exist as brothers and sisters, as children of the root.

Again run the application by clicking the Run icon.  When the application starts, the TreeControlFrame should display the words "My Life" just to the right of a familiar plus-sign icon.  You're probably used to seeing this plus-sign in the Windows95 or Windows NT filesystem Explorer.  Click on the plus-sign to expose the child nodes, and you'll see the complete hierarchy.  After a little resizing, your running application should look like the TreeControlFrame in Figure 3.
 

 

Figure 3:	The root and three child nodes of the TreeControl hierarchy are visible in this view.

 

To make the tree more interesting, let's add a few more details about our lives.  Change the fillTree() method to include the additional lines shown in Listing 2 (or, if you prefer, add details pertinent to your own history).
 
 

private void fillTree() {    GraphLocation root = treeControl1.setRoot("My Life");    GraphLocation earlyYears  = treeControl1.addChild(root, "The Early Years");    GraphLocation marriage    = treeControl1.addChild(root, "Marriage");    GraphLocation theChildren = treeControl1.addChild(root, "The Children");    GraphLocation birth   = treeControl1.addChild(earlyYears, "Birth");    GraphLocation college = treeControl1.addChild(earlyYears, "College");    GraphLocation firstDate  = treeControl1.addChild(marriage,    "The First Date");    GraphLocation lateNights = treeControl1.addChild(theChildren, "Late Nights");     }

 

Listing 2:	The fillTree() method with child nodes added to the three already-existing child nodes.

 
In this code, notice that the birth and college objects are added as children of the earlyYears node, firstDate is a child of the marriage node, and lateNights is a child of the node named theChildren.  It is in this manner, as you add child objects to child nodes, that the tree begins to take shape.

When you run the code, you'll see the familiar TreeControlFrame open, with the My Life root node next to the plus-sign.  Clicking on the plus-sign displays the three child nodes, with plus-sign's next to them.  Clicking on each plus sign in turn displays the next layer of child nodes.  After each node has been opened, your display will look similar to Figure 4.
 

 

Figure 4:	All of the TreeControl nodes are displayed in the running application.

 

A few useful methods

As you play with this TreeControl application, you'll see that you can edit the names of the nodes by clicking twice on the name in the tree.  You've also seen that when the application first starts, the tree is collapsed into one node.  The next two methods will demonstrate how to modify this TreeControl behavior.

Adding the following line of code to the jbInit() method disables the user's ability to edit the name of each node by double-clicking on the name:

treeControl1.setEditInPlace(false);

treeControl1.setExpandByDefault(true);

Summary

This is the basic manner in which tree-like user interface elements are developed using JBuilder's TreeControl component.  In a real world application, you'll probably want to use a different data structure behind the scenes.  Instead of scalar variables like earlyYears, marriage, and theChildren, you'll want to use a data structure that can grow and shrink as nodes are added-to and removed from the tree.  This can include simple vectors and linked-lists, as well as more complex tree data structures.

If you're interested in an additional example of using the TreeControl component, Borland has included a sample TreeControl application with the JBuilder software.  If you used the default JBuilder installation directory, you'll find the sample in the C:\JBuilder\samples\borland\samples\jbcl\treecontrol directory.  The naming structure I used in this article is similar to the names in the Borland example, to make their sample easier to understand.
 

Conclusion

You can quickly add TreeControl components to your applets and applications by using JBuilder's TreeControl component.  Adding the initial TreeControl component is made simple with JBuilder's AppBrowser interface, while adding the nodes to the tree requires some more complex behind-the-scenes coding.

Note - this article first appeared in ZD Journals, by Ziff-Davis.

Read the BLOG

Copyright © 1998-2005 DevDaily Interactive, Inc.
All Rights Reserved.