com.codename1.ui.tree

Class Tree

java.lang.Object

com.codename1.ui.Component

com.codename1.ui.Container

com.codename1.ui.tree.Tree

All Implemented Interfaces:

Animation, Editable, StyleListener, Iterable<Component>

Direct Known Subclasses:

FileTree

public class Tree
extends Container

The Tree component allows constructing simple tree component hierarchies that can be expanded seamlessly with no limit. The tree is bound to a model that can provide data with free form depth such as file system or similarly structured data.
To customize the look of the tree the component can be derived and component creation can be replaced.

And heres a more "real world" example showing an XML hierarchy in a Tree:

Another real world example showing the FileSystemStorage as a tree:

Author:

Shai Almog

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Tree.TreeState A marker interface used for Tree state returned from getTreeState() and passed to setTreeState(com.codename1.ui.tree.Tree.TreeState) for retaining state in a Tree when the model is changed.

Field Summary

Fields inherited from class com.codename1.ui.Component

BASELINE, BOTTOM, BRB_CENTER_OFFSET, BRB_CONSTANT_ASCENT, BRB_CONSTANT_DESCENT, BRB_OTHER, CENTER, CROSSHAIR_CURSOR, DEFAULT_CURSOR, DRAG_REGION_IMMEDIATELY_DRAG_X, DRAG_REGION_IMMEDIATELY_DRAG_XY, DRAG_REGION_IMMEDIATELY_DRAG_Y, DRAG_REGION_LIKELY_DRAG_X, DRAG_REGION_LIKELY_DRAG_XY, DRAG_REGION_LIKELY_DRAG_Y, DRAG_REGION_NOT_DRAGGABLE, DRAG_REGION_POSSIBLE_DRAG_X, DRAG_REGION_POSSIBLE_DRAG_XY, DRAG_REGION_POSSIBLE_DRAG_Y, E_RESIZE_CURSOR, HAND_CURSOR, LEFT, MOVE_CURSOR, N_RESIZE_CURSOR, NE_RESIZE_CURSOR, NW_RESIZE_CURSOR, RIGHT, S_RESIZE_CURSOR, SE_RESIZE_CURSOR, SW_RESIZE_CURSOR, TEXT_CURSOR, TOP, W_RESIZE_CURSOR, WAIT_CURSOR

Constructor Summary

Constructors

Constructor and Description
Tree() Constructor for usage by GUI builder and automated tools, normally one should use the version that accepts the model
Tree(TreeModel model) Construct a tree with the given tree model

Method Summary

Modifier and Type	Method and Description
void	addLeafListener(ActionListener l) A listener that fires when a leaf is clicked
protected void	bindNodeListener(ActionListener l, Component node) Since a node may be any component type developers should override this method to add support for binding the click listener to the given component.
protected Dimension	calcPreferredSize() Calculates the preferred size based on component content.
protected String	childToDisplayLabel(Object child) Converts a tree child to a label, this method can be overriden for simple rendering effects
void	collapsePath(Object... path) Collapses the last element in the path
protected Component	createNode(Object node, int depth) Creates a node within the tree, this method is protected allowing tree to be subclassed to replace the rendering logic of individual tree buttons.
protected Button	createNodeComponent(Object node, int depth) Deprecated. replaced with createNode, bindNodeListener and setNodeIcon
void	expandPath(boolean animate, Object... path) Expands the tree path
void	expandPath(Object... path) Expands the tree path
Component	findNodeComponent(Object node) Finds the component for a model node.
Component	findNodeComponent(Object node, Component root) Finds the component for a model node.
TreeModel	getModel() Returns the tree model instance
protected Object	getModel(Component node) Gets the model for a component in the tree.
Component	getParentComponent(Component nodeComponent) Gets the UI component corresponding to the parent model mode of the node corresponding with the given UI component.
Object	getParentNode(Component nodeComponent) Gets the parent model node for a component.
String[]	getPropertyNames() A component may expose mutable property names for a UI designer to manipulate, this API is designed for usage internally by the GUI builder code
String[]	getPropertyTypeNames() This method is here to workaround an XMLVM array type bug where property types aren't identified properly, it returns the names of the types using the following type names: String,int,double,long,byte,short,char,String[],String[][],byte[],Image,Image[],Object[],ListModel,ListCellRenderer
Class[]	getPropertyTypes() Matches the property names method (see that method for further details).
Object	getPropertyValue(String name) Returns the current value of the property name, this method is used by the GUI builder
Object	getSelectedItem() Returns the currently selected item in the tree
Tree.TreeState	getTreeState() Gets the state of the tree in a format that can be restored later by either the same tree or a different tree whose model includes the same nodes.
protected boolean	isExpanded(Component node) This method returns true if the given node is expanded.
boolean	isMultilineMode() Toggles a mode where rows in the tree can be broken since span buttons will be used instead of plain buttons.
void	refreshNode(Component nodeComponent) Refreshes a node of the tree.
void	removeLeafListener(ActionListener l) Removes the listener that fires when a leaf is clicked
static void	setFolderIcon(Image folderIcon) Sets the icon for a tree folder
static void	setFolderOpenIcon(Image folderIcon) Sets the icon for a tree folder in its expanded state
void	setModel(TreeModel model) Sets the tree model to a new value
void	setMultilineMode(boolean multilineMode) Toggles a mode where rows in the tree can be broken since span buttons will be used instead of plain buttons.
static void	setNodeIcon(Image nodeIcon) Sets the icon for a tree node
protected void	setNodeIcon(Image icon, Component node) Sets the icon for the given node similar in scope to bindNodeListener
protected void	setNodeMaterialIcon(char c, Component node, float size) Sets material icon for the node.
String	setPropertyValue(String name, Object value) Sets a new value to the given property, returns an error message if failed and null if successful.
void	setTreeState(Tree.TreeState state) Sets the tree state.

