net.rim.device.api.ui.component
Class TreeField

java.lang.Object
  net.rim.device.api.ui.Field
      net.rim.device.api.ui.component.TreeField

public class TreeField
extends Field

A simple field to show a tree structure.

Behaviour
Shows a field structure useful for displaying objects in a hierarchy (like a set of nested folders).

Field Summary

Fields inherited from class net.rim.device.api.ui.Field

ACTION_INVOKE, AXIS_HORIZONTAL, AXIS_SEQUENTIAL, AXIS_VERTICAL, EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEADING, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_TRAILING, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL

Constructor Summary

TreeField(TreeFieldCallback callback, long style)
Constructs an empty TreeField instance with given callback.

Method Summary
int	addChildNode(int parent, Object cookie) Adds a new child node to this tree field.
int	addChildNode(int parent, Object cookie, boolean updateLayout) Adds a new child node to this tree field.
int	addSiblingNode(int previousSibling, Object cookie) Adds a new sibling node to this tree field.
int	addSiblingNode(int previousSibling, Object cookie, boolean updateLayout) Adds a new sibling node to this tree field.
void	deleteAll() Deletes all trees in this field.
void	deleteSubtree(int node) Delete the entire subtree rooted at 'node'.
protected void	drawFocus(Graphics graphics, boolean on) Draws the focus indicator for this field.
AccessibleContext	getAccessibleContext() Returns accessible representation of the field for a screen reader.
Object	getCookie(int node) Retrieves the user-supplied cookie object for the given node.
int	getCurrentNode() Retrieves ID of node with focus.
String	getEmptyString() Retrieves empty marker string.
int	getEmptyStringStyle() Retrieves drawing style of the empty marker string.
boolean	getExpanded(int node) Determines if node is expanded or collapsed.
int	getFirstChild(int node) Retrieves ID of first child of specified node.
int	getFirstRoot() Retrieves ID of this tree's first root node.
void	getFocusRect(XYRect rect) Retrieves this field's current focus region.
void	getFocusRectPhantom(XYRect rect) Retrieves this field's current focus phantom region.
int	getLastNode(int node, boolean followCollapsed) Retrieves the last node in a prefix depth first traversal of the subtree rooted at the given node.
int	getNextSibling(int node) Retrieves ID of next sibling of specified node.
int	getNodeCount() Retrieves total number of nodes in this tree.
int	getParent(int node) Retrieves ID of specified node's parent.
int	getPreviousSibling(int node) Retrieves ID of the previous sibling of specified node.
int	getRowHeight() Retrieves this field's row height.
boolean	getVisible(int node) Determines if node is visible.
int	getVisibleNodeCount() Retrieves number of visible nodes in this tree.
void	invalidateNode(int node) Invalidates the given node for repainting.
protected boolean	keyChar(char character, int status, int time) Handles character generation events.
protected void	layout(int width, int height) Lays out this field's contents.
protected void	makeContextMenu(ContextMenu contextMenu) Builds this field's context menu.
protected int	moveFocus(int amount, int status, int time) Handles moving the focus within this field.
protected void	moveFocus(int x, int y, int status, int time) Handles moving the focus within this field.
int	nextNode(int node, int root, boolean followCollapsed) Retrieves the next node in a prefix depth first traversal of the tree.
protected void	onFocus(int direction) Invoked when this field receives the focus.
protected void	onUnfocus() Invoked when this field loses the focus.
protected void	paint(Graphics graphics) Redraws this field.
int	previousNode(int node, boolean followCollapsed) Retrieves the previous node in a prefix depth first traversal of the tree.
void	setCookie(int node, Object cookie) Sets the user-supplied cookie object for the given node.
void	setCurrentNode(int node) Sets the current node for this field.
void	setDefaultExpanded(boolean expanded) Sets the default expansion state for future node allocations.
void	setEmptyString(String emptyString, int style) Sets the empty marker string for this field.
void	setExpanded(int node, boolean expanded) Sets the expansion state for the given node.
void	setExpanded(int node, boolean expanded, boolean updateLayout) Sets the expansion state for the given node.
void	setIndentWidth(int indent) Sets the indent width.
void	setRowHeight(int rowHeight) Sets the height of each row in the list field.
void	setRowHeightInLines(int rowHeight) Sets the height of each row in the list field.
protected boolean	touchEvent(TouchEvent message) Traps touch input events.

Methods inherited from class net.rim.device.api.ui.Field

drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isMuddy, isPasteable, isScrollCopyable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyControl, keyDown, keyRepeat, keyStatus, keyUp, navigationClick, navigationMovement, navigationUnclick, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setDirty, setEditable, setEnabled, setExtent, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, trackwheelClick, trackwheelUnclick, updateLayout

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TreeField

public TreeField(TreeFieldCallback callback,
                 long style)

