org.itsnat.comp.tree

Interface ItsNatTree

All Superinterfaces:

ItsNatComponent, ItsNatElementComponent, ItsNatUserData

All Known Subinterfaces:

ItsNatFreeTree

public interface ItsNatTree
extends ItsNatElementComponent

Is the base interface of tree based components.

A tree component manages a javax.swing.tree.TreeModel data model, tree node values are rendered as markup using a special object, the renderer, and may be optionally edited "in place" using a user defined editor.

Any change to the data model is notified to the component and the markup is rendered again. The data model ever mandates over the markup, any initial markup content (initial root node) is removed.

Almost a root node must be present in the markup, this element is used as a pattern to create new tree nodes, and is removed because by default the data model is empty.

This component family uses a javax.swing.tree.TreeSelectionModel to keep track of selection states. When a tree node is selected (usually by clicking it) the selection state is updated accordingly using the selection model (this one fires any listener registered).

There is no default decoration of tree node selection, selection model listeners may be used to decorate the tree node markup when its selection state changes.

The component internally manages the expand/collapse behavior, when a mouse event is received (by default one click on handler, double click if icon or label) usually changes the expand/collapse state, this change is notified sending a javax.swing.event.TreeExpansionEvent to the registered listeners, these listeners must be used to manage how the expansion/collapsing is rendered visually (by default the component does not modify the view, does not force a default view behavior).

By default this component uses the default renderer and editor and a javax.swing.tree.DefaultTreeModel data model.

Row indexes start in 0.

This component family is the "componentized" version of ElementTree and follows a similar philosophy.

ItsNat only provides "free trees" because no <tree> tag is present in HTML.

Author:

Jose Maria Arranz Santamaria

Method Summary

Methods