Methods inherited from class com.codename1.ui.Container

add, add, add, add, add, add, addAll, addComponent, addComponent, addComponent, addComponent, animateHierarchy, animateHierarchyAndWait, animateHierarchyFade, animateHierarchyFadeAndWait, animateLayout, animateLayoutAndWait, animateLayoutFade, animateLayoutFadeAndWait, animateUnlayout, animateUnlayoutAndWait, applyRTL, cancelRepaints, clearClientProperties, constrainHeightWhenScrollable, constrainWidthWhenScrollable, contains, createAnimateHierarchy, createAnimateHierarchyFade, createAnimateLayout, createAnimateLayoutFade, createAnimateLayoutFadeAndWait, createAnimateMotion, createAnimateUnlayout, createReplaceTransition, dragInitiated, drop, encloseIn, encloseIn, findDropTargetAt, findFirstFocusable, fireClicked, flushReplace, forceRevalidate, getBottomGap, getChildrenAsList, getClosestComponentTo, getComponentAt, getComponentAt, getComponentCount, getComponentIndex, getGridPosX, getGridPosY, getLayout, getLayoutHeight, getLayoutWidth, getLeadComponent, getLeadParent, getResponderAt, getSafeAreaRoot, getScrollIncrement, getSideGap, getUIManager, initLaf, invalidate, isEnabled, isSafeArea, isSafeAreaRoot, isScrollableX, isScrollableY, isSelectableInteraction, isSurface, iterator, iterator, keyPressed, keyReleased, layoutContainer, morph, morphAndWait, paint, paintBackground, paintBorderBackground, paintComponentBackground, paintGlass, paramString, pointerPressed, refreshTheme, removeAll, removeComponent, replace, replace, replaceAndWait, replaceAndWait, replaceAndWait, revalidate, revalidateLater, revalidateWithAnimationSafety, scrollComponentToVisible, setCellRenderer, setEnabled, setLayout, setLeadComponent, setSafeArea, setSafeAreaRoot, setScrollable, setScrollableX, setScrollableY, setScrollIncrement, setShouldCalcPreferredSize, setShouldLayout, setUIManager, updateTabIndices

Methods inherited from class com.codename1.ui.Component

