| **Navigation:**  [[templates.htm|Templates]] > Guide to all Templates > Control Templates >====== RelationTree control template ====== | [[tplcontrolbrowseqbebutton.htm|{{btn_prev_n.gif|Previous page}}]][[templates.htm|{{btn_home_n.gif|Return to chapter overview}}]][[tplcontrolreltreeupdatebuttons.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

{{c6h0057_shg.jpg|C6H0057_shg.jpg}}[[tplcontrolrelationtree.htm#a2pmr2n|]][[tplcontrolrelationtree.htm#tplcontrolrelationtree primaryfiledetails|]][[tplcontrolrelationtree.htm#tplcontrolrelationtree filedetails|]]

Click on a TAB to see its help

The tree control is a list box formatted to display as a collapsible hierarchical list. This Control template provides an alternative for the Browse-Form paradigm. A single RelationTree control can replace several Browse-Form pairs.

Using the RelationTree Control template, you can specify multiple related files to display on multiple levels (up to 29) of a hierarchical list--//with an associated update procedure for each level//. The related files are declared in the Data / Tables Pad--the Primary (Parent) file and a single chain of related secondary Child files (Parent-Child-GrandChild).

The RelationTree template employs a fully-loaded QUEUE for the root level. The child levels are demand-loaded when a branch is expanded.

{{tipbox.jpg|TipBox.jpg}}

This template is not appropriate for databases with a very large primary file. For large files you should use the BrowseBox Control template.

The plus (+) sign indicates a collapsed level that expands when the user CLICKS on the plus (+) sign. Conversely, the minus (-) sign indicates an expanded level that collapses when the user CLICKS on the minus (-) sign.

To create a tree using the RelationTree Control template:

Place a RelationTree Control template on a window.

This opens the **List Box Formatter**. Use the **List Box Formatter** to enable colorization, icon display, or horizontal scrolling in your tree control (see //The List Box Formatter//). Do //not //use the **List Box Formatter** to populate fields in the tree control.

{{tipbox.jpg|TipBox.jpg}}

The tree control is a single column list, therefore you must specify a column scroll bar rather than a list scroll bar to accomplish horizontal scrolling.

Press the **OK** button on the **List Box Formatter**.

RIGHT-CLICK on the RelationTree Control template and choose **Actions **from the popup menu.

Access the Data / Tables Pad to specify the file schematic for the control.

Specify the Primary (Parent) file and a single chain of related Secondary Child files (Parent-Child-GrandChild).

Complete the RelationTree template prompts.

{{blk2blue.jpg|blk2blue.jpg}}

The RelationTree template provides the following prompts:

**File Details**

**Table Schematic Description**

Enter a descriptive string that will be displayed in the Table Schematic window for this particular control. This allows you to distinguish one control from another when there are multiple controls populated in a single window.

**Tree Heading Text**

An optional text heading at the top of the tree. Tree Heading Text is required to let the user add a record at the root level. Press the **E **button to call the Expression Editor. This dialog is used to help you construct syntactically correct expressions to use in the appropriate prompt.

**Tree Heading Icon**

An optional icon at the top of the tree. Icons must be enabled in the List Box Formatter for this prompt to be enabled.

**Expand Branch**

Specify a keystroke to expand the selected list item--display its children. Press the ellipsis button (...) to select special keys such as ESC, TAB or ENTER. See //Controls and Their Properties--Common Control Attributes--Setting the KEY Attribute// for more information on this dialog.

**Contract Branch**

Specify a keystroke to contract the selected list item--hide its children. Press the ellipsis button (...) to select special keys such as ESC, TAB or ENTER. See //Controls and Their Properties--Common Control Attributes--Setting the KEY Attribute// for more information on this dialog.

**Accept control from Toolbar**

Check this box to accept navigation events and other relation tree control events generated by the //FrameBrowseControl //control template on the APPLICATION's toolbar. See //FrameBrowseControl //for more information on these toolbar buttons and their operation. Clear this box to disable the //FrameBrowseControl //toolbar buttons for this procedure.

**Give option to expand and contract all levels**

Specify the RIGHT-CLICK popup menu for the RelationTree includes "Expand All" and "Contract All" commands.

**Primary Files ' Primary File Details**

**Display String**

The field name or text to display for the primary file level. This may be any valid Clarion expression, for example:

**CLIP(CUST:LastName)&' '&CUST:FirstName**

Press the **E **button to call the Expression Editor. This dialog is used to help you construct syntactically correct expressions to use in the appropriate prompt.

**Update Procedure**

The update procedure to call for the primary file. The procedure may be accessed with the RIGHT-CLICK popup menu automatically provided when you specify an update procedure. The default popup menu text is "Insert," "Change," and "Delete."

The procedure may also be accessed with the RelationTreeUpdateButtons--see below. If you use the RelationTreeUpdateButtons control template, the popup menu inherits the text from the buttons.

**Record Filter**

Type a valid Clarion expression to limit the contents of the list to only those records causing the expression to evaluate to true (nonzero or non-blank). The procedure loops through all displayable records to select only those that meet the filter.

You must [[bind  declare runtime expression string variable .htm|BIND]] any file field, variable, or EQUATE that is used in a filter expression. The **Hot Fields** tab lets you BIND fields.

**Colors**

This tab is only available if you check the **Color Cells** box in the **List Field Properties** in the List Box Formatter.

**Default Colors**

To specify the default colors for the primary file display string, type color EQUATEs (from \LIBSRC\EQUATES.CLW) in the entry fields or press the ellipsis (...) buttons to select colors from the **Select Color** dialog.

**Conditional Color Assignments**

To specify conditional colors for the primary file display string, press the **Insert **button. This opens the **Conditional Color Assignments** dialog.

**Conditional Color Assignments**

This dialog lets you specify the conditional colors for the primary file display string.

**Condition**

Type a valid Clarion expression to evaluate at runtime, then type color EQUATEs (from \LIBSRC\EQUATES.CLW) in the entry fields or press the ellipsis (...) buttons to select colors from the **Select Color** dialog.

Press the **E **button to call the Expression Editor. This dialog is used to help you construct syntactically correct expressions to use in the appropriate prompt.

At run-time these conditions are evaluated, and the colors for the first true condition in the list are used.

**Icons**

This tab is only available if you check the **Icons** box in the **List Field Properties** in the List Box Formatter.

**Default Icon**

To specify the default icon for the primary file display string, type the icon filename in the entry field.

**Conditional Icon Usage**

This dialog lets you specify conditional icons for the primary file display string.

To specify conditional icons for the primary file display string, press the **Insert **button. This opens the **Conditional Icon Usage** dialog.

Press the **E **button to call the Expression Editor. This dialog is used to help you construct syntactically correct expressions to use in the appropriate prompt.

**Condition**

Type a valid Clarion expression to evaluate at runtime.

**Icon**

Type the icon filename in the entry field.

At run-time these conditions are evaluated, and the icon for the first true condition in the list is used.

**Secondary File Settings**

The secondary file settings are identical to the primary file settings. Highlight the secondary file, then press the **Properties **button below the **Secondary Files **list box. See //RelationTree Overview// for information on how to specify the secondary files with the** Select File **dialog.

**RelationTree Embed Points**

The RelationTree Control template provides a comprehensive set of embed points to allow full customization of the control's behavior.