• Tree class

The Tree content is internally maintained as a linear list. Dependent entries (children) are immediately ordered below their parent node.

Nodes may be empty and return an event when expanded (opened). This allows an application to dynamically fill the Tree content as needed. Optionally, these nodes may automatically become emptied when collapsed (closed).

The line, add and ins attributes expect an entry definition as an argument. It has multiple fields, separated by the character defined with the delim attribute:

{level}[+-] | Text [ | UDATA ]

The | character represents the delimiter character. It is used to separate different fields. (Please note that by default the TAB character is used as delimiter.)

The level field is an integer specifying the indention level of this entry. Higher indention levels designate a dependent (child) entry.

After the indention level, a + or - character may be present. A + indicates the entry is a node and should default to an expanded state. A - indicates a node entry that is displayed collapsed (the default for a node).

By default, an entry that has no dependent entries (children) is considered a leaf. An entry that has dependent entries is considered a node.

The Text field specfies the text of the entry. It may use HTML content.

If present, the udata field defines a string value for the udata attribute of the entry. If not present, the udata value is unchanged.

activeline : integer, get/set

Currently selected node or leaf (starting with 1, 0 = no entry selected).

Notes:

• After DLG SET, the next DLG DO or DLG DRAW expands any parent node of the selected node or leaf as necessary.
• If necessary, the Tree is scrolled to bring the selected node or leaf into view (requires JDLG version 1.7.4 or newer).
• This is also the node or leaf where a drag originated.

See also cy below.

add[] or add : string, set

Adds new entries to the Tree. Multiple entries are separated by LF (ASCII 10).

If used with a nonzero index, the new entries are added as dependent entries of the specified node (starting with 1). If dependent entries already exist, the new entries are appended after the last dependent entry. If multiple entries are added, the first field of each entry specifies the relative indention level among the new entries.

If used without an index or with a zero index, the new entries are added to the end of the Tree. The first field of each entry specifies the indention level. A zero indention level adds a top-level entry. A nonzero positive indention level adds an entry in the specified level, which presumes that this level or the parent level exists.

ERROR 660 is issued if an invalid entry format is used.

addcy : integer, get

After an add or ins invocation, the addcy attribute may be used to query the location of the first added or inserted line (starting with 1).

Note: Requires JDLG version 1.7.5 or newer.

children[] or children : integer, get

Returns the number of dependent entries for the entry with the specified index (starting with 1). If used without an index or with a zero index, the current entry (cy) is used.

A zero result indicates that the specified entry has no dependent entries (i.e., it is an empty node or a leaf) or does not exist.

class : string, get

Returns "Tree". (Note: JDLG versions before 2.0.0 returned "tree".)

clear : integer or string, set

Deletes all entries in the Tree. The argument is ignored.

content : string, get/set

Used to get or set all entries in the Tree at once.
Multiple entries are separated by LF (ASCII 10).

On DLG GET, the udata values are not returned.

cy : integer, get/set

Currently selected node or leaf (starting with 1, 0 = no entry selected).

When the emptynode value is submitted, cy is set to the related node (starting with 1), while activeline remains set to the current selection if present.

Notes:

• After DLG SET, the next DLG DO or DLG DRAW expands any parent node of the selected node or leaf as necessary.
• This is also the node or leaf where a drag originated.

See also activeline above.

del[] or del : integer, set

Used to delete the entry with the specified index (starting with 1). If used without an index or with a zero index, the current entry (cy) is affected.

A nonzero argument causes the specified entry to be deleted, including all dependent entries if present.

A zero argument causes only the dependent entries to be deleted. The specified entry itself is not deleted. If no dependent entries are present, nothing is deleted.

delim : string, get/set

The fields specifying an entry are separated by this delimiter.
By default, the TAB character (ASCII 9) is used.

emptynode : integer, get/set

If nonzero, this value is returned to the program, along with the path of the Tree object, when an empty node is expanded (opened).

When the emptynode value is submitted, cy is set to the related node (starting with 1), while activeline remains set to the current selection if present.

The default emptynode value is zero.

This may be used to fill an empty node on demand. See also emptynodeauto below.

emptynodeauto : integer, get/set

A program may use the emptynode attribute to fill an empty node on demand (see above).

In this context, if the emptynodeauto attribute is set to a nonzero value, a node that was filled on demand will be emptied automatically as soon as it is collapsed (closed).

The default value is 0.

ins[] or ins : string, set

Inserts new entries. Multiple entries are separated by LF (ASCII 10).

If used with a nonzero index, the new entries are inserted before the specified node or leaf (starting with 1). If dependent entries already exist, the new entries are appended after the last dependent entry.

If used without an index or with a zero index, the new entries are inserted before the current entry (cy).

If multiple entries are inserted, the first field of each entry specifies the relative indention level among the new entries.