addDragFinishedListener, addDragOverListener, addDropListener, addFocusListener, addLongPressListener, addPointerDraggedListener, addPointerPressedListener, addPointerReleasedListener, addPullToRefresh, addScrollListener, addStateChangeListener, animate, bindProperty, blocksSideSwipe, calcScrollSize, contains, containsOrOwns, createStyleAnimation, deinitialize, deinitializeCustomStyle, dragEnter, dragExit, dragFinished, draggingOver, drawDraggedImage, focusGained, focusLost, getAbsoluteX, getAbsoluteY, getAllStyles, getAnimationManager, getBaseline, getBaselineResizeBehavior, getBindablePropertyNames, getBindablePropertyTypes, getBorder, getBoundPropertyValue, getBounds, getBounds, getClientProperty, getCloudBoundProperty, getCloudDestinationProperty, getComponentForm, getComponentState, getCursor, getDirtyRegion, getDisabledStyle, getDraggedx, getDraggedy, getDragImage, getDragRegionStatus, getDragSpeed, getEditingDelegate, getHeight, getInlineAllStyles, getInlineDisabledStyles, getInlinePressedStyles, getInlineSelectedStyles, getInlineStylesTheme, getInlineUnselectedStyles, getInnerHeight, getInnerPreferredH, getInnerPreferredW, getInnerWidth, getInnerX, getInnerY, getLabelForComponent, getName, getNativeOverlay, getNextFocusDown, getNextFocusLeft, getNextFocusRight, getNextFocusUp, getOuterHeight, getOuterPreferredH, getOuterPreferredW, getOuterWidth, getOuterX, getOuterY, getOwner, getParent, getPreferredH, getPreferredSize, getPreferredSizeStr, getPreferredTabIndex, getPreferredW, getPressedStyle, getSameHeight, getSameWidth, getScrollable, getScrollAnimationSpeed, getScrollDimension, getScrollOpacity, getScrollOpacityChangeSpeed, getScrollX, getScrollY, getSelectCommandText, getSelectedRect, getSelectedStyle, getStyle, getTabIndex, getTensileLength, getTextSelectionSupport, getTooltip, getUIID, getUnselectedStyle, getVisibleBounds, getVisibleBounds, getWidth, getX, getY, growShrink, handlesInput, hasFixedPreferredSize, hasFocus, hideNativeOverlay, initComponent, initCustomStyle, initDisabledStyle, initPressedStyle, initSelectedStyle, initUnselectedStyle, installDefaultPainter, isAlwaysTensile, isBlockLead, isCellRenderer, isChildOf, isDragActivated, isDragAndDropOperation, isDraggable, isDragRegion, isDropTarget, isEditable, isEditing, isFlatten, isFocusable, isGrabsPointerEvents, isHidden, isHidden, isHideInLandscape, isHideInPortrait, isIgnorePointerEvents, isInClippingRegion, isInitialized, isOpaque, isOwnedBy, isRippleEffect, isRTL, isScrollable, isScrollVisible, isSetCursorSupported, isSmoothScrolling, isSnapToGrid, isStickyDrag, isTactileTouch, isTactileTouch, isTensileDragEnabled, isTraversable, isVisible, keyRepeated, laidOut, longKeyPress, longPointerPress, onScrollX, onScrollY, paintBackgrounds, paintBorder, paintComponent, paintComponent, paintIntersectingComponentsAbove, paintLock, paintLockRelease, paintRippleOverlay, paintScrollbars, paintScrollbarX, paintScrollbarY, paintShadows, parsePreferredSize, pinch, pinchReleased, pointerDragged, pointerDragged, pointerHover, pointerHoverPressed, pointerHoverReleased, pointerPressed, pointerReleased, pointerReleased, putClientProperty, refreshTheme, refreshTheme, remove, removeDragFinishedListener, removeDragOverListener, removeDropListener, removeFocusListener, removeLongPressListener, removePointerDraggedListener, removePointerPressedListener, removePointerReleasedListener, removeScrollListener, removeStateChangeListener, repaint, repaint, requestFocus, resetFocusable, respondsToPointerEvents, scrollRectToVisible, scrollRectToVisible, setAlwaysTensile, setBlockLead, setBoundPropertyValue, setCloudBoundProperty, setCloudDestinationProperty, setComponentState, setCursor, setDirtyRegion, setDisabledStyle, setDraggable, setDropTarget, setEditingDelegate, setFlatten, setFocus, setFocusable, setGrabsPointerEvents, setHandlesInput, setHeight, setHidden, setHidden, setHideInLandscape, setHideInPortrait, setIgnorePointerEvents, setInitialized, setInlineAllStyles, setInlineDisabledStyles, setInlinePressedStyles, setInlineSelectedStyles, setInlineStylesTheme, setInlineUnselectedStyles, setIsScrollVisible, setLabelForComponent, setName, setNextFocusDown, setNextFocusLeft, setNextFocusRight, setNextFocusUp, setOpaque, setOwner, setPreferredH, setPreferredSize, setPreferredSizeStr, setPreferredTabIndex, setPreferredW, setPressedStyle, setRippleEffect, setRTL, setSameHeight, setSameSize, setSameWidth, setScrollAnimationSpeed, setScrollOpacityChangeSpeed, setScrollSize, setScrollVisible, setScrollX, setScrollY, setSelectCommandText, setSelectedStyle, setSize, setSmoothScrolling, setSnapToGrid, setTabIndex, setTactileTouch, setTensileDragEnabled, setTensileLength, setTooltip, setTraversable, setUIID, setUIID, setUnselectedStyle, setVisible, setWidth, setX, setY, shouldBlockSideSwipe, shouldBlockSideSwipeLeft, shouldBlockSideSwipeRight, shouldRenderComponentSelection, showNativeOverlay, startEditingAsync, stopEditing, stripMarginAndPadding, styleChanged, toImage, toString, unbindProperty, updateNativeOverlay, visibleBoundsContains

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

