Defining and Updating ValRep Lists for the Tree Widget

The items listed in a tree widget typically represent a nested ValRep list. You can populate the initial list when defining the widget properties in the Component Editor. To make changes to the list, you must use ProcScript to update or rebuild the list.

To build a ValRep list in ProcScript, you need to define the parent nodes before you define the child nodes and leaves. Special functionality is available for the $fieldvalrep function when used in a tree widget, enabling you to partially update the ValRep list of a tree widget, reorder the items in the list, or delete the tree list contents.

It is best to build the complete tree once, for instance in the exec operation, then use only $fieldvalrep to update it, making use of the extended functionality available for $fieldvalrep in tree widgets..

Defining a ValRep List

The preferred way to build an initial ValRep list is to define the parent node and all its children, followed by the next parent node and its children. This ensures that the tree is built correctly and minimizes the time it takes to open a node. However, you can also choose to define all parent-only nodes first, followed by the all the immediate child nodes or leaves (second generation).

You can build a tree structure by level (for example, 1, 1.1, 1.1.1, 1.2, and so on) or by child identifier reference to parent identifier (child-parent). Use $valrep to build a complete tree structure using an associative list of tree items, where each list item has the following syntax:

Value = ParentID!; {+ | - } NodeType!;Representation { ! TTimeStamp}

  • Value—unique string identifying the tree item; for a tree structure built by level, it is a period-separated string of integers, for example, 1.1 or 1.2.2
  • ParentID—Value of the item’s parent node (or empty, if the item is the tree root). For a tree built by level, it must have the format LEVEL_ItemID
  • NodeType—string containing the name of the tree item type (as defined in Type). It can be optionally preceded by:
    • + to insert an Expand button in front of the node, if the node contains children.
    • - to indicate that the node should initially appear expanded.
  • ItemText—string containing the representation (the text) for the tree item.
  • TimeStamp—optional integer used to sort the list by date and time if the T sorting format is used. The maximum value this integer value can hold is FFFF FFFF FFFF FFFF hexadecimal. For example, to represent the combined date/time Nov 16 2007 06:22:48, you can use integer value 20071116062248.

For example, the following statement defines a ValRep list for a tree built using parent child references:

;For readability, each list item is placed on a new line
;ValRep = Value!;NodeType!;Representation

$valrep(MYTREE) = "root=!;NODE!;root
;A=root!;NODE!;A
;B=root!;NODE!;B
;B1=B!;NODE!;B1
;B2=B!;NODE!;B2
;B3=B!;NODE!;B3
;C=root!;NODE!;C"

Updating a ValRep List

Special functionality is available for manipulating the ValRep of a tree widget. It works only for $fieldvalrep and only for the tree widget and enables you to update only specified items in the tree list. You can:

  • Update the tree’s ValRep list (that is, without having to specify the entire ValRep again), when you want to update the information or structure of only a part of the tree.
  • Change the order of nodes in a tree
  • Delete all or part of a tree's contents

Use the following syntax:

$fieldvalrep(TreeField)= "ActionIndicator=;"ValRepListForUpdate

  • TreeField—name of field that uses a tree widget
  • ActionIndicator—value indicating an action that updates the current ValRep of the tree widget; allowed values are:
    • 0—the ValRepListForUpdate is an update on the existing tree; otherwise the current tree is deleted first before building the tree with the new values.
    • -1—delete a tree item or a subset of the tree.
    • -2—reorder the nodes in the existing tree using the indicated order.
  • ValRepListForUpdate—associative list of the items in the tree to update.

For example, the following statement reorders a ValRep list for a tree built using parent child references:

;For readability, each list item is placed on a new line
;$fieldvalrep(Field) = "ActionIndicator = ValRepList

$fieldvalrep(FLD_TREE) = "-2 = 
;root = B!;C!;A
;B=B2!;B3!;B1"

Related Topics