ERROR 660 is issued if an invalid entry format is used.

line[] or line : string, get/set

Used to get or set the entry with the specified index (starting with 1). If used without an index or with a zero index, the current entry (cy) is affected.

On DLG SET, the text and the udata values may be modified. If the udata field is present, the specified string value is stored for the udata attribute of the entry.

The indention level in the first field is ignored. The first field may be used to modify the node/leaf state (requires JDLG 1.7.4 or newer). If the entry is a node and the first field does not end with a + or - character, the entry becomes a leaf and all dependent entries are deleted. If the entry is a leaf and the first field ends with a + or - character, the entry becomes an empty node.

On DLG GET, the udata value is not returned.

If the specified entry does not exist, DLG SET has no effect and DLG GET returns an empty string. On DLG SET, ERROR 660 is issued if an invalid entry format is used.

Note: JDLG versions before 1.7.4 ignore the first field on DLG SET and therefore do not support modifying the node/leaf state.

lines : integer, get

Returns the current number of entries in the Tree.

open[] or open : integer, get/set

Used to get or set the expansion state of the entry with the specified index (starting with 1). If used without an index or with a zero index, the current entry (cy) is used.

A nonzero argument expands (opens) a node or indicates that a node is expanded (open).

A zero argument collapses (closes) a node or indicates that a node is collapsed (closed).

If the specified node does not exist, DLG SET has no effect and DLG GET returns zero.

openall[] or openall : integer, set

Used to expand or collapse the entry with the specified index (starting with 1) and all expandable/collapsable dependent entries. If used without an index or with a zero index, all expandable/collapsable nodes in the Tree are expanded or collapsed at once.

Note: Using the openall[] attribute to specify an index requires JDLG version 1.7.4 or newer. JDLG versions before 1.7.4 only support the openall attribute to affect all nodes in the Tree.

Nonzero: Index specified: The specified entry and its dependent entries are expanded. No or zero index specified: All nodes are expanded.

Zero: Index specified: The specified entry and its dependent entries are collapsed. No or zero index specified: All nodes are collapsed.

Invoking openall[] with an index has no effect if the specified node does not exist.

Note: This attribute behaves in a special way until the Tree has been displayed for the first time. In this case, the openall status is marked for delayed execution on the first DLG DO or DLG DRAW.

This has the following implications:

• If used with a nonzero argument (expand all), any subsequent DLG SET open invocations will reset the saved openall status.
• If used with a zero argument (collapse all), subsequent DLG SET open,1 invocations are also marked for delayed execution. This way it is possible to collapse all nodes and then expand selected nodes before the Tree is displayed for the first time.
• If invoked multiple times before the first DLG DO or DLG DRAW, only the last invocation is effective.

parent[] or parent : integer, get

Returns the index of the parent node (starting with 1) of the entry with the specified index (starting with 1). If used without an index or with a zero index, the current entry (cy) is used.

A zero result indicates that the specified entry has no parent (i.e., it is a top-level entry) or does not exist.

rule : integer, get/set

If nonzero, the rule value is returned to the program, along with the path of the Tree object (see also ruleoverride below), when an action is triggered. The kind of action that causes a rule submission is specified by the singleclick attribute (see below).

When a rule is submitted, the cy and activeline attributes are set.

The default rule value is zero.

See also the documentation of the common rule attribute.

ruleoverride : integer, get/set

If nonzero, the rule of a previously focused EditText or ComboBox object is overridden (the Tree rule value combined with the EditText or ComboBox path is returned).

The default ruleoverride value is zero.

For details, please refer to the RuleOverride documentation.

singleclick : integer, get/set

Specifies which action should activate a rule submission:

0		rule submission on mouse button double click, ENTER and SPACE keys
1		rule submission on mouse button single click (see note below), ENTER and SPACE keys
2		rule submission on mouse button double click, ENTER and SPACE keys, UP/DOWN cursor keys
3 (default)		rule submission on mouse button single click (see note below), ENTER and SPACE keys, UP/DOWN cursor keys

Notes:

• A mouse button single click on a node entry only submits a rule if this changes the selection in the Tree.

• Since JDLG version 2.0.16 the mouse button single click behavior is configured by the eloquence.config.delay.singleclick property.

udata[] or udata : integer or string, get/set

User-defined data stored for the entry with the specified index (starting with 1). If used without an index or with a zero index, the current entry (cy) is affected.

DLG SET defines the data type (integer or string).

Note: ERROR 660 is issued if the specified entry does not exist.

useicons : integer, get/set

Nonzero (default): The (platform or look-and-feel specific) node and leaf icons are displayed.

Zero: The node and leaf icons are not displayed.

Note: JDLG versions before 1.7.5 had the side effect that setting the useicons attribute collapsed (closed) all nodes in the Tree.