Constructs an empty TreeField instance with given callback.

Parameters:

callback - Drawing callback object for this field.

style - The only valid styles for tree fields are Field.NON_FOCUSABLE and Field.FOCUSABLE.

Throws:

NullPointerException - If callback parameter is null and this is not a TreeFieldCallback.

IllegalArgumentException - If you specify an invalid style.

Method Detail

drawFocus

protected void drawFocus(Graphics graphics,
                         boolean on)

Draws the focus indicator for this field.

This method inverts the row of the current node offset by the indent. If moveMode is true, a rectangle is instead drawn around the current node with up/down arrows on the right

Overrides:

drawFocus in class Field

Parameters:

graphics - Graphics object for drawing the focus.

on - True if the focus should be set; otherwise, false.

getAccessibleContext

public AccessibleContext getAccessibleContext()

Returns accessible representation of the field for a screen reader.

Overrides:

getAccessibleContext in class Field

Returns:

AccessibleContext instance

Since:

BlackBerry API 4.6.1

getCookie

public Object getCookie(int node)

Retrieves the user-supplied cookie object for the given node.

Parameters:

node - ID of the node for which to retrieve the cookie.

Returns:

Cookie associated with the given node.

getCurrentNode

public int getCurrentNode()

Retrieves ID of node with focus.

Returns:

Node ID of the current node with focus, or -1 if no node has the focus.

getExpanded

public boolean getExpanded(int node)

Determines if node is expanded or collapsed.

Note that this method does not tell you whether a node can be collapsed (i.e. has at least one child); nodes with no children are automatically and permanently expanded.

Parameters:

node - ID of node to test.

Returns:

True if the node is expanded, false if the node is collapsed.

getFirstChild

public int getFirstChild(int node)

Retrieves ID of first child of specified node.

Parameters:

node - ID of parent node; or 0 to retrieve the first root node.

Returns:

ID of the first child node of specified parent; or -1 if the parent has no child nodes.

getFirstRoot

public int getFirstRoot()

Retrieves ID of this tree's first root node.

Returns:

ID of the first root node (the first sibling node in the tree that has no parent); or -1 if this tree has no nodes.

getFocusRect

public void getFocusRect(XYRect rect)

Retrieves this field's current focus region.

Overrides:

getFocusRect in class Field

Parameters:

rect - To contain the focus extent for this field, in local coordinates.

getFocusRectPhantom

public void getFocusRectPhantom(XYRect rect)

Retrieves this field's current focus phantom region.

Overrides:

getFocusRectPhantom in class Field

Parameters:

rect - To contain the phantom focus extent for this field, in local coordinates. This rect will be identical to, or a superset set of, the current focus region.

Since:

BlackBerry API 3.6.0

getNextSibling

public int getNextSibling(int node)

Retrieves ID of next sibling of specified node.

Parameters:

node - ID of sibling node.

Returns:

ID of the next node sibling to your specified node; or -1 if your node has no further siblings.

getNodeCount

public int getNodeCount()

Retrieves total number of nodes in this tree.

Invoke this method to retrieve the total number of nodes contained in this tree, including all the child nodes of collapsed ancestors (i.e. those nodes not currently visible).

Returns:

Total number of nodes in this tree.

getParent

public int getParent(int node)

Retrieves ID of specified node's parent.

Parameters:

node - ID of node for which to retrieve parent.

Returns:

ID for your specified node's parent; or 0, if your node is a root node (has no parents).

getPreviousSibling

public int getPreviousSibling(int node)

Retrieves ID of the previous sibling of specified node.

Parameters:

node - ID of sibling node.

Returns:

ID of the previous node sibling to your specified node; or -1 if your node has no previous siblings.

getRowHeight

public int getRowHeight()

Retrieves this field's row height.

Returns:

Row height, in pixels.

getVisible

public boolean getVisible(int node)

Determines if node is visible.

Note that this method does not necessarily report on whether the node is currently shown on the screen (i.e. visible to the user). It reports only whether or not the specified node is "hidden" by a collapsed ancestor.

Parameters:

node - ID of node to test.

Returns:

True if the node is visible (no ancestor is collapsed), false otherwise.

invalidateNode

public void invalidateNode(int node)

Invalidates the given node for repainting.

Parameters:

node - ID of the node to invalidate

getVisibleNodeCount

public int getVisibleNodeCount()

Retrieves number of visible nodes in this tree.

Invoke this method to retrieve the number of nodes currently shown in this tree (i.e. not including child nodes of currently collapsed ancestors).

Returns:

Number of visible nodes in this tree.

keyChar

protected boolean keyChar(char character,
                          int status,
                          int time)

Handles character generation events.

This field's manager invokes this method to handle SPACE key generation events. All other key events are passed on, and this method then returns false.

If the key pressed is SPACE, then this method may do a number of things:

