User Tools

Site Tools


idh_multichildrelationtree.htm
Navigation:  Templates > Guide to all Templates > Control Templates >====== MultiChildRelationTree control template ====== Previous pageReturn to chapter overviewNext page

MCTabs_shg.jpgidh childidh primaryidh setup1idh setup0

Click on a TAB to see its help

The MultiChildRelationTree control extends the standard 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

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

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

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

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 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 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 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 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 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\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

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

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

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

idh_multichildrelationtree.htm.txt · Last modified: 2021/04/15 15:57 (external edit)