Class UITree

public class UITree extends UISelector implements IUITree
{
  // Constructors
  public UITree();
  public UITree(String s);
  public UITree(Image i, String s);
  public UITree(IUIComponent comp);
  public UITree(IUIComponent comp, int indent);

  // Methods
  public boolean action(Event e, Object o);
  public IUIComponent add(String s);
  public IUIComponent add(String s, int pos);
  public IUIComponent add(Image i, String s);
  public IUIComponent add(Image i, String s, int pos);
  public IUIComponent add(IUIComponent comp);
  public IUIComponent add(IUIComponent comp, int pos);
  public Rectangle getAttachRect();
  public IUIComponent getExpander();
  public int getRoleCode();
  public int getStateCode();
  public boolean hasChildren();
  public boolean isExpanded();
  public boolean keyDown(Event e, int key);
  public void remove(IUIComponent comp);
  public void remove(int index);
  public void setChecked(boolean on);
  public void setExpanded(boolean expanded);
  public void setExpanded(boolean expanded, boolean notify);
  public void setExpander(IUIComponent to);
  public void setLayout(IUILayoutManager lm);
}

This class implements a tree control. Each UITree object represents an expandable tree node. Use the add method, to insert child components, including other tree nodes. The following example demonstrates this process.

UITree t0, t1;

// Construct the root tree node with the "Colors" text string.
t0 = new UITree("Colors");

// Add two text child items to t0.
t0.add("Red"); 
t0.add("Yellow"); 

// Construct a child node that itself has two children.
{
   t1 = new UITree("Blue");
   t1.add("Navy");
   t1.add("Royal");
}
t0.add(t1);  // Add node t1 to t0.

// Now add t0 to the container.
add(t0); 

Note The item displayed by the root node of a tree control is the tree's header component. UITree inherits the getHeader and setHeader methods to retrieve and set this item. The following example shows how to change the header of a tree node.

// Change the text displayed by t0. Pass a UIText
// object that displays the "Primary Colors" text string.
t0.setHeader(new UIText("Primary Colors"));

For more information about header components, see the UIPanel overview.

When a String is used to create a tree node or to add a child item, the component is automatically hot-tracked. To override this default, use a UIText object, as shown in the following example.

// Construct a tree control using UIText. 
// By default, the node is not hot-tracked.
UITree t2 = new UITree(new UIText("Not hot-tracked"));

// Add three child items to t2. By default, the String item 
// will be hot-tracked. To create a hot-tracked item with 
// UIText, specify the UIStatic.HOTTRACK style.
t2.add("Hot-tracked by default");
t2.add(new UIText("Not hot-tracked"));
t2.add(new UIText("Hot-tracked with UIText", UIStatic.HOTTRACK));

// Add two child items that display an image and text.
// Use UIItem to create an item that is not hot-tracked.
t2.add(myImage, "Hot-tracked by default");
t2.add(new UIItem(myImage, "Not hot-tracked"));

// Add t2 to the container.
add(t2);

For more information about hot-tracking, see the UIText overview.

Typically, a UITree object uses UITreeLayout for its layout manager, which handles the drawing of the attaching lines between a node and its child components. By default, all UITree node children use UIExpandButton to create the tree's expand button. Initially, UITree nodes are not set in the expanded state. To manually expand or collapse a tree node, call its setExpanded method, as shown in the following example.

// Force t0 to display all children.
t0.setExpanded(true);

UITree permits only one child item to be selected at a time, and by default, a list select event is generated when an item is clicked.

Be aware that UITree objects alone have no scrolling capabilities. The easiest way to add this support is to create a UIScrollViewer object that contains the tree control. UIScrollViewer automatically inserts scroll bars when necessary. Also, by using a fixed size layout manager such as UIScrollViewer, the size of the component will be fixed.

The following example adds a tree control to a UIScrollViewer object.

UITree myTree = new UITree();
myTree.add("first item"); // Add an item to myTree.
...  // Continue adding items to myTree.

// Now create a UIScrollViewer object to contain myTree. 
UIScrollViewer sv = new UIScrollViewer(myTree);

// Add sv to the container.
add(sv);

Note The hot-track color is the same color as the button text color. As a result, hot-tracking does not appear to be functional.

UIComponent
  |
  +--UIContainer
    |
    +--UIStateContainer
      |
      +--UIPanel
        |
        +--UISelector
          |
          +--UITree

Constructors

UITree

public UITree();

Creates a tree control with no content.

Remarks:

Call the add method to add child items to the tree control. To add an item to the root node itself, call setHeader (inherited through UIPanel). For an example of calling setHeader, see the UITree overview.

UITree

public UITree(String s);

Creates a tree control with the specified text.

Parameter	Description
s	The text to be displayed by the node.

Remarks:

By default, the tree node is hot-tracked. To create a node that is not hot-tracked, pass a UIText object instead of a String. For more information about hot-tracking, see the UITree overview.

To add child items to the tree control, call the add method.