• If no node in the tree currently has the focus, this method returns false (passes on the event).
• If the currently focused node has no children, this method swallows the key event but does nothing.
• If the currently focused node does have children, this method toggles its display state: if the node is currently expanded to show the children, it collapses to hide the children; if the node is currently collapsed, it expands.

Overrides:

keyChar in class Field

Parameters:

character - Character generated.

status - Modifier key status.

time - Number of milliseconds since the device was turned on.

Returns:

True if this method consumed the event; otherwise, false.

touchEvent

protected boolean touchEvent(TouchEvent message)

Traps touch input events.

This method handles touch input events. DOWN events cause this TreeField to enter a focused state, which is in fact handled at the Manager level. UNCLICK events toggle the tree nodes. The remaining touch input events are consumed and/or ignored.

Overrides:

touchEvent in class Field

Parameters:

message - TouchEvent object containing various input parameters including the event type and touch coordinates.

Returns:

True if the event was consumed; otherwise, false.

Throws:

IllegalArgumentException - If message is null.

Since:

BlackBerry API 6.0.0

layout

protected void layout(int width,
                      int height)

Lays out this field's contents.

This field's manager invokes this method during the layout process to instruct this field to arrange its contents, given an amount of available space.

Specified by:

layout in class Field

Parameters:

width - Amount of available horizontal space.

height - Amount of available vertical space.

makeContextMenu

protected void makeContextMenu(ContextMenu contextMenu)

Builds this field's context menu.

The framework invokes this method to construct this field's context menu. This method overrides the one in Field in order to provide menu items to Collapse Item and Expand Item.

Overrides:

makeContextMenu in class Field

Parameters:

contextMenu - Context menu for this field.

See Also:

ContextMenu

moveFocus

protected void moveFocus(int x,
                         int y,
                         int status,
                         int time)

Handles moving the focus within this field.

This method is invoked by the framework to move the focus within this field. Given an x,y position in client coordinates, update the focus to point to the new location.

Does nothing if the x,y position is out of range.

Overrides:

moveFocus in class Field

Parameters:

x - Horizontal coordinate of the new focal point

y - Vertical coordinate of the new focal point

status - Modifier key state.

time - Ticks since device reset.

Since:

BlackBerry API 4.0.0

moveFocus

protected int moveFocus(int amount,
                        int status,
                        int time)

Handles moving the focus within this field.

The framework invokes this method to move the focus within this field. The value of the amount parameter determines the direction of the roll: a negative amount value indicates a backwards direction, whereas a positive amount indicates a forwards direction.

Overrides:

moveFocus in class Field

Parameters:

amount - Number of positions to move, positive means forwards in the tree, negative means backwards in the tree.

status - Modifier key state.

time - Number of milliseconds since the device was turned on.

Returns:

Remaining scroll amount not used up (if the start or end of the tree is reached, for example).

onFocus

protected void onFocus(int direction)

Invoked when this field receives the focus.

Overrides:

onFocus in class Field

Parameters:

direction - If 1, the focus came from the previous field; if -1, the focus came from the subsequent field; if 0, the focus was directly set (not as a result of trackwheel movement).

onUnfocus

protected void onUnfocus()

Invoked when this field loses the focus.

Overrides:

onUnfocus in class Field

paint

protected void paint(Graphics graphics)

Redraws this field.

This field's manager invokes this method during the repainting process to instruct this field to repaint itself.

This method determines what tree elements require repainting, and then invokes the registered TreeFieldCallback to do the actual repainting..

Specified by:

paint in class Field

Parameters:

graphics - Graphics context for repainting this field.

setEmptyString

public void setEmptyString(String emptyString,
                           int style)

Sets the empty marker string for this field.

Provide this method with a string (and style) that this field can display to signify that this tree field is empty (for example the string "[Empty]"). By default, the style for this string is DrawStyle.HCENTER (that is, horizontally centered text).

Parameters:

emptyString - Empty marker string for this field.

style - Drawing style for the empty marker string.

Throws:

NullPointerException - If emptyString parameter is null

getEmptyString

public String getEmptyString()

Retrieves empty marker string.

Returns:

Empty marker string used to show this field is empty.

getEmptyStringStyle

public int getEmptyStringStyle()

Retrieves drawing style of the empty marker string.

Returns:

Drawing style of the empty marker string.

setCurrentNode

public void setCurrentNode(int node)

Sets the current node for this field.

Parameters:

node - ID of the node to make current.

Throws:

IllegalArgumentException - If the identified node is invalid or is not currently visible.

deleteAll

public void deleteAll()

Deletes all trees in this field.

Since:

BlackBerry API 4.0.0

deleteSubtree

public void deleteSubtree(int node)

Delete the entire subtree rooted at 'node'.

The subtree root is also deleted from the tree.

Parameters:

node - ID of the root node of the subtree to be deleted.