Tree

public Tree()

Constructor for usage by GUI builder and automated tools, normally one should use the version that accepts the model

Tree

public Tree(TreeModel model)

Construct a tree with the given tree model

Parameters:

model - represents the contents of the tree

Method Detail

getTreeState

public Tree.TreeState getTreeState()

Gets the state of the tree in a format that can be restored later by either the same tree or a different tree whose model includes the same nodes.

Returns:

A TreeState object that can be passed to setTreeState(com.codename1.ui.tree.Tree.TreeState)

setTreeState

public void setTreeState(Tree.TreeState state)

Sets the tree state.

Parameters:

state - The state, which was returned from the getTreeState() method.

isMultilineMode

public boolean isMultilineMode()

Toggles a mode where rows in the tree can be broken since span buttons will be used instead of plain buttons.

Returns:

the multilineMode

setMultilineMode

public void setMultilineMode(boolean multilineMode)

Toggles a mode where rows in the tree can be broken since span buttons will be used instead of plain buttons.

Parameters:

multilineMode - the multilineMode to set

getPropertyNames

public String[] getPropertyNames()

A component may expose mutable property names for a UI designer to manipulate, this API is designed for usage internally by the GUI builder code

Overrides:

getPropertyNames in class Component

Returns:

the property names allowing mutation

getPropertyTypes

public Class[] getPropertyTypes()

Matches the property names method (see that method for further details).

Overrides:

getPropertyTypes in class Component

Returns:

the types of the properties

getPropertyTypeNames

public String[] getPropertyTypeNames()

This method is here to workaround an XMLVM array type bug where property types aren't identified properly, it returns the names of the types using the following type names: String,int,double,long,byte,short,char,String[],String[][],byte[],Image,Image[],Object[],ListModel,ListCellRenderer

Overrides:

getPropertyTypeNames in class Component

Returns:

Array of type names

getPropertyValue

public Object getPropertyValue(String name)

Returns the current value of the property name, this method is used by the GUI builder

Overrides:

getPropertyValue in class Component

Parameters:

name - the name of the property

Returns:

the value of said property

setPropertyValue

public String setPropertyValue(String name,
                               Object value)

Sets a new value to the given property, returns an error message if failed and null if successful. Notice that some builtin properties such as "$designMode" might be sent to components to indicate application state.

Overrides:

setPropertyValue in class Component

Parameters:

name - the name of the property

value - new value for the property

Returns:

error message or null

getModel

public TreeModel getModel()

Returns the tree model instance

Returns:

the tree model

setModel

public void setModel(TreeModel model)

Sets the tree model to a new value

Parameters:

model - the model of the tree

setFolderIcon

public static void setFolderIcon(Image folderIcon)

Sets the icon for a tree folder

Parameters:

folderIcon - the icon for a folder within the tree

setFolderOpenIcon

public static void setFolderOpenIcon(Image folderIcon)

Sets the icon for a tree folder in its expanded state

Parameters:

folderIcon - the icon for a folder within the tree

setNodeIcon