UITree

public UITree(Image i, String s);

Creates a tree control with the specified image and text.

Parameter	Description
i	The image to be displayed by the node.
s	The text to be displayed by the node.

Remarks:

By default, the tree node is hot-tracked. To create a node that is not hot-tracked, pass a UIItem object instead of an Image and String. For more information about hot-tracking, see the UITree overview.

To add child items to the tree control, call the add method.

UITree

public UITree(IUIComponent comp);

Creates a tree control with the specified component.

Parameter	Description
comp	The component to be displayed by the node.

Remarks:

Typically, you'll pass a UIText, UIGraphic, or UIItem object for the component. To add child items to the tree control, call the add method.

UITree

public UITree(IUIComponent comp, int indent);

Creates a tree control with the specified component and indent.

Parameter	Description
comp	The component to be displayed by the node.
indent	The indent (in pixels) to be used when laying out node children.

Remarks:

Typically, you'll pass a UIText, UIGraphic, or UIItem object for the component. To add child items to the tree control, call the add method.

Methods

action

public boolean action(Event e, Object o);

Determines whether the tree control was double-clicked, and if so, toggles the expanded state.

Return Value:

Returns true if the event was handled; otherwise, returns false.

Parameter	Description
e	The event posted to the tree control.
o	The object that posted the event.

add

public IUIComponent add(String s);

Adds the specified text to the end of the tree control.

Return Value:

Returns the text component that was added.

Parameter	Description
s	The text to be added.

Remarks:

The newly-added child component is shown or hidden, according to the tree control's expanded state. By default, the item is hot-tracked. To add an item that is not hot-tracked, pass a UIText object instead of a String. For more information about hot-tracking, see the UITree overview.

See Also: remove

add

public IUIComponent add(String s, int pos);

Adds the specified text to the tree control at the specified position.

Return Value:

Returns the text component that was added.

Parameter	Description
s	The text to be added.
pos	The zero-based index at which to add the text. If the root node itself displays an item (a header component), this item is at index 0 and the first child begins at index 1. To add a child item at the end of the tree control, pass -1.

Remarks:

The newly-added child component is shown or hidden, according to the tree control's expanded state. By default, the item is hot-tracked. To add an item that is not hot-tracked, pass a UIText object instead of a String. For more information about hot-tracking, see the UITree overview.

Note If the tree node has a header, adding an item at index 0 will insert the item as the new header and shift all other components by one index position. As a result, the previous header becomes the first child item. To simply replace the header without shifting its position, call the setHeader method (inherited through UIPanel). For an example of calling setHeader, see the UITree overview.

See Also: remove

add

public IUIComponent add(Image i, String s);

Adds the specified image and text to the end of the tree control.

Return Value:

Returns the item component that was added.

Parameter	Description
i	The image to be added.
s	The text to be added.

Remarks:

The newly-added child component is shown or hidden, according to the tree control's expanded state. By default, the item is hot-tracked. To add an item that is not hot-tracked, pass a UIItem object instead of an Image and String. For more information about hot-tracking, see the UITree overview.

See Also: remove

add

public IUIComponent add(Image i, String s, int pos);

Adds the specified image and text to the tree control at the specified position.

Return Value:

Returns the item component that was added.

Parameter	Description
i	The image to be added.
s	The text to be added.
pos	The zero-based index at which to add the text and image. If the root node itself displays an item (a header component), this item is at index 0 and the first child begins at index 1. To add a child item at the end of the tree control, pass -1.

Remarks:

The newly-added child component is shown or hidden, according to the tree control's expanded state. By default, the item is hot-tracked. To add an item that is not hot-tracked, pass a UIItem object instead of an Image and String. For more information about hot-tracking, see the UITree overview.

Note If the tree node has a header, adding an item at index 0 will insert the item as the new header and shift all other components by one index position. As a result, the previous header becomes the first child item. To simply replace the header without shifting its position, call the setHeader method (inherited through UIPanel). For an example of calling setHeader, see the UITree overview.

See Also: remove

add

public IUIComponent add(IUIComponent comp);

Adds the specified component to the end of the tree control.

Return Value:

Returns the component that was added.

Parameter	Description
comp	The component to be added.

Remarks:

Typically, you'll pass a UIText, UIGraphic, or UIItem object for the component. The newly-added child component is shown or hidden, according to the tree control's expanded state.

See Also: remove

add

public IUIComponent add(IUIComponent comp, int pos);

Adds the specified component to the tree control at the specified position.

Return Value:

Returns the component that was added.

Parameter	Description
comp	The component to be added.
pos	The zero-based index at which to add the component. If the root node itself displays an item (a header component), this item is at index 0 and the first child begins at index 1. To add a child item at the end of the tree control, pass -1.

Remarks:

Typically, you'll pass a UIText, UIGraphic, or UIItem object for the component. The newly-added child component is shown or hidden, according to the tree control's expanded state.

