Tree Applet documentation v. 1.0
Copyright SCAND LLC 2001

Initialization

Tree applet can load content in two modes:

In both cases it is possible to manage items of the tree applet using public methods of it. This can be done as from another Java applet that uses Tree applet, so from browser using JavaScript. The public methods are described below in the section "Tree methods".

Items parameters

To populate tree with data you should specify for every item set of required parameters, listed below.

Name Required Possible values Description
ITEMi Yes according to IDC parameter Item's identifier. Used as reference to item while accessing from script functions.
TEXTi Yes Any string value Visible name of tree item, which will be displayed on screen.
ACTIONi Yes Valid parameters for script function List of parameters, transmitted to script function, described by EVAL parameter.
Can accept:
1. Integer value
2. String value in single or double quotation marks.
3. Collection of (1) and (2), separated by commas.
LEVELi Yes Integer Level of current node. Must be from 0 till previous item's level + 1.
SELECTi No Any value If specified, then current item will be selected.(Cursor will be placed on last selected item.)
IM0i, IM1i No Integer Indexes of images (given by IMAGEi parameters), associated with current item. Ignored if no ICONS_PERMANENT parameter specified.

It is possible to specify a file name directly in this parameter. In this case the parameter should have value in format f<file_name>
CHILDi No Any value Use in dynamical tree only. Not null value means non-terminal node - children for it will be loaded from server. (See also Dynamic loading section)
COLORi No HTML color format The color of item's text
SELCOLORi No HTML color format The color of text for selected items
OPENEDi No Any value Sets item initially to open state
CHECKEDi No Any value If specified, then current item will be checked (See Check items section)
UNDERLINEi No Any value If specified, then current item will be underlined.
 Note: 'i' indicates the sequential number of an item in initialization list. Starts from 0.

 Example 1. Possible item definition. 

<PARAM NANE='ITEM0' VALUE='0'>
<PARAM NANE='NAME0' VALUE='Root item'>
<PARAM NANE='ACTION0' VALUE="'r13'">
<PARAM NANE='LEVEL0' VALUE='0'>
<PARAM NANE='SELECT0' VALUE='1'>

Representation parameters

This set of parameters describes the color, fonts and other attributes of tree applet. Attributes of fonts and attributes can be redefined for each tree item using Items parameters and Items Properties Control.

Color parameters

This set of parameters describes the color model of the tree applet.
Name Description
BG_COLOR Background color.
FG_COLOR Color of non-selected item's label.
BGSEL_COLOR Background of selected item.
FGSEL_COLOR Color of selected item's label.
LINES_COLOR Color of lines in tree
CROSSES_COLOR Color of crosses for non-terminal items
 

Size parameters

This set of parameters describes sizes of tree components:

o NODE_HEIGHT

The height of node. All nodes in tree has the same height. Default value is 18.

o IMAGE_WIDTH / IMAGE_HEIGHT

Size of icons in tree. If real size of any image differs from this value, image will be resized. Default value is 16x16.

o LEVEL_INDENT

Indent between two levels in tree. Default value is 4.

Images control

This set of parameters specifies the image list of tree items and behavior of showing images.

o IMAGEi

Specifies the list of images for the tree items. Has structure IMAGE0, IMAGE1, ... ,IMAGEn. This numbers can be passed in IM0 and IM1 parameters of an item (see Items parameters).

If ICONS_PERMANENT parameter is not specified, they will have next meaning:
IMAGE0 - Image for root nodes.
IMAGE1 - Image for terminal nodes.
IMAGE2 - Image for non-terminal opened nodes.
IMAGE3 - Image for non-terminal closed nodes.

The path for image starts from TreeApplet class folder.

o ICONS_PERMANENT

If this parameter has non-empty value, then images associated with the item should be given in IM0,IM1 parameters, otherwise, default images from IMAGE0...IMAGE3 parameters will be used instead.

Important: If this parameter specified, minimum one of images (IM0 or IM1) must be specified for each node. Otherwise the tree will not be initialized.

o CROSSES

If this parameter has non-empty value, non-terminal items will be marked with "+" on the left side