public static void setNodeIcon(Image nodeIcon)

Sets the icon for a tree node

Parameters:

nodeIcon - the icon for a node within the tree

isExpanded

protected boolean isExpanded(Component node)

This method returns true if the given node is expanded.

Parameters:

node - a Component that represents a tree node.

Returns:

true if this tree node is expanded

findNodeComponent

public Component findNodeComponent(Object node)

Finds the component for a model node.

Parameters:

node - The node from the model.

Returns:

The corresponding component in the UI or null if not found.

Since:

7.0

findNodeComponent

public Component findNodeComponent(Object node,
                                   Component root)

Finds the component for a model node.

Parameters:

node - Model node whose view we seek.

root - A root component - we check root and its descendents.

Returns:

The corresponding UI component for node, or null if not found.

Since:

7.0

expandPath

public void expandPath(Object... path)

Expands the tree path

Parameters:

path - the path to expand

expandPath

public void expandPath(boolean animate,
                       Object... path)

Expands the tree path

Parameters:

path - the path to expand

animate - whether to animate expansion

collapsePath

public void collapsePath(Object... path)

Collapses the last element in the path

Parameters:

path - the path to the element that should be collapsed

getSelectedItem

public Object getSelectedItem()

Returns the currently selected item in the tree

Returns:

the object selected within the tree

getParentNode

public Object getParentNode(Component nodeComponent)

Gets the parent model node for a component.

Parameters:

nodeComponent - The UI for a node.

Returns:

The model node's parent, or null if not found.

getParentComponent

public Component getParentComponent(Component nodeComponent)

Gets the UI component corresponding to the parent model mode of the node corresponding with the given UI component.

Parameters:

nodeComponent - UI component, whose node we seek the parent.

Returns:

UI component for the given node's parent.

Since:

7.0

refreshNode

public void refreshNode(Component nodeComponent)

Refreshes a node of the tree.

Parameters:

nodeComponent - The node component.

Since:

7.0

createNodeComponent

protected Button createNodeComponent(Object node,
                                     int depth)

Deprecated. replaced with createNode, bindNodeListener and setNodeIcon

Creates a node within the tree, this method is protected allowing tree to be subclassed to replace the rendering logic of individual tree buttons.

Parameters:

node - the node object from the model to display on the button

depth - the depth within the tree (normally represented by indenting the entry)

Returns:

a button representing the node within the tree

bindNodeListener

protected void bindNodeListener(ActionListener l,
                                Component node)

Since a node may be any component type developers should override this method to add support for binding the click listener to the given component.

Parameters:

l - listener interface

node - node component returned by createNode

setNodeIcon

protected void setNodeIcon(Image icon,
                           Component node)

Sets the icon for the given node similar in scope to bindNodeListener

Parameters:

icon - the icon for the node

node - the node instance

setNodeMaterialIcon

protected void setNodeMaterialIcon(char c,
                                   Component node,
                                   float size)

Sets material icon for the node.

Parameters:

c - Material icon code. See FontImage

node - The node to set the icon for.

size - The size in millimetres for the icon.

Since:

7.0

createNode

protected Component createNode(Object node,
                               int depth)

Creates a node within the tree, this method is protected allowing tree to be subclassed to replace the rendering logic of individual tree buttons.

Parameters:

node - the node object from the model to display on the button

depth - the depth within the tree (normally represented by indenting the entry)

Returns:

a button representing the node within the tree

childToDisplayLabel

protected String childToDisplayLabel(Object child)

Converts a tree child to a label, this method can be overriden for simple rendering effects

Returns:

a string representing the given tree node

addLeafListener

public void addLeafListener(ActionListener l)

A listener that fires when a leaf is clicked

Parameters:

l - listener to fire when the leaf is clicked

removeLeafListener

public void removeLeafListener(ActionListener l)

Removes the listener that fires when a leaf is clicked

Parameters:

l - listener to remove

getModel

protected Object getModel(Component node)

Gets the model for a component in the tree.

Parameters:

node - The component whose model we want to obtain.

Returns:

The model.

Since:

7.0

calcPreferredSize

protected Dimension calcPreferredSize()

Calculates the preferred size based on component content. This method is invoked lazily by getPreferred size.

Overrides:

calcPreferredSize in class Container

Returns:

the calculated preferred size based on component content