Note If the tree node has a header, adding an item at index 0 will insert the item as the new header and shift all other components by one index position. As a result, the previous header becomes the first child item. To simply replace the header without shifting its position, call the setHeader method (inherited through UIPanel). For an example of calling setHeader, see the UITree overview.

See Also: remove

getAttachRect

public Rectangle getAttachRect();

Determines where the attaching line will be drawn from the tree node's parent to the tree node.

Return Value:

Returns the node's bounding rectangle.

Remarks:

This method implements getAttachRect in the IUITree interface, and is called by the layout manager's layoutContainer method.

getExpander

public IUIComponent getExpander();

Retrieves the tree control's expand button, which indicates whether the node is expanded or collapsed.

Return Value:

Returns the component currently being used as the expand button.

Remarks:

This method implements getExpander in the IUITree interface. By default, a UITree control uses a UIExpandButton object for its expand button. The setExpander method enables you to specify the component that will be used.

getRoleCode

public int getRoleCode();

Retrieves the ROLE_SYSTEM code that best describes the role of the tree control.

Return Value:

Returns the ROLE_SYSTEM_OUTLINE code.

Overrides:

getRoleCode() in UISelector.

getStateCode

public int getStateCode();

Retrieves the state of the tree control.

Return Value:

Returns the combination of STATE_SYSTEM codes that best describe the state of the control.

Remarks:

If the tree node is expanded, the returned code contains the STATE_SYSTEM_EXPANDED flag. Otherwise, the returned code contains the STATE_SYSTEM_COLLAPSED flag.

Overrides:

getStateCode() in UISelector.

hasChildren

public boolean hasChildren();

Determines whether the tree control has child items.

Return Value:

Returns true if the node has child items; otherwise, returns false.

Remarks:

This method implements hasChildren in the IUITree interface.

isExpanded

public boolean isExpanded();

Determines whether the tree control is expanded.

Return Value:

Returns true if the node is expanded; otherwise, returns false.

Remarks:

This method implements isExpanded in the IUITree interface. To set or clear the expanded state, call setExpanded.

keyDown

public boolean keyDown(Event e, int key);

Determines whether the RIGHT ARROW key or the LEFT ARROW key is being pressed, and if so, expands or collapses the tree control accordingly.

Return Value:

Returns true if event was handled; otherwise, returns false.

Parameter	Description
e	The event posted to the tree control.
key	The key that has been pressed.

Remarks:

This method is called when the tree control has focus and a key is pressed. The RIGHT ARROW key expands the node; the LEFT ARROW key collapses the node.

Overrides:

keyDown(Event,int) in UISelector.

remove

public void remove(IUIComponent comp);

Removes the specified component from the tree control.

Return Value:

No return value.

Parameter	Description
comp	The child component to be removed.

Remarks:

For an example of calling remove, see UISelector.remove. To add a child component to the tree control, call the add method.

Overrides:

remove(IUIComponent) in UISelector.

remove

public void remove(int index);

Removes the component at the specified index from the tree control.

Return Value:

No return value.

Parameter	Description
index	The child component to be removed.

Remarks:

For an example of calling remove, see UISelector.remove. To add a child component to the tree control, call the add method.

Overrides:

remove(int) in UISelector.

setChecked

public void setChecked(boolean on);

Sets or clears the checked state of the tree control.

Return Value:

No return value.

Parameter	Description
on	If true, the checked state is set; otherwise, it is cleared.

Remarks:

This method additionally sets or clears the checked state of the component that is displayed by the tree node.

setExpanded

public void setExpanded(boolean expanded);

Expands or collapses the tree control to show or hide the node's children.

Return Value:

No return value.

Parameter	Description
expanded	If true, the node will be expanded; otherwise, the node will be collapsed.

Remarks:

This method implements setExpanded in the IUITree interface. The display of the node's expand button is updated to reflect the new state.

See Also: isExpanded

setExpanded

public void setExpanded(boolean expanded, boolean notify);

Expands or collapses the tree node to show or hide the node's children.

Return Value:

No return value.

Parameter	Description
expanded	If true, the node will be expanded; otherwise, the node will be collapsed.
notify	If true, the node will generate an action event and post it to the tree node's parent.

setExpander

public void setExpander(IUIComponent to);

Sets the tree control's expand button to the specified component. The expand button indicates whether the node is expanded or collapsed.

Return Value:

No return value.

Parameter	Description
to	The component to be used for the expand button.

Remarks:

This method implements setExpander in the IUITree interface. By default, a UITree control uses a UIExpandButton object for its expand button.

Note Call this method only after the control has been added to a parent container.

See Also: getExpander

setLayout

public void setLayout(IUILayoutManager lm);

Sets the layout manager for the tree control.

Return Value:

No return value.

Parameter	Description
lm	The new layout manager to be used.

Remarks:

When a new UITree object is created with the default indent, it uses the layout manager that is identified by the TREE_LAYOUT index as defined in UISystem. Otherwise, its default layout manager is UITreeLayout.