addChildNode

public int addChildNode(int parent,
                        Object cookie)

Adds a new child node to this tree field.

Invoke this method to create a new node and add it as the first child of the given parent node. If the parent node already has children, the new node is still placed as the first child.

Parameters:

parent - ID of the parent node, 0 if this is to be the first root node.

cookie - User supplied cookie object to associate with the new node.

Returns:

ID of the newly created node.

addChildNode

public int addChildNode(int parent,
                        Object cookie,
                        boolean updateLayout)

Adds a new child node to this tree field.

Invoke this method to create a new node and add it as the first child of the given parent node. If the parent node already has children, the new node is still placed as the first child.

Parameters:

parent - ID of the parent node, 0 if this is to be the first root node.

cookie - User supplied cookie object to associate with the new node.

updateLayout - If false, layout will not be updated (good for batch operations)

Returns:

ID of the newly created node.

Since:

BlackBerry API 4.7.0

addSiblingNode

public int addSiblingNode(int previousSibling,
                          Object cookie)

Adds a new sibling node to this tree field.

Invoke this method to create a new node and add it as the first sibling of the given sibling node. This method inserts the sibling immediately after the one you identify.

Parameters:

previousSibling - ID of the node after which to place the new node.

cookie - User supplied cookie object to associate with the new node.

Returns:

ID of the newly created node.

addSiblingNode

public int addSiblingNode(int previousSibling,
                          Object cookie,
                          boolean updateLayout)

Adds a new sibling node to this tree field.

Invoke this method to create a new node and add it as the first sibling of the given sibling node. This method inserts the sibling immediately after the one you identify.

Parameters:

previousSibling - ID of the node after which to place the new node.

cookie - User supplied cookie object to associate with the new node.

updateLayout - If false, layout will not be updated (good for batch operations)

Returns:

ID of the newly created node.

Since:

BlackBerry API 4.7.0

setDefaultExpanded

public void setDefaultExpanded(boolean expanded)

Sets the default expansion state for future node allocations.

Parameters:

expanded - True if future nodes should be expanded, false if the nodes should be collapsed.

setExpanded

public void setExpanded(int node,
                        boolean expanded)

Sets the expansion state for the given node.

Parameters:

node - ID of the node.

expanded - True if the node should be expanded, false if the node should be collapsed.

setExpanded

public void setExpanded(int node,
                        boolean expanded,
                        boolean updateLayout)

Sets the expansion state for the given node.

Parameters:

node - ID of the node.

expanded - True if the node should be expanded, false if the node should be collapsed.

updateLayout - If false, layout will not be updated (good for batch operations)

Since:

BlackBerry API 4.7.0

nextNode

public int nextNode(int node,
                    int root,
                    boolean followCollapsed)

Retrieves the next node in a prefix depth first traversal of the tree.

Parameters:

node - ID of the current node, 0 to start at the beginning.

root - ID of the root node of the traversal, 0 to do a complete walk.

followCollapsed - True if the walk should traverse through collapsed nodes; otherwise, false.

Returns:

ID of the next node in a depth first traversal.

previousNode

public int previousNode(int node,
                        boolean followCollapsed)

Retrieves the previous node in a prefix depth first traversal of the tree.

Parameters:

node - ID of the current node, 0 to start at the beginning.

followCollapsed - True if the walk should traverse through collapsed nodes, false otherwise.

Returns:

ID of the previous node in a depth first traversal.

getLastNode

public int getLastNode(int node,
                       boolean followCollapsed)

Retrieves the last node in a prefix depth first traversal of the subtree rooted at the given node.

Parameters:

node - ID of the root of the subtree to traverse.

followCollapsed - True if the walk should traverse through collapsed nodes; otherwise, false.

Returns:

ID of the final node in the traversal.

setCookie

public void setCookie(int node,
                      Object cookie)

Sets the user-supplied cookie object for the given node.

Parameters:

node - ID of the node to associate with the cookie.

cookie - User supplied cookie object.

setIndentWidth

public void setIndentWidth(int indent)

Sets the indent width.

Parameters:

indent - New indent width in pixels.

Throws:

IllegalArgumentException - If indent parameter is negative.

setRowHeight

public void setRowHeight(int rowHeight)

Sets the height of each row in the list field.

Parameters:

rowHeight - Height of each row in the list field.

Throws:

IllegalArgumentException - If invalid row height parameter (if zero, or too small proper display of current font).

Since:

BlackBerry API 4.0.0

setRowHeightInLines

public void setRowHeightInLines(int rowHeight)

Sets the height of each row in the list field.

The row height is in multiples of the height of the font for this field.

Parameters:

rowHeight - Height of each row in the list field.

Throws:

IllegalArgumentException - If invalid row height parameter (if zero, or too small proper display of current font).

Since:

BlackBerry API 4.0.0