Element: treenode.add_child ( )

Type

treenode

Description

A function to add a new node to a tree window. The new node is added to the tree as a child of treenode, after its current last child, if any.

Parameters

<treenode>.add_child(<class> {,<has_value>
    {,<child_count_known>
    {,<has_dynamic_children) {,<show_expanded>
    {,<label> {,<images> {,<tvalue>
    {,<nvalue> } } } } } } } })

There are a possible 9 parameters to this function (8 of which are optional), supplying the characteristics of the new node:

1. <class> String - The treenode class of the new node.

2. <has_value> Numeric - Whether it is a class node (0) or value node (1). If omitted the value is 0.

3. <child_count_known> Numeric - Whether the child count for the new node will be known when the node gets next expanded.

A 0 means that the count will not be known, so the .populate callback will be called at expand time. The .populate callback will only be called once, unless the <has_dynamic_children> parameter is set.

A 1 means that the child count will be known at expand time, so the .populate callback will not be called. The application must therefore ensure that this node is fully populated, by calls to add_child with this node as the parent.

The default value is 0 (child count not known) for a "class" treenode is 0, and 1 (child count known) for a "value" treenode.

4. <has_dynamic_children> Numeric - Whether the child count for the new node is always dynamic.

When the value is 1, .populate is always called whenever the node is expanded (not only the first time), and all child nodes are destroyed automatically when the node contracts. This also forces the value of the <child_count_known> parameter to 0.

A value of 0 means that after the node has been expanded the first time, .populate is never called again. Its child list may be subsequently changed programmatically by the application however.

The default value is 0.

5. <show_expanded> Numeric - Whether the new node is to be initially displayed expanded. The default value is 0 - No.

6. <label> String - The text appearing in the window alongside the new node. For a new "class" node, this can be an empty string and the "class_label" of this treenode class will be used. For a "value" node, a value should always be provided although the system will derive one if necessary, but this will be meaningless to the application. This has a maximum length of 48 characters. This sets the treenode.label attribute.

7. <images> String[2] - The file names of the new node’s images. One string or a 2-element string array may be passed. The first image is that shown when the node is contracted. The second image (if supplied) is that shown when the image is expanded. If the second is omitted, it is assumed to be the same as the first. Images in tree windows are all displayed with the same dimensions, typically 16 x 16 pixels. They are scaled if necessary.

This sets the treenode.image attribute.

If these values are both empty strings, the default images will be used, either the "class_image" or the "value_image" of the treenode class. The one chosen will depend on the value of the <has_value> parameter.

8. <tvalue> String - The "user" text value for the node. This has a maximum length of 64 characters. This sets the treenode.tvalue attribute which is purely for use by the application. Its default value is null.

9. <nvalue> Numeric - The "user" numeric value for the node. This sets the treenode.nvalue attribute which is purely for use by the application. Its default value is 0.

The resulting new node is returned as the function value.

The code of the function cannot be redefined.