Modifier and Type	Method and Description
void	addTreeExpansionListener(javax.swing.event.TreeExpansionListener tel) Registers a new tree expansion listener.
void	addTreeWillExpandListener(javax.swing.event.TreeWillExpandListener tel) Registers a new "tree will expand" listener.
void	collapseNode(javax.swing.tree.TreePath treePath) Marks the specified node as collapsed.
void	collapsePath(javax.swing.tree.TreePath path) Collapses the specified node and node parents.
javax.swing.tree.TreeModel	createDefaultTreeModel() Creates a data model instance appropriated to this component.
void	expandNode(javax.swing.tree.TreePath treePath) Marks the specified node as expanded.
void	expandPath(javax.swing.tree.TreePath path) Expands the specified node and node parents.
javax.swing.tree.TreePath	getEditingPath() Returns the path of the tree node being edited.
int	getEditingRow() Returns the row index of the tree node being edited.
java.lang.String	getEditorActivatorEvent() Returns the event type used to activate the tree node edition process by the user.
ItsNatTreeCellEditor	getItsNatTreeCellEditor() Returns the current tree node label editor.
ItsNatTreeCellRenderer	getItsNatTreeCellRenderer() Returns the current component renderer.
ItsNatTreeStructure	getItsNatTreeStructure() Returns the component structure.
ItsNatTreeUI	getItsNatTreeUI() Returns the user interface manager of this component.
javax.swing.tree.TreePath	getLastPath() Returns the last node (tree order)
javax.swing.tree.TreePath	getNextPath(javax.swing.tree.TreePath path) Returns the path of the next node seeing the data model as a list (tree order).
javax.swing.tree.TreePath	getNextSiblingPath(javax.swing.tree.TreePath path) Returns the path of the next sibling node.
javax.swing.tree.TreePath	getPreviousPath(javax.swing.tree.TreePath path) Returns the previous path seeing the data model as a list (tree order).
javax.swing.tree.TreePath	getPreviousSiblingPath(javax.swing.tree.TreePath path) Returns the path of the previous sibling node.
int	getRowForPath(javax.swing.tree.TreePath path) Returns the row position of the specified path.
javax.swing.tree.RowMapper	getRowMapper() Returns the built-in row mapper.
int	getToggleClickCount() Returns the number of mouse clicks needed to expand or close a node.
javax.swing.event.TreeExpansionListener[]	getTreeExpansionListeners() Returns all registered "tree expansion" listeners
javax.swing.tree.TreeModel	getTreeModel() Returns the current data model of this component.
int	getTreeNodeCount() Returns the number of nodes.
javax.swing.tree.TreePath	getTreePathForRow(int row) Returns the path of the node at the specified row position.
javax.swing.tree.TreeSelectionModel	getTreeSelectionModel() Returns the current selection model.
javax.swing.event.TreeWillExpandListener[]	getTreeWillExpandListeners() Returns all registered tree "tree will expand" listeners
boolean	isEditing() Informs whether a tree node value is being edited.
boolean	isEditingEnabled() Informs whether the in place edition is enabled.
boolean	isExpandedNode(javax.swing.tree.TreePath treePath) Informs whether the specified path is expanded.
boolean	isExpandsSelectedPaths() Returns the expandsSelectedPaths property.
boolean	isJoystickMode() Informs whether a joystick is enough to control the component (some kind of mouse, pointer or stylus not present or not necessary).
boolean	isRootless() Informs whether this tree has a visible root.
boolean	isSelectionUsesKeyboard() Returns if the keyboard is used to select items.
boolean	isTreeTable() Informs whether this tree is a tree-table.
void	removeTreeExpansionListener(javax.swing.event.TreeExpansionListener tel) Unregisters the specified tree expansion listener.
void	removeTreeWillExpandListener(javax.swing.event.TreeWillExpandListener tel) Unregisters the specified "tree will expand" listener.
void	setEditingEnabled(boolean value) Enables or disables temporally the in place edition.
void	setEditorActivatorEvent(java.lang.String eventType) Sets the event type used to activate the tree node edition process by the user.
void	setExpandsSelectedPaths(boolean newValue) Sets the expandsSelectedPaths property.
void	setItsNatTreeCellEditor(ItsNatTreeCellEditor editor) Sets the tree node label editor.
void	setItsNatTreeCellRenderer(ItsNatTreeCellRenderer renderer) Sets the component renderer.
void	setJoystickMode(boolean value) Informs whether a joystick is enough to control the component (some kind of mouse, pointer or stylus not present or not necessary).
void	setSelectionUsesKeyboard(boolean value) Sets if the keyboard is used to select items.
void	setToggleClickCount(int toggleClickCount) Sets the number of mouse clicks needed to expand or close a node.
void	setTreeModel(javax.swing.tree.TreeModel dataModel) Changes the data model of this component.
void	setTreeSelectionModel(javax.swing.tree.TreeSelectionModel selectionModel) Sets the new selection model.
void	startEditingAtPath(javax.swing.tree.TreePath path) Used to start programmatically a tree node edition process "in place".
void	startEditingAtRow(int row) Used to start programmatically a tree node edition process "in place".
void	toggleExpansionStateNode(javax.swing.tree.TreePath treePath) Changes the expansion state of the specified node to the contrary.

Methods inherited from interface org.itsnat.comp.ItsNatElementComponent

getElement, getItsNatElementComponentUI

Methods inherited from interface org.itsnat.comp.ItsNatComponent

addEventListener, addEventListener, addEventListener, addEventListener, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, disableEventListener, disableEventListener, dispose, enableEventListener, enableEventListener, getArtifact, getArtifact, getItsNatComponentManager, getItsNatComponentUI, getItsNatDocument, getNode, getPropertyChangeListeners, getPropertyChangeListeners, getVetoableChangeListeners, isDisposed, isEnabled, registerArtifact, removeArtifact, removeEventListener, removeEventListener, removeEventListener, removeEventListener, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, setEnabled, setEventListenerParams, setEventListenerParams, setNode

Methods inherited from interface org.itsnat.core.ItsNatUserData

containsUserValueName, getUserValue, getUserValueNames, removeUserValue, setUserValue

Method Detail

getItsNatTreeUI

ItsNatTreeUI getItsNatTreeUI()

Returns the user interface manager of this component.

Returns:

the user interface manager.

getTreeModel

javax.swing.tree.TreeModel getTreeModel()

Returns the current data model of this component.

Returns:

the current data model

See Also:

setTreeModel(javax.swing.tree.TreeModel)

setTreeModel

