Clarion Community Help

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

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.

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.

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