Defining a TREE container
Start a tree-view implementation by defining the TREE
container in the
form definition file.
Create a form specification file containing a TREE
container
bound to a screen array. The screen array identifies the
presentation elements to be used by the runtime system
to display the tree-view and the additional columns.
A TREE
container must be present in the LAYOUT
section of the
form, defining the columns of the tree-view list. The TREE
container must hold at
least one column defining the node texts (or names). This column will be used on the front-end side
to display the tree-view widget. Additional columns can be added in the TREE
container to display node information. The TREE
container attributes must be
declared in the ATTRIBUTES
section of the form.
Secondary form fields have to be used to hold tree node information such as icon image, parent
node id, current node id, expanded flag and parent flag. While these secondary fields can be defined
as regular form fields and displayed in the tree-view list, we recommend that you use
PHANTOM
fields instead. Phantom fields can be listed in the screen-array but do not
need to be part of the LAYOUT
section. Phantom fields will only be used by the
runtime system to build the tree of nodes.
TREE
container:
LAYOUT
TREE mytree ( PARENTIDCOLUMN=parentid, IDCOLUMN=id,
EXPANDEDCOLUMN=expanded, ISNODECOLUMN=isnode )
{
Tree
[name |desc ]
[name |desc ]
[name |desc ]
[name |desc ]
[name |desc ]
}
END
END
ATTRIBUTES
EDIT name = FORMONLY.name, IMAGECOLUMN=image;
PHANTOM FORMONLY.image;
PHANTOM FORMONLY.parentid;
PHANTOM FORMONLY.id;
PHANTOM FORMONLY.expanded;
PHANTOM FORMONLY.isnode;
EDIT desc = FORMONLY.description;
END
INSTRUCTIONS
SCREEN RECORD sr( FORMONLY.* );
END
Tree
layout tag inside a
GRID
container, with a TREE
form element to define attributes in
the ATTRIBUTES
section:LAYOUT
GRID
{
<Tree tv >
Tree
[name |desc ]
[name |desc ]
[name |desc ]
[name |desc ]
[name |desc ]
< >
}
END
END
ATTRIBUTES
TREE tv: mytree,
PARENTIDCOLUMN=parentid, IDCOLUMN=id,
EXPANDEDCOLUMN=expanded, ISNODECOLUMN=isnode;
EDIT name = FORMONLY.name, IMAGECOLUMN=image;
PHANTOM FORMONLY.image;
PHANTOM FORMONLY.parentid;
PHANTOM FORMONLY.id;
PHANTOM FORMONLY.expanded;
PHANTOM FORMONLY.isnode;
EDIT desc = FORMONLY.description;
END
INSTRUCTIONS
SCREEN RECORD sr( FORMONLY.* );
END
The first visual column ("name" in the example) must be the field defining the node names, and
the widget must be an EDIT
or LABEL
.
Several attributes are used to configure a TREE
form
element:
- The
PARENTIDCOLUMN
andIDCOLUMN
attributes are respectively used to identify the form field containing the identifiers of the parent and child nodes, defining the structure of the tree. You must specify form field column names, not item tag identifiers (used to reference a form item in the layout section). If these attributes are not specified, the parent node id and node id field names default respectively to "parentid" and "id". - The
EXPANDEDCOLUMN
attribute can be used to define the form field holding the flag indicating that a node is expanded (opened). - If the
ISNODECOLUMN
attribute is used, it defines the form field indicating that a node has children, even if the program array does not contain child nodes for that parent node. This attribute must be used to implement dynamic filling of tree-views. - The
IMAGEEXPANDED
,IMAGECOLLAPSED
and theIMAGELEAF
attributes are optional attributes defining global images for expanded, collapsed and leaf nodes. You should use these attributes if you want to display the same icons for all nodes. - The
IMAGEEXPANDED
andIMAGECOLLAPSED
instruct the runtime system to set a specific icon when a node gets expanded or collapsed. TheIMAGELEAF
attribute defines the global icon for leaf nodes. This saves the programmer from writing code to display common node images.
Tree-view definition must be completed with form fields declaration.
These must be defined in the ATTRIBUTES
section.
The fields not used for display are declared as PHANTOM
fields.
The tree-view form fields must be grouped in a screen-array
declared in the INSTRUCTIONS
section.
The form fields required to declare a tree-view table are the following.
Description | Field type | Tree attribute | Mandatory | Default name |
---|---|---|---|---|
Text to be displayed for the node | EDIT |
N/A | yes | N/A |
Id of the node | PHANTOM |
IDCOLUMN |
yes | id |
Id of the parent node | PHANTOM |
PARENTIDCOLUMN |
yes | parentid |
Icon image for a node | PHANTOM |
IMAGECOLUMN |
no | N/A |
Node expansion indicator | PHANTOM |
EXPANDEDCOLUMN |
no | no |
Parent node indicator | PHANTOM |
ISNODECOLUMN |
no | no |
The first three fields (node text, parent id and node id) are mandatory, and the first visual (non-phantom) field listed in the screen array will be implicitly used to hold the text of tree-view nodes.
Additional fields (like the "desc"
field in this example) can be defined to
display details for each node in regular columns, that will appear on the right of the tree
widget.
The order of the fields in the screen array of the tree-view does not matter, but it must of course match the order of the corresponding variables in the record-array of the program.
If you need to display node-specific images, define a phantom field
to hold node images and attach it to the tree-view definition
by using the IMAGECOLUMN
attribute. Alternatively
you can globally define images for all nodes with the IMAGEEXPANDED
, IMAGECOLLAPSED
and
the IMAGELEAF
attributes of the TREE
form
element.