void setTreeModel(javax.swing.tree.TreeModel dataModel)

Changes the data model of this component.

Current data model is disconnected from this component, and the new data model is bound to this component, every change is tracked and updates the user interfaces accordingly.

If the specified data model is the same instance as the current data model, then is reset, component listener is removed and added again. Use this technique if you want to add a data model listener to be executed before the default component listener.

Parameters:

dataModel - the new data model.

See Also:

getTreeModel()

isTreeTable

boolean isTreeTable()

Informs whether this tree is a tree-table.

The tree-table mode only affects to the layout of tree nodes. If not tree-table (normal) child nodes are contained by the parent tree node markup, in a tree-table layout is as a list, all tree nodes are "top" level nodes as whether they all were roots (only from a layout point of view).

This mode is explicitly defined when the component is created calling ItsNatComponentManager.createItsNatFreeTree(org.w3c.dom.Element element,boolean,boolean,ItsNatTreeStructure,org.itsnat.core.NameValue[] artifacts) otherwise is defined by the artifact name "treeTable" if defined or "treeTable" attribute (ItsNat namespace) if defined else is false by default.

Returns:

true if this tree has a tree-table layout.

isRootless

boolean isRootless()

Informs whether this tree has a visible root.

In a root-less tree the root node has no markup, direct child nodes are top level nodes. This feature may be used to build trees with "multiple roots" visually, this is very useful in vertical tree-based menus where a root node is disturbing.

This mode is explicitly defined when the component is created calling ItsNatComponentManager.createItsNatFreeTree(org.w3c.dom.Element element,boolean,boolean,ItsNatTreeStructure,org.itsnat.core.NameValue[] artifacts) otherwise is defined by the artifact name "rootless" if defined or "rootless" attribute (ItsNat namespace) if defined else is false by default.

Returns:

true if root node has no markup.

createDefaultTreeModel

javax.swing.tree.TreeModel createDefaultTreeModel()

Creates a data model instance appropriated to this component. This instance is not bound to the component.

Returns:

a new data model instance.

getToggleClickCount

int getToggleClickCount()

Returns the number of mouse clicks needed to expand or close a node.

This number only counts for icon and label parts, the handle ever expands/collapses the node with every click.

Valid numbers: 0,1 and 2. If 0 icon and label do not expand/collapse the node when clicked.

Returns:

number of mouse clicks to expand/collapse a node. By default is 2.

See Also:

setToggleClickCount(int)

setToggleClickCount

void setToggleClickCount(int toggleClickCount)

Sets the number of mouse clicks needed to expand or close a node.

Parameters:

toggleClickCount - number of mouse clicks to expand/collapse a node. Valid numbers: 0,1 and 2.

See Also:

getToggleClickCount()

addTreeWillExpandListener

void addTreeWillExpandListener(javax.swing.event.TreeWillExpandListener tel)

Registers a new "tree will expand" listener. This listener is called before a tree node is going to expand/collapse and can veto this action.

Parameters:

tel - the listener to register.

See Also:

removeTreeWillExpandListener(javax.swing.event.TreeWillExpandListener)

removeTreeWillExpandListener

void removeTreeWillExpandListener(javax.swing.event.TreeWillExpandListener tel)

Unregisters the specified "tree will expand" listener.

Parameters:

tel - the listener to unregister.

See Also:

addTreeWillExpandListener(javax.swing.event.TreeWillExpandListener)

getTreeWillExpandListeners

javax.swing.event.TreeWillExpandListener[] getTreeWillExpandListeners()

Returns all registered tree "tree will expand" listeners

Returns:

an array with all registered "tree will expand" listeners

addTreeExpansionListener

void addTreeExpansionListener(javax.swing.event.TreeExpansionListener tel)

Registers a new tree expansion listener. This listener is called after a tree node is expanded/collapsed.

Parameters:

tel - the listener to register.

See Also:

removeTreeExpansionListener(javax.swing.event.TreeExpansionListener)

removeTreeExpansionListener

void removeTreeExpansionListener(javax.swing.event.TreeExpansionListener tel)

Unregisters the specified tree expansion listener.

Parameters:

tel - the listener to unregister.

See Also:

addTreeExpansionListener(javax.swing.event.TreeExpansionListener)

getTreeExpansionListeners

javax.swing.event.TreeExpansionListener[] getTreeExpansionListeners()

Returns all registered "tree expansion" listeners

Returns:

an array with all registered "tree expansion" listeners

getItsNatTreeStructure

ItsNatTreeStructure getItsNatTreeStructure()

Returns the component structure.

Returns:

the component structure.

getItsNatTreeCellRenderer

ItsNatTreeCellRenderer getItsNatTreeCellRenderer()

Returns the current component renderer. This renderer converts a tree node value to markup.

Returns:

the current renderer. By default uses the default renderer (ItsNatComponentManager.createDefaultItsNatTreeCellRenderer())

See Also:

setItsNatTreeCellRenderer(ItsNatTreeCellRenderer)

setItsNatTreeCellRenderer

void setItsNatTreeCellRenderer(ItsNatTreeCellRenderer renderer)

Sets the component renderer.

Parameters:

renderer - the new renderer.

See Also:

getItsNatTreeCellRenderer()

getItsNatTreeCellEditor

ItsNatTreeCellEditor getItsNatTreeCellEditor()

Returns the current tree node label editor. This object is used to edit in place a tree node value.

Returns:

the current editor. By default uses the default editor calling (ItsNatComponentManager.createDefaultItsNatTreeCellEditor(ItsNatComponent)) with a null parameter.

See Also:

setItsNatTreeCellEditor(ItsNatTreeCellEditor)

setItsNatTreeCellEditor

void setItsNatTreeCellEditor(ItsNatTreeCellEditor editor)

Sets the tree node label editor.

Tree node edition works very much the same as label edition (see ItsNatLabel.setItsNatLabelEditor(ItsNatLabelEditor)).

Some differences:

The edition process starts programmatically by calling startEditingAtPath(javax.swing.tree.TreePath) or startEditingAtRow(int).

The edition takes place inside the tree node label element as returned by ItsNatTreeStructure.getLabelElement(ItsNatTree,int,org.w3c.dom.Element).

The new tree node value is set to the data model calling javax.swing.tree.TreeModel.valueForPathChanged(javax.swing.tree.TreePath,Object).

Parameters:

editor - the new editor. May be null (edition disabled).

See Also:

getItsNatTreeCellEditor()

getTreeSelectionModel

javax.swing.tree.TreeSelectionModel getTreeSelectionModel()

Returns the current selection model.

Returns:

the current selection model. By default a javax.swing.tree.DefaultTreeSelectionModel instance.

See Also:

setTreeSelectionModel(javax.swing.tree.TreeSelectionModel)

setTreeSelectionModel

void setTreeSelectionModel(javax.swing.tree.TreeSelectionModel selectionModel)

Sets the new selection model.

If the new selection model is the current defined then is "reset", component listener is removed and added again. Use this technique if you want to add a listener to be executed before the default component listener.

The component automatically replaces the current selection model javax.swing.tree.RowMapper with the internal row mapper (getRowMapper()) calling TreeSelectionModel.setRowMapper(RowMapper).

Parameters:

selectionModel - the new selection model.

See Also:

getTreeSelectionModel()

getPreviousPath

javax.swing.tree.TreePath getPreviousPath(javax.swing.tree.TreePath path)

Returns the previous path seeing the data model as a list (tree order).

First tries to return the previous sibling, if no sibling then returns the parent.

Returns:

the previous path or null if specified path is the root node.

See Also:

getNextPath(javax.swing.tree.TreePath), getPreviousSiblingPath(javax.swing.tree.TreePath)

getNextPath

javax.swing.tree.TreePath getNextPath(javax.swing.tree.TreePath path)

Returns the path of the next node seeing the data model as a list (tree order).

First tries to return the first child, if no child returns the next sibling, if no next sibling returns the next sibling of the parent node, if none then the next sibling of the parent of the parent and so on.

Returns:

the next path or null if this node is the last.

See Also:

getPreviousPath(javax.swing.tree.TreePath), getNextSiblingPath(javax.swing.tree.TreePath)

getPreviousSiblingPath

javax.swing.tree.TreePath getPreviousSiblingPath(javax.swing.tree.TreePath path)

Returns the path of the previous sibling node.

Returns:

the previous sibling path or null if specified path is the first child node or is the root.

See Also:

getNextSiblingPath(javax.swing.tree.TreePath)

getNextSiblingPath

javax.swing.tree.TreePath getNextSiblingPath(javax.swing.tree.TreePath path)

Returns the path of the next sibling node.

Returns:

the next sibling path or null if specified path is the last child node or is the root.

See Also:

getPreviousSiblingPath(javax.swing.tree.TreePath)

getLastPath

javax.swing.tree.TreePath getLastPath()

Returns the last node (tree order)

Returns:

the last node, null if the tree is empty.

getTreeNodeCount

int getTreeNodeCount()

Returns the number of nodes. This value is got traversing the data model.

Returns:

the number of nodes.

isExpandsSelectedPaths

boolean isExpandsSelectedPaths()

Returns the expandsSelectedPaths property.

Returns:

true if selection changes result in the parent path being expanded

See Also:

setExpandsSelectedPaths(boolean)

setExpandsSelectedPaths

void setExpandsSelectedPaths(boolean newValue)

Sets the expandsSelectedPaths property. If true, any time the selection is changed, either via the TreeSelectionModel, or the cover methods provided by this component like expandNode(javax.swing.tree.TreePath), the TreePaths parents will be expanded too to make them visible (visible meaning the parent path is expanded, not necessarily in the visible rectangle of the tree). If false, when the selection changes the node parents are not expanded. This is useful if you wish to have your selection model maintain selected paths that are not always expanded (all parents expanded).

Parameters:

newValue - the new value for expandsSelectedPaths

See Also:

isExpandsSelectedPaths()

startEditingAtPath

void startEditingAtPath(javax.swing.tree.TreePath path)

Used to start programmatically a tree node edition process "in place".

Parameters:

path - the tree node path to edit.

See Also:

startEditingAtRow(int), isEditing()

startEditingAtRow

void startEditingAtRow(int row)

Used to start programmatically a tree node edition process "in place".

Parameters:

row - the tree node row to edit.

See Also:

startEditingAtPath(javax.swing.tree.TreePath), isEditing()

isEditing

boolean isEditing()

Informs whether a tree node value is being edited.

Returns:

true if a tree node item value is being edited.

See Also:

startEditingAtPath(javax.swing.tree.TreePath), startEditingAtRow(int)

getEditingPath

javax.swing.tree.TreePath getEditingPath()

Returns the path of the tree node being edited.

Returns:

the path of the tree node item being edited. Null if none is being edited.

getEditingRow

int getEditingRow()

Returns the row index of the tree node being edited.

Returns:

the row index of the tree node item being edited. -1 if none is being edited.

getEditorActivatorEvent

java.lang.String getEditorActivatorEvent()

Returns the event type used to activate the tree node edition process by the user.

If returns null edition activated by events is disabled .

Returns:

the event type used to activate the edition. By default is "dblclick".

See Also:

setEditorActivatorEvent(String)

setEditorActivatorEvent

void setEditorActivatorEvent(java.lang.String eventType)

Sets the event type used to activate the tree node edition process by the user.

Parameters:

eventType - the event type used to activate the edition.

See Also:

getEditorActivatorEvent()

isEditingEnabled

boolean isEditingEnabled()

Informs whether the in place edition is enabled.

Returns:

false if the editing in place is temporally disabled. True by default.

See Also:

setEditingEnabled(boolean)

setEditingEnabled

void setEditingEnabled(boolean value)

Enables or disables temporally the in place edition.

Parameters:

value - true to enable in place edition.

See Also:

isEditingEnabled()

isExpandedNode

boolean isExpandedNode(javax.swing.tree.TreePath treePath)

Informs whether the specified path is expanded.

Parameters:

treePath - the specified path.

Returns:

true if the specified path is expanded, true by default.

See Also:

ItsNatTreeCellUI.isExpanded()

expandNode

void expandNode(javax.swing.tree.TreePath treePath)

Marks the specified node as expanded.

First of all a TreeExpansionEvent event is sent to the registered TreeWillExpandListener listeners, if expansion request is not vetoed then the node is marked as expanded and previous event is sent again to the registered TreeExpansionListener listeners.

Parameters:

treePath - the node path to expand.

See Also:

collapseNode(javax.swing.tree.TreePath), ItsNatTreeCellUI.expand(boolean)

collapseNode

void collapseNode(javax.swing.tree.TreePath treePath)

Marks the specified node as collapsed.

Symmetric behavior is applied to collapse request than expandNode(javax.swing.tree.TreePath).

Parameters:

treePath - the node path to collapse.

See Also:

expandNode(javax.swing.tree.TreePath), ItsNatTreeCellUI.expand(boolean)

toggleExpansionStateNode

void toggleExpansionStateNode(javax.swing.tree.TreePath treePath)

Changes the expansion state of the specified node to the contrary.

Same behavior as expandNode(javax.swing.tree.TreePath) and collapseNode(javax.swing.tree.TreePath).

Parameters:

treePath - the node path to change expansion state.

expandPath

void expandPath(javax.swing.tree.TreePath path)

Expands the specified node and node parents.

Parameters:

path - the path to expand.

See Also:

collapsePath(javax.swing.tree.TreePath)

collapsePath

void collapsePath(javax.swing.tree.TreePath path)

Collapses the specified node and node parents.

Parameters:

path - the path to expand.

See Also:

expandPath(javax.swing.tree.TreePath)

getRowMapper

javax.swing.tree.RowMapper getRowMapper()

Returns the built-in row mapper.

This row mapper can not be replaced and is set automatically to the registered selection model (setTreeSelectionModel(javax.swing.tree.TreeSelectionModel)).

Current implementation converts a TreePath to the matched row seeing the tree as a list (root node is 0), where every node is "visible" (in a server point of view, the same node in the client may be hidden).

Returns:

the built-in row mapper.

getRowForPath

int getRowForPath(javax.swing.tree.TreePath path)

Returns the row position of the specified path. This position is obtained calling the built-in row mapper.

Returns:

the row position of the path.

getTreePathForRow

javax.swing.tree.TreePath getTreePathForRow(int row)

Returns the path of the node at the specified row position.

Current implementation specifies every node is visible (server point of view) row-path conversion is straightforward seeing the tree as a list.

Parameters:

row - the specified row position.

Returns:

the path of the node at this row position.

See Also:

getRowMapper()

isSelectionUsesKeyboard

boolean isSelectionUsesKeyboard()

Returns if the keyboard is used to select items.

If false ItsNat simulates the CTRL key is ever pressed when an item is selected.

This feature is useful for mobile devices without keyboard and tactile screens to select multiple items (if set to false).

Default value is defined by ItsNatComponentManager.isSelectionOnComponentsUsesKeyboard()

Returns:

the current state.

See Also:

setSelectionUsesKeyboard(boolean)

setSelectionUsesKeyboard

void setSelectionUsesKeyboard(boolean value)

Sets if the keyboard is used to select items.

Parameters:

value - the new state.

See Also:

isSelectionUsesKeyboard()

isJoystickMode

boolean isJoystickMode()

Informs whether a joystick is enough to control the component (some kind of mouse, pointer or stylus not present or not necessary).

If the component is in joystick mode, the handle, icon and label elements of every tree node have an event listener associated. By this way tree nodes are "live" elements and can traversed using a joystick in mobile devices without a mouse, pointer or stylus.

Default value is defined by ItsNatDocument.isJoystickMode()

Returns:

true if joystick mode is on.

See Also:

setJoystickMode(boolean), ItsNatTreeStructure.getHandleElement(ItsNatTree, int, org.w3c.dom.Element), ItsNatTreeStructure.getIconElement(ItsNatTree, int, org.w3c.dom.Element), ItsNatTreeStructure.getLabelElement(ItsNatTree, int, org.w3c.dom.Element)

setJoystickMode

void setJoystickMode(boolean value)

Informs whether a joystick is enough to control the component (some kind of mouse, pointer or stylus not present or not necessary).

Parameters:

value - true to enable joystick mode.

See Also:

isJoystickMode()