Font parameters

Font of tree applet can be defined with help of the next parameters: FONT_NAME / FONT_SIZE / FONT_STYLE
Default value is "Verdana", size 13, style PLAIN.

FONT_STYLE is a composition of the next string values: PLAIN, BOLD, ITALIC, separated by commas.

o ROOT_CLOSEABLE

Allows you to collapse root nodes with LEVEL=0. Disabled by default. 

Check items

 This set of parameters permits to use checkboxes as items in tree

o CHECKBOXES

Creates tree with checkboxes for all nodes. Images for checkboxes has fixed size 11x11 pt and can be specified with followed parameters:

Checkboxes representation:

Name Description Default value
IMAGE_CHECKED Image for checked item icons/item_checked.gif
IMAGE_UNCHECKED Image for unchecked item icons/item_unchecked.gif
IMAGE_SHADEN Image for unchecked item, who has checked children on next levels icons/item_shaden.gif

o SHOW_IMAGES

Shows checkboxes with images. Default value is "1".

o AutoCheckBoxes

Processing of checks is automatic - if item checked, all subnodes becomes to checked state too and all parents came into shadow mode. Default value is "1".

Dynamic loading

In case of huge set of data reasonable to load only root nodes from HTML page and load additionally subnodes as required. For this possibility parameter GET_DOC is using.

Important: This possibility available only in full version of jtree.

o GET_DOC

Used in dynamical trees. It means the name of document, which will load the data from server. Loading happens when:
    1. This parameter is not null,
    2. Node hasn't child subnodes
    3. Parameter CHILD for this node is not null.
The document can get identifier of called node through id parameter and must return the list of strings, ended by empty string. Every string contains information about single child node in the next format:
    "Name","id","action",hasChildren,im0,im1,UNDERLINE
Where id - identifier of the node, name - its name, action - the same meaning as ACTION parameter, hasChildren - CHILD parameter, im0,im1 - IM0,IM1 parameters. If UNDERLINE world specified in last position item will be underlined.

Example 2. ASP document for loading subnodes from database.

<%
id = request("id")
sqlStr ="select KeyField, NameField from DataTable where ParentKeyFied=" & id
set ResultSet = DBConnection.execute(sqlStr)
while not ResultSet.eof
          Key = ResultSet("KeyField")
          Name = ResultSet("NameField")
          response.writeln("""" & Name & """,""" & Key & """,""" & Key & """,0,1,2" )
          ResultSet.moveNext
wend
response.writeln("")
%>

 Menu parameters

o MENU

Enabling menu in tree applet. It will be called after right-button clicking on node. The value of this parameter is the name of script function, wich will be called after selection in menu. It must have two parameters - the identifier of node and number of selected item in menu (started from 0). If this parameter specified, next parameters will be processed:

o MENUi

Specifies the name of menu item. Can has any string values or 'SEPARATOR' for inserting menu separator between menu items.

o ON_MENU_PRE

Specifies menu initialization script function. This function should be used for customizing popup menu and is called directly before displaying menu and takes two parameters: identifier of node and TreeMenu object. Initially this object contains parameters defined with MENUi parameters. See Menu object for additional information..

Menu object

This object is passes into ON_MENU_PRE function and make possible to change structure of the menu in run-time. It has the next set of public functions:

void addSeparator() Adds seperator into menu.
void addString(String txt) Adds new item with specified label into menu.
void void remove(int index) Removes item from menu.
void removeAll() Removes all items from menu.
String getLabel() Gets label of specified item.
setEnable(int index, boolean isEnable)() Sets specified item to enabled or disabled state.
void void setLabel(int index, String txt) Sets label of specified item.

Events processing

 This set of functions specifies script functions to process events from the tree.

o EVAL

The name of script function, which will be called when any item in tree is selected. Values specified in ACTION parameter will be passed to this function.

Example 3. Function with single argument.

function foo( s ) { }

<PARAM name="EVAL" VALUE="f">
<PARAM name="ACTION0" VALUE="0">  // foo(0) will be called
<PARAM name="ACTION1" VALUE="'test'"> // foo('test') will be called
Example 4. Function with two arguments.
function foo( s1, s2 ) { }

<PARAM name="EVAL" VALUE="f">
<PARAM name="ACTION0" VALUE="0,0">  // foo(0,0) will be called
<PARAM name="ACTION0" VALUE="'test',28"> // foo('test',28) will be called
<PARAM name="ACTION0" VALUE="28"> // Invalid, function does't take one argument.

o ON_LOAD

The name of script function, which will be called when all items have been loaded into the tree and you can call any tree applet's method.

o ON_DBLCLICK

The name of script function, which will be called after doubleclicking on node. Function takes single parameter - the identifier of node.

o ON_CHECK

The name of script function, which will be called after changing of checked state of item. It has two parameters - identifier of item and boolean value of current checked state.

Selection parameters

o HIER_SEL

Hierarchical selection flag. By default you cannot select node item and its child simultaneously. To enable child selection you should set this parameter to any nonempty value.

o MULTISELECT

Enabling (1) or disabling (0) multiple selection mode of tree. Default it's enabled.

Other parameters

o TREENAME

Specified name of tree. In this case state of tree will be stored in internal java variable and restored after page reloading.

Member functions

Search functions

o findRef 
public String findRef(java.lang.String ref)
Returns identifier of node with action act.

Parameters:
ref - action for searching

Retutns:
identifier of first item with action=ref or null if not found.
o findRefByLabel 
public String findRefByLabel(java.lang.String lbl)
Returns separated by comas list of items with specified label

Retutns:
list of identifiers or null if no items found

Selection control

o hasData 
public boolean hasData()
Checking for presents of selected items in tree

Retutns:
Returns true if there are some selected items in tree.
o getSelectedItems 
public String getSelectedItems()
Gets names of selected items from tree

Retutns:
Returns the names of selected items, separated by commas. Empty string will be returned if zero items are selected.
o getSelectedItemsId 
public String getSelectedItemsId()
Gets identifiers of selected items from tree

Retutns:
Returns the identifiers of selected items, separated by commas. Empty string will be returned if zero items are selected.
public String getSelectedItemsId(java.lang.String delimiter)
Gets identifiers of selected items from tree, separated by delimiter

Retutns:
Returns the identifiers of selected items, separated by delimiter. Empty string will be returned if zero items are selected.
public String getSelectedItemsId(int sortType)
Returns the identifiers of selected items, separated by commas. Empty string will be returned if zero items selected.

Parameters:
sortType - If sortType = 0 returns id's in natural selection order, sortType = 1 - in 'top down' order

Retutns:
Returns the identifiers of selected items, separated by commas. Empty string will be returned if zero items are selected.
public String getSelectedItemsId(int sortType, java.lang.String delimiter)
Returns the identifiers of selected items, separated by delimiter. Empty string will be returned if zero items selected.

Parameters:
sortType - If sortType = 0 returns id's in natural selection order, sortType = 1 - in 'top down' order

Retutns:
Returns the identifiers of selected items, separated by commas. Empty string will be returned if zero items are selected.
o getLastSelectedId 
public String getLastSelectedId()
Gets last selected item from tree

Retutns:
Returns the identifier of the last selected item. Empty string will be returned if zero items are selected.
o isLastItemSelected 
public boolean isLastItemSelected()
Gets state of last selected item from tree

Retutns:
Returns true, if last selected item is't deselected by repeated pressing on it. (One of item has color border around it)
o selectItem 
public void selectItem(java.lang.String id)
Moves selection to the item with specified ID.

Parameters:
id - identifier of node
public void selectItem(java.lang.String id, boolean isCall)
Moves selection to the item with specified ID.

Parameters:
id - identifier of node
isCall - If true, script function for selected node will be called.
o addSelection 
public void addSelection(java.lang.String id, boolean isCall)
Adds (or removes) item into select list (in multiselect tree)

Parameters:
id - identifier of node
isCall - If true, script function for selected node will be called.

Navigation functions

o getSubItems 
public String getSubItems(java.lang.String id)
Returns the list of all children items from the next level of tree, separated by commas.

Parameters:
id - identifier of item

Retutns:
list of childer identifiers, separated by commas. Empty for terminal nodes. Null if item not found.
o getAllSubItems 
public String getAllSubItems(java.lang.String id)
Returns the list of all children items from all next levels of tree, separated by commas.

Parameters:
id - identifier of item

Retutns:
list of identifiers, null if id not found
o getLastAllSubItems 
public String getLastAllSubItems(java.lang.String id)
Similar to the getAllSubItems except we only want the last descendant.
o getNextItem 
public String getNextItem(java.lang.String id)
Return the id of the item that appears next sequentially in the tree.
o getNextSibling 
public String getNextSibling(java.lang.String id)
Return the id of the next sibling after parameter id.

Items properties control

o setLabel 
public void setLabel(java.lang.String id, java.lang.String text)
Available in full version only
Sets label for the item with specified ID.

Parameters:
id - identifier of node
text - new item label
o getParentId 
public String getParentId(java.lang.String id)
Returns the parent ID for item.

Parameters:
id - identifier of item

Retutns:
parent node ID or null if id not found or if it is root node.
o getAction 
public String getAction(java.lang.String id)
Returns the action string for item. Null if id not found.

Parameters:
id - identifier of item

Retutns:
associated action or null if id not found.
o getLabel 
public String getLabel(java.lang.String id)
Returns the label of item. Null if id not found.

Parameters:
id - identifier of item
o openItem 
public void openItem(java.lang.String id)
Opens specified item.

Parameters:
id - identifier of item
o setItemColor 
public void setItemColor(java.lang.String id, java.lang.String strNormColor, java.lang.String strSelColor)
Available in full version only
Sets the color of specified item.

Parameters:
id - identifier of item
strNormColor - normal color
strSelColor - selection color
o setItemFont 
public void setItemFont(java.lang.String id, java.lang.String fName, java.lang.String fStyle)
Available in full version only
Sets the font of specified item.

Parameters:
id - identifier of item
fName - the name of font
fStyle - the style of font, can be combination of "BOLD","ITALIC","PLAIN", separated by commas
o setFontStyle 
public void setFontStyle(java.lang.String id, java.lang.String fStyle)
Available in full version only
Sets the font style of specified item.

Parameters:
id - identifier of item
fStyle - the style of font, can be combination of "BOLD","ITALIC","PLAIN", separated by commas
o setUnderline 
public void setUnderline(java.lang.String id, boolean isUnderline)
Available in full version only
Sets Underline flag for specified item

Parameters:
id - identifier of item
isUnderline - underline flag
o setItemImage 
public void setItemImage(java.lang.String id, java.lang.String im)
Sets image for specified item.

Parameters:
id - identifier of item
im - the name (or number) for image
public void setItemImage(java.lang.String id, java.lang.String im1, java.lang.String im2)
Sets images for specified item.

Parameters:
id - identifier of item
im1 - the name (or number) for opened image
im2 - the name (or number) for closed image
o getLevel 
public int getLevel(java.lang.String id)
Returns zero-based level of item.

Retutns:
level of item or -1 if not found
o isOpen 
public boolean isOpen(java.lang.String id)
Returns true if item is opened

Tree manipulation functions

o deleteSelectedItem 
public void deleteSelectedItem()
Deletes selected item.
o deleteItem 
public void deleteItem(java.lang.String id)
Deletes item with 'id' identifier.

Parameters:
id - identifier of node
public void deleteItem(java.lang.String id, boolean isSel)
Deletes item with 'id' identifier.

Parameters:
id - identifier of node
isSel - If true (default), parent of deleted item get selection, else no selected items leaving in tree.
o insertNewChild 
public void insertNewChild(java.lang.String pId, java.lang.String id, java.lang.String label, java.lang.String action)
Inserts new item into tree without images and options = "SELECT,CALL,CHILD" 
public void insertNewChild(java.lang.String pId, java.lang.String id, java.lang.String label, java.lang.String action, java.lang.String options)
Inserts new item into tree without images 
public void insertNewChild(java.lang.String pId, java.lang.String id, java.lang.String label, java.lang.String action, java.lang.String im0, java.lang.String im1)
Inserts new item into tree with options = "SELECT,CALL,CHILD" 
public void insertNewChild(java.lang.String pId, java.lang.String id, java.lang.String label, java.lang.String action, java.lang.String im0, java.lang.String im1, java.lang.String options)
Inserts new child item for node with 'pId' identifier

Parameters:
pId - parent identifier
id - the identifier for newly created item.
label - the label for newly node
action - the action for newly node
im0 - number (or name) of first image
im1 - number (or name) of second image
options - is copmosition of the next values separated by commas:
SELECT - new item gets selection
CALL - action function for new item will be called after insertion
CHILD - new item has children (for dinamical tree)
CHECKED - node is checket (for checkboxes applet only)
TOP - insert new node at first child position Default value for options is "SELECT,CALL,CHILD"
o insertNewNext 
public void insertNewNext(java.lang.String pId, java.lang.String id, java.lang.String label, java.lang.String action)
Inserts new item into tree without images and options = "SELECT,CALL,CHILD" 
public void insertNewNext(java.lang.String pId, java.lang.String id, java.lang.String label, java.lang.String action, java.lang.String options)
Inserts new item into tree without images 
public void insertNewNext(java.lang.String pId, java.lang.String id, java.lang.String label, java.lang.String action, java.lang.String im0, java.lang.String im1)
Inserts new item into tree with options = "SELECT,CALL,CHILD" 
public void insertNewNext(java.lang.String pId, java.lang.String id, java.lang.String label, java.lang.String action, java.lang.String im0, java.lang.String im1, java.lang.String options)
Inserts new node at position next to the 'pId' item

Parameters:
pId - parent identifier
id - the identifier for newly created item.
label - the label for newly node
action - the action for newly node
im0 - number (or name) of first image
im1 - number (or name) of second image
options - is copmosition of the next values separated by commas:
SELECT - new item gets selection
CALL - action function for new item will be called after insertion
CHILD - new item has children (for dinamical tree)
CHECKED - node is checket (for checkboxes applet only)
Default value for options is "SELECT,CALL,CHILD"
o insertNewRoot 
public void insertNewRoot(java.lang.String id, java.lang.String label, java.lang.String action)
Inserts new root node without images and options = "SELECT,CALL" 
public void insertNewRoot(java.lang.String id, java.lang.String label, java.lang.String action, java.lang.String options)
Inserts new root node without images 
public void insertNewRoot(java.lang.String id, java.lang.String label, java.lang.String action, int im0, int im1)
Inserts new root node with options "SELECT,CALL" 
public void insertNewRoot(java.lang.String id, java.lang.String label, java.lang.String action, int im0, int im1, java.lang.String options)
Inserts new root node at LEVEL=0.

Parameters:
id - the identifier for newly created item.
label - the label for newly node
action - the action for newly node
im0 - number (or name) of first image
im1 - number (or name) of second image
options - is copmosition of the next values separated by commas:
SELECT - new item gets selection
CALL - action function for new item will be called after insertion
CHILD - new item has children (for dinamical tree)
CHECKED - node is checket (for checkboxes applet only)
Default value for options is "SELECT,CALL,CHILD"
o deleteAllNext 
public void deleteAllNext(java.lang.String id)
Available in full version only
Deletes item with 'id' identifier and all items on the same level of the tree.

Parameters:
id - identifier of item

Expanding/collapsing functions

o expandAllChildren 
public void expandAllChildren(java.lang.String id)
Expands all children of item with 'id' identifier (also expands subnodes).

Parameters:
id - identifier of node
o expandAllSelectedChildren 
public void expandAllSelectedChildren(java.lang.String id)
Makes all selected subitems of item with 'id' identifier visible.

Parameters:
id - identifier of node
o collapseAllChildren 
public void collapseAllChildren(java.lang.String id)
Collapses all children of item with 'id' identifier (with it's subnodes.).

Parameters:
id - identifier of node

Cut & Paste functions

o doCut 
public int doCut()
Cuts all selected items from tree.

Retutns:
number of items where cut.
o doPaste 
public int doPaste(java.lang.String id)
Pastes cut items as child of specified node.

Parameters:
id - identifier for node, where past operation will be process

Retutns:
function returning the next codes:
0 - successful
1 - no items was cut
2 - One of cut item is root of the tree
3 - specified item not found
4 - Parent - to - child inserting
public int doPaste(java.lang.String id, java.lang.String new_ids)
Pastes items as child of specified node.

Parameters:
id - identifier for node, where past operation will be process
new_ids - - identifiers for items, separated by commas. Number of items must be equal to number of cut items.

Retutns:
function returning the next codes:
0 - successful
1 - no items was cut
2 - One of cut item is root of the tree
3 - specified item not found
4 - numbers of items in new_ids is incorrect
o clearCut 
public void clearCut()
Clears 'cut' flag on all items

User specified data manipulation functions

o setUserData 
public boolean setUserData(java.lang.String id, java.lang.String key, java.lang.String value)
Sets user-specified data to node.

Parameters:
id - identifier of node
key - key for data
value - data value

Retutns:
true if node was found.
o getUserData 
public String getUserData(java.lang.String id, java.lang.String key)
Returns user-specified data from node.

Parameters:
id - identifier of node
key - key for data

Retutns:
Returns null value if node or data key not found.

Checkboxes operations functions

o isItemChecked 
public boolean isItemChecked(java.lang.String id)
Available in full version only
Returns true if specified item was checked.

Parameters:
id - identifier of item

Retutns:
true if item was checked, false else or if not found
o setCheck 
public void setCheck(java.lang.String id, boolean isCheck)
Available in full version only
Sets check state for specified item

Parameters:
id - identifier of item
isCheck - check state for item
o getAllChecked 
public String getAllChecked(boolean isSubitems)
Available in full version only
Returns list of checked items, separated by commas

Parameters:
isSubitems - if set to true, all items will be returned, else only first checked item without it's children.
o setSubChecked 
public void setSubChecked(java.lang.String id, boolean isCheck)
Available in full version only
Sets all subitems into specified check state

Parameters:
id - identifier of item. If id=null applying for all items in tree
isCheck - new check state
o getAboveChecked 
public String getAboveChecked(java.lang.String id)
Available in full version only
Gets identifiers of all checked items above specified in top-down order.
o getBelowChecked 
public String getBelowChecked(java.lang.String id)
Available in full version only
Gets identifiers of all checked items below specified in top-down order.
o getCheckedParents 
public String getCheckedParents(java.lang.String id)
Available in full version only
Gets identifiers of all checked parents of specified item.
o getCheckedChildren 
public String getCheckedChildren(java.lang.String id)
Available in full version only
Gets identifiers of all checked children of specified item

Tree updating operations

o updateItem 
public void updateItem(java.lang.String id)
Available in full version only
Updates specified item from server
o storeTree 
public void storeTree(java.lang.String treeName)
Available in full version only
Stores current state of tree into internal treeName variable

Parameters:
treeName - the name of internal variable
o dropStaticTree 
public void dropStaticTree(java.lang.String treeName)
Available in full version only
Removes specified tree from static trees list
o restoreTree 
public boolean restoreTree(java.lang.String treeName)
Available in full version only
Restores tree from the treeName internal variable.

Parameters:
treeName - the name of internal variable

Retutns:
Returns false if this variable is't found (was't created by storeTree() call)
o reloadTree 
public void reloadTree(java.lang.String docName)
Available in full version only
Forces a full reload of tree by reading of specified document from the server.

Child applets functions

o showApplet 
public void showApplet(java.lang.String name, int x, int y, int width, int height)
Shows another applet in current applet panel

Parameters:
name - path to code of applet (from current DOC_BASE)
x - x coordinate of child applet
y - y coordinate of child applet
width - width of child applet
height - height of child applet
o hideApplet 
public void hideApplet()
Hides child applet
o getChildApplet 
public Applet getChildApplet()
Returns the instance of child applet

Other functions

o traceTree 
public void traceTree()
Prints contents of current tree into Java log panel.