| **Navigation:**  [[templates.htm|Templates]] > Guide to all Templates > Control Templates >====== MultiChildRelationTree control template ====== | [[tplcontrolbrowsebox ext ipdrv.htm|{{btn_prev_n.gif|Previous page}}]][[templates.htm|{{btn_home_n.gif|Return to chapter overview}}]][[idh multichildrelationtreebutton.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

{{mctabs_shg.jpg|MCTabs_shg.jpg}}[[idh multichildrelationtree.htm#idh child|]][[idh multichildrelationtree.htm#idh primary|]][[idh multichildrelationtree.htm#idh setup1|]][[idh multichildrelationtree.htm#idh setup0|]]

Click on a TAB to see its help

The MultiChildRelationTree control extends the standard [[tplcontrolrelationtree.htm|RelationTree]] control with a number of new enhancements and developer control. Like the standard RelationTree, the MultiChildRelationTree 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 MultiChildRelationTree control can replace several Browse-Form combinations.

Using this 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 multiple chains of related secondary Child files (Parent-Child-GrandChild). But more so, **This template allows multiple child tables to be attached to a single primary record. See the shipping example for an illustration of this.**

The MultiChildRelationTree 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 register the MultiChildRelationTree Control template:**__

Access the Template Registry from the IDE Tools menu. In the Template Registry window, press the **Register** button, and locate and select the MCRTREE.TPL file.

__**To create a tree using the MultiChildRelationTree Control template:**__

Place a **MultiChildRelationTree** 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.

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

Specify the Primary (Parent) file and optional chains of related Secondary Child files (Parent-Child-GrandChild).

Complete the MultiChildRelationTree template prompts.

{{gold.jpg|gold.jpg}}

The MultiChildRelationTree template provides the following prompts:

**General Tab 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.

**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.

**Enable Tree Root**

Check this box to create a root (Single top branch). All primary file records will be displayed directly below this root. More options for the Root branch is found on the template Root tab.

**Disable Primary Table Level**

Check** **this box to remove the primary table from the template interface and allow the creation of the tree using only the Secondary (child) tables, in order to create a "multi-parent" tree. This is very handy when a dummy table is used as the primary table and you don't want to show any Root node based on this table.

**Tree Line Height**

Enter a number in dialog units (unless PROP:Pixels is active) to set the line height of each row generated in the relation tree. This option sets the [[prop lineheight.htm|PROP:LineHeight]] property.

**Expand Key**

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 Key**

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.

**Initial State**

Select Expanded or Contracted from the drop list options. This is the initial state of the relation tree as the window is first opened.

Select from the following **Popup** options:

**Expanding/Contracting via popup**

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

**Use One Item for Both Actions**

This box is enabled if you have enabled the **Expanding/Contracting via popup **option. Check this box to allow one popup item to toggle the Expanding/Contraction action, or leave blank to create distinct menu items for each action.

**Expand/Contract Popup priority**

Specify a number relative to the other selections below that will determine the //order// that this popup menu item will appear in the structure. A value of 1 would designate it as the first item.

**Refresh Via Popup**

Check this box to add a refresh option to the popup menu.

**Refresh Popup Priority**

Specify a number relative to the other selections below that will determine the //order// that this popup menu item will appear in the structure. A value of 1 would designate it as the first item.

**Root Tab Options**

The options listed here are only made available if you had checked the **Enable Tree Root **option in the template's **General** tab.

**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 ellipsis** **button to call the //Select Column// dialog. 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.

**Colors Sub Tab**

If you have enabled the **Colors **option in the List Box Formatter, you can specify colors for the Root node as follows:

**Default Colors**

This dialog lets you specify the default and conditional Foreground and Background colors for normal (unselected) and selected columns.

**Conditional Colors**

Below the default colors section is the **Conditional Color Assignments **list. This list lets you set colors to apply when an expression evaluates to true (nonzero or non-blank). To add an expression and its associated colors, press the **Insert **button.

At run-time the expressions are evaluated, and the colors for the first true expression are used.

**Styles Sub Tab**

This tab is only available if you check the **Style** box in the List Box Formatter. It displays a list of the BrowseBox columns that may have applied styles.

{{tipbox.jpg|TipBox.jpg}}

**To specify the default styles and any conditional styles, highlight the column's field name, then press the Properties button. This opens the Customize BrowseBox Styles dialog. A default style may also be defined on the List Box Formatter Appearance tab.**

**Default Style**

This entry lets you specify the default style to be used for the column.

**Style Type**

Use the drop list to select //Local List// or //Style Number//. The //Local List// displays the descriptions of the styles that you created in the [[tpllistboxstyles.htm|Listbox Styles]] dialog. You can also reference the styles by //Style Number// only.

**Style or Style Number**

Based on the Style Type selected, select a style's description or number from the drop list control.

**Conditional Styles**

This list lets you define the styles to apply when an expression evaluates to true (nonzero or non-blank). To add an expression and its associated colors, press the Insert button.

**Condition**

Provide a valid Clarion expression that when evaluates to true (nonzero or non-blank) will cause the Style to be applied.

**Style Type**

Use the drop list to select //Local List// or //Style Number//. The //Local List// displays the descriptions of the styles that you created in the [[tpllistboxstyles.htm|Listbox Styles]] dialog. You can also reference the styles by //Style Number// only.

**Style or Style Number**

Based on the Style Type selected, select a style's description or number from the drop list control.

At run-time the expressions are evaluated, and the styles for the first true expression are used.

All Styles must be defined. For more information on defining styles see [[tpllistboxstyles.htm|Listbox Styles]].

**Primary Level Tab ' Primary File Details**

**Level Title**

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

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

Press the ellipsis** **button to call the //Select Column// dialog. This dialog is used to help you construct syntactically correct expressions to use in the appropriate prompt. All expressions must be prepended with an exclamation point as shown above.

**Field to Display**

The field name to display for the primary file level. This may also be any valid Clarion expression. Press the ellipsis** **button to call the //Select Column// dialog. This dialog is used to help you construct syntactically correct expressions to use in the appropriate prompt.

**Advanced Display**

If the text to display is part of a more complex expression, or even perhaps the result of a procedure call, this button opens an appropriate embed point to use to construct the value to return.

**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.

There is also **Range Limit** support in the MultiChild Relation Tree. Set the Range Limit options as you would in a standard Browse Box. Click [[tplcontrolbrowsebox.htm#standardrangelimitoptions|here]] for more information.

**Icons**

This tab is only available if you select an **Icon** in the **Appearance** tab in the List Box Formatter.

**Use different icons for Expand and Contract**

Check this box to enable you to select different icons to display when the relation tree is in an expanded or contracted state. This option also cascades to the //Conditional Icons// option.

**Default Icon**

To specify the default icon for the primary file display string, first select the type of icon to use.

**Icon Type**

In the drop list provided, select from //Built-in// (pick from a built-in IDE list), //File// (a standard .ICO file), //Variable// (using the //!variable// format), or //External// (to reference icons in a composite *ICO file, using the //filename.ico[x]// format).

**Conditional Icons**

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 ellipsis button to call the //Select Column// dialog. 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 and Icon**

In the drop list provided, select from //Built-in// (pick from a built-in IDE list), //File// (a standard .ICO file), //Variable// (using the //!variable// format), or //External// (to reference icons in a composite *ICO file, using the //filename.ico[x]// format).

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

**Colors Tab**

This tab is only available if you check the **Colors **box in the **Flags** area located in the //List Box Formatter//.

**Default Colors**

To specify the default colors for the primary file display string, type color EQUATEs (from \LIBSRC\[[commonly used equates.htm|EQUATES.CLW]]) in the entry fields or press the ellipsis (...) buttons to select colors from the //Select Color// dialog.

**Conditional Colors**

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

**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 ellipsis** **button to call the //Select Column// dialog. 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.

**Styles Tab**

This tab is only available if you check the **Style** box in the List Box Formatter. It displays a list of the BrowseBox columns that may have applied styles.

{{tipbox.jpg|TipBox.jpg}}

**To specify the default styles and any conditional styles, highlight the column's field name, then press the Properties button. This opens the Customize BrowseBox Styles dialog. A default style may also be defined on the List Box Formatter Appearance tab.**

**Default Style**

This entry lets you specify the default style to be used for the column.

**Style Type**

Use the drop list to select //Local List// or //Style Number//. The //Local List// displays the descriptions of the styles that you created in the [[tpllistboxstyles.htm|Listbox Styles]] dialog. You can also reference the styles by //Style Number// only.

**Style or Style Number**

Based on the Style Type selected, select a style's description or number from the drop list control.

**Conditional Styles**

This list lets you define the styles to apply when an expression evaluates to true (nonzero or non-blank). To add an expression and its associated colors, press the Insert button.

**Condition**

Provide a valid Clarion expression that when evaluates to true (nonzero or non-blank) will cause the Style to be applied.

**Style Type**

Use the drop list to select //Local List// or //Style Number//. The //Local List// displays the descriptions of the styles that you created in the [[tpllistboxstyles.htm|Listbox Styles]] dialog. You can also reference the styles by //Style Number// only.

**Style or Style Number**

Based on the Style Type selected, select a style's description or number from the drop list control.

At run-time the expressions are evaluated, and the styles for the first true expression are used.

All Styles must be defined. For more information on defining styles see [[tpllistboxstyles.htm|Listbox Styles]].

**Hot Fields Tab**

The options in this tab are identical to the standard Hot Fields dialog found in the Browse Box control. Any field that needs to be accessed individually within a filter or in a call to any procedure from this template must be included in the Hot Fields list.

**Child Levels Settings**

The Child Levels 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.

Select from the following options:

**Level Title**

The text to display for the child table level. Expressions are also valid here. Press the ellipsis** **button to call the //Select Column// dialog. This dialog is used to help you construct syntactically correct expressions to use in this prompt.

**Field to Display**

The field name to display for the primary file level. This may also be any valid Clarion expression. Press the ellipsis** **button to call the //Select Column// dialog. This dialog is used to help you construct syntactically correct expressions to use in the appropriate prompt.

**Advanced Display**

If the text to display is part of a more complex expression, or even perhaps the result of a procedure call, this button opens an appropriate embed point to use to construct the value to return.

**Custom Join**

A powerful feature of this template is that you can use tables that are not necessarily related in the dictionary to build your relation tree. If you have specified a Custom Join in the table schematic for this table, you can specify the type of join used here by pressing this button. In the //Custom Join// dialog you select the Key and Key Field used, and then specify the join criteria. The Join of this table to the primary table can be based on a //Clear Value//, a //Fixed Value//, or a //Variable Value//.

For example:

Assume that a //User// and //Computers// table are not related to any table in the dictionary.

You can show them at the same tree level by creating a "Dummy" root:

DummyRoot

|

Users

|   \---ComputersAssigned

|                       \---ComputersAlias

|

Computers

The computer is assigned to a user with a matching UserId and ComputerId

Users and Computer are //not// be related to DummyRoot. The custom join will use the "Clear Value" option to show //all// Users and //all// Computers.

In the case of //ComputersAssigned// and //ComputersAlias//, the template uses smart logic to show them all like one entry because the relation between ComputersAssigned and ComputersAlias is a Many to One.

**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.

**Level Root**

An optional text heading can be added to each child table to display at the top of the child node. For example:

{{childroot.jpg|childroot.jpg}}

Press the ellipsis** **button to call the //Select Column// dialog. This dialog is used to help you construct syntactically correct expressions to use in the appropriate prompt.

The **Level Root Format** button opens an additional dialog to control the Colors, Icons and Styles used in the Child Root. The options are identical to the [[idh multichildrelationtree.htm#idh primary|Primary Root]] dialog.

**RelationTree Embed Points**

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