TreeView class

Actions

• Create one or more nodes using wb_create_items(). Each node is given a unique identifier.
• Assign an image source as a handle or path to an image file using wb_set_image().
• Assign icons to a node for normal and selected state using wb_set_item_image().
• Select a treeview node using wb_set_selected().
• Get the index of the currently selected node using wb_get_selected().
• Delete one node or all nodes at once with wb_delete_items().
• Associate an integer, string or float value to a node using wb_create_items() or wb_set_value().
• Retrieve the value associated to a node with wb_get_value().
• Retrieve the node caption using wb_get_text().
• Get the parent of a node using wb_get_parent().
• Get the hierarchical level of a node using wb_get_level().
• Set and retrieve the expanded/collapsed state of a node with wb_set_state() and wb_get_state().
• Show or hide the dotted lines that connect the nodes with wb_set_style() and the WBC_LINES style.

Using tree views

The function used to create a node (a node is a treeview item) is wb_create_items(). This function can create one or more nodes at once by passing an array of arrays as the items parameter. Each element of the second-level array describes the node to be inserted.

The second-level arrays can be described as follows:

array (string caption [, mixed value [, int where [, int imageindex [, int selectedimageindex [, int insertiontype]]]]])

• caption is the node label.
• value (optional) is an integer, string or float value that can be assigned to the node and later retrieved.
• where (optional) is the location where the new node will be inserted (see explanation below).
• imageindex (optional) is the index of the unselected image for the node. If empty or -1, the node will use the default.
• selectedimageindex (optional) is the index of the selected image for the node. If empty or -1, the node will use the default.
• insertiontype (optional) is the type of insertion (see explanation below). the default is zero.

wb_create_items() will return an array of unique integer identifiers. Each identifier refers to a node. These identifiers are actually treeview item handles.

NOTE: The identifier used to reference the node is completely independent of the value parameter.

To retrieve a node text, use wb_get_text() and set the item parameter to the node identifier. Leave it blank to retrieve the text of the currently selected node.

The possible values for insertiontype are:

• 0: where is the insertion level
• 1: where is a sibling of the new node
• 2: where is the parent of the new node

If insertiontype is zero, To insert a node you must specify its insertion level. The minimum level is zero and the maximum is the level of the node with the higher level plus one. The level of an empty list is -1. If you try to assign a invalid level to a node, the level will be automatically lowered to the higher possible level. For example, If the treeview is empty and you try to insert a node with level 1, the item level will be automatically set to 0. Negative levels are always converted  to 0.

You may assign up to two images, imageindex and selectedimageindex, to a treeview item, respectively for the unselected and selected states. If image indices of a given item are not assigned or set to a negative number, default images will be automatically assigned for that node. In addition to showing the selected state of the node, the default images also indicate whether the node has sub-items (image indices 0 and 1) or not (image indices 4 and 5). To use an empty image, use a value that is higher than the last available image on the bitmap.

Example

The code snippet below shows some ways of populating a treeview with items.

// Create several items in a treeview by specifying the insertion level

$items = wb_create_items($tree, array(
    array("Root0",  2001),            // Default insertion level is 0
    array("Child1", 2002, 1),
    array("Child2", 2003, 1),
    array("Root1",  2004),
    array("Child3", 2005, 2),
    array("Child4", 2006, 2),
    array("Child5", 2007, 3),
    array("Child6", 2008, 4),
    array("Root2",  2009),
    array("Root3",  2010),
}

// Create items with parent-child-sibling relationships

$node1 = wb_create_items($tree, array(array("Root4",  3001, 0,      0, 1, 0)));  // At root
$node2 = wb_create_items($tree, array(array("Child7", 3002, $node1, 4, 5, 2)));  // As a child of $node1
$node3 = wb_create_items($tree, array(array("Child8", 3003, $node2, 4, 5, 1)));  // As a sibling of $node2

See also

wb_create_control
wb_create_items
Control classes