Clarion Community Help

tplcontrolbrowsebox stylesa5ct83ikrsel1jqrf01lzswittbbclassestplcontrolbrowsebox extended optionsbyfe621tplcontrolbrowsebox tipseb6iwttplcontrolbrowsebox sqladvanced

Click on a tab to see its help

The Browse Control template places a “page-loaded” or a “file-loaded” LIST control in a window and generates code to fill the list with data, and to scroll, search, sort, and select the listed items. It generates code to select or filter the data, total the data, update the data directly (edit-in-place), or to call a separate FORM procedure to update the data. It also generates code to conditionally set the colors and icons associated with each row and column in the LIST. The standard Browse behavior is defined by the ABC Library's BrowseClass. See BrowseClass in the ABC Library Reference for more information.

You can use the Browse Control template to manage a page-loaded drop-list simply by setting the DROP attribute to a value greater than zero (0) .

The LIST control's popup menu takes you to the List Box Formatter where you can choose which fields or variables populate the list. You can also define how they appear in the list box (including enabling colorization and Icon display). The Actions tab on the List Properties dialog provides the prompts which let you define the browse box's functionality, including any record filters, range limits, totaling, scroll bar behavior, and locator behavior.

Placing a Browse control on your window

You can place the Browse Control template in a window by clicking on the template control tool , then selecting Browse - File Browsing List Box in the Select Control template dialog. After you select the Browse template, the Application Generator automatically opens the List Box Formatter so you can choose the files, fields and variables to display in the list, and you can design the appearance of the list and its fields.

Populating and Formatting the List Fields

The Populate button lets you add a field or variable to the list box, one field or variable at a time. The Select Column dialog presents the file schematic. Within the schematic, the Browse control appears, with a <;To Do> beneath it. To add a field from a data file defined in the dictionary:

Select the <;To Do> item.

Press the Insert button

Select the file from the Insert File dialog.

If you want to use a Key, press the Key button to select the key from the Key Access dialog. If you do not select a Key, the list is displayed in record order, which also disables the ability to set Range Limits.

Select a field from the Fields list, which appears in the right side of the Select Field dialog. After you select the file, key and field (or variable) the List Field Properties dialog appears. This lets you precisely define the fields appearance within the list.

Actions

The Actions tab of the List Properties dialog (right-click the control and choose Actions) displays the template prompts which let you specify numerous template options, as well as add custom embedded source code for standard list box events, such as moving the selection bar. The dialog contains the following options:

Default Behavior

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.

Quick-Scan Records

Specifies buffered access behavior for file systems that use multi-record buffers (primarily ASCII, BASIC, and DOS). See Database Drivers for more information. These file drivers read a buffer at a time, allowing for fast access. In a multi-user environment these buffers are not 100% trustworthy, because another user may change a record between accesses. As a safeguard, the driver refills the buffers before each record access.

Quick scanning is the normal way to read records for browsing. However, rereading the buffer may provide slightly improved data integrity in some multi-user circumstances at the cost of substantially slower processing.

Loading Method

Select the method used to read the Browse data from the drop-down list.

Page

Page-loading provides near-instantaneous displays for unfiltered data, even for very large datasets. Page-loading uses less memory, because only a few records are held in memory at a time. On the other hand, page-loading can cause erratic vertical scroll bar behavior as well as additional network traffic for each scroll or search action.

File

File-loading provides smooth, accurate vertical scroll bar behavior, plus no additional network traffic when scrolling and searching. File-loading is also quite SQL friendly. On the other hand, file-loading can result in substantial delays and heavy memory usage when reading large datasets.

Accept browse control from Toolbar

Check this box to accept navigation events and other browse 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 and use local navigation controls only. See also SetToolbarTarget.

LIST Line Height

Enter a number in dialog units (unless PROP:Pixels is active) to set the line height of each row generated in the browse box. This option sets the PROP:LineHeight property. You can optionally press the “E” button to call the Expression Editor, which is used to help you construct syntactically correct expressions or variables, used to calculate the desired LIST Line Height.

Locator

A locator lets the user search for specific records in the list box without manually scrolling through the entire list. Locator is only available when browsing a file in Key Order (specify a KEY in the Data / Tables Pad). The search field must be the first free key element, that is, the first component field of the browse key that is not range limited to a single value.

For multi-key browses (the Wizards create them), you may have multiple locators. Use the Conditional Behavior tab to set additional locators for the additional sorts. Choose from the following locator types in the drop-down list:

The Filter Locator performs very well on SQL databases and on high order key component fields; however, performance may suffer if applied to non-key fields or low order key fields of non-SQL databases.

Override default locator control

The default locator control is the control whose USE attribute is the first free key element of the browse key. To override this default and specify a different locator control, check this box. This option is provided in case you have multiple controls with the same free key element as their USE attributes–that is, when you have both ascending and descending keys on the same field.

Select one of the controls to use as the locator control from the New Locator Control list.

Find Method

Only available when the Filtered locator is selected. The Find Anywhere checkbox determines whether the FilterLocator applies the search value to the entire field (field contains search value) or only to the leftmost field positions (field begins with search value). If checked, it applies the “contains” test. If unchecked, it applies the “begins with” test. See FloatRight for more information.

Locator Class

Press this button to override the global Locator Manager setting. See Classes Tab.

Record Filter

Type a valid Clarion expression to limit the contents of the browse 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. Filters are generally much slower than Range Limits.

You must BIND any file field, variable, or EQUATE that is used in a filter expression. The Hot Fields tab lets you BIND fields.

Press the “E” button to call the Expression Editor. This dialog is used to help you construct syntactically correct expressions to use in the Record Filter prompt.

Range Limit Field

In conjunction with the Range Limit Type, specifies a record or group of records for inclusion in the list. Choose a field by pressing the ellipsis (…) button. The range limit is key-dependent. Range Limits are generally much faster than filters.

Range Limit Type

Specifies the type of range limit to apply. Choose one of the following from the drop-down list.

Current Value

Limits the key to the current value of the Range Limit Field.

Single Value

Lets you limit the key to a single value. Specify the variable containing that value in the Range Limit Value box which appears.

Range of Values

Lets you specify upper and lower limits. Specify the variables containing the limits in the Low Limit and High Limit boxes.

File Relationship

Lets you choose a range limiting file from a 1:MANY relationship. This limits the list to display only those child records matching the current record in the parent file. For example, if your list was a list of Orders, you could limit the display to only those orders for the current Customer (in the Customer file).

See Also: Using Range Limits and Filters

Additional Sort Fields

Specify fields to sort on in addition to any Key specified in the Data / Tables Pad by typing an ORDER expression list (a comma delimited list of field names). See ORDER in the Language Reference for more information.

Reset Fields button

Press this button to add Reset Fields. If the value of any Reset Field changes, the procedure refreshes the Browse list. Many Browse events automatically refresh the list; however, if some want another control (such as a Radio button or an entry field) or process to refresh the list, use a Reset Field.

Scroll Bar Behavior button

Pressing this button displays a dialog where you can define the way a scroll bar works.

Choose from Fixed Thumb or Movable Thumb.

For file loaded lists, you automatically get Standard Windows standard (movable thumb) scroll bar behavior. However, since this is not possible for page loaded lists, these options let you choose the behavior that best suits your application.

Fixed Thumb

The thumb (square 3D box in the middle of the scroll bar) remains in the center of the scroll bar. CLICK above the thumb to scroll up one “page.” CLICK below the thumb to scroll down one “page.” DRAG the thumb to the top or bottom of the scroll bar to scroll the top or bottom of the file.

Choose Fixed Thumb when browsing large SQL tables to get best performance.

Movable Thumb

CLICK and DRAG the thumb to scroll a proportional distance in the list. The thumb remains where you drag it, and its position on the scroll bar indicates the relative position within the browse list.

CLICK above the thumb to scroll up one “page.” CLICK below the thumb to scroll down one “page”.

When you choose Movable Thumb, you can also set the Key Distribution to further define how the Browse evaluates the thumb's relative position within the browse list.

Key Distribution

Specifies the distribution of the points of the scroll bar. Choose one of the two predefined distributions (Alpha or Last Names), or Custom, or Run-time from the drop-down list.

Alpha

Defines 100 evenly distributed points alphabetically.

Last Names

Defines 100 points distributed as last names are commonly found in the United States. If the access key is numeric, you should use a custom or run-time distribution.

Custom

Lets you define your own points.

Run-time

Reads the first and last record and computes the values for 100 evenly distributed points in between.

Custom Key Distribution

Lets you specify the break points for distribution along the scroll bar (useful when you have data with a skewed distribution). Insert the values for each point in the list. String constants should be in single quotes ( ' ' ).

Run-time Distribution Parameters

Lets you specify the type of characters considered when determining the distribution points. This is only appropriate when the Free Key Element is a STRING or CSTRING. Check the boxes for the types of characters you wish to include for consideration. Choose from Use alpha characters (Aa-Zz), Use numeric characters (0-9), and Use other keyboard characters.

Step Class Press this button to override the global Step Manager setting. See Classes Tab.

Conditional Behavior

This tab contains a list box that lets you define Browse behavior based on conditions or expressions. Add expressions to the list by pressing the Insert button. This displays a dialog where you define the expression and the associated behavior when that expression evaluates to true (nonzero or non-blank).

At run-time the expressions are evaluated, and the behavior for the first true condition in the list is used.

In this dialog you can specify:

The remaining fields and buttons are the same as the Default Behavior tab.

Hot Fields

When you select the Hot Fields tab, you can specify fields not populated in the list to add to the QUEUE. When scrolling through the file, the generated source code reads the data for these fields from the QUEUE, rather than from the disk. This speeds up list box updates.

Specifying “Hot” fields also lets you place controls outside the Browse that are updated whenever a different record is selected in the list box. Elements of the Primary Key and the current key are always included in the QUEUE, so they do not need to be inserted in the Hot Field list.

This dialog also lets you BIND a field. You must BIND any file field, variable, or EQUATE that is used in a filter expression.

If the field you are BINDing does not need to be included in the default Browse VIEW structure, check the Not in View checkbox.

Colors

This tab is only available if you check the Colors box in the List Box Formatter. It displays a list of the Browse columns that may be colored.

To specify the default colors and any conditional colors, highlight the column's field name, then press the Properties button. This opens the Customize Colors dialog.

Use same color for all columns

Check this box if the color assignments designated here will be for all columns.

Customize Colors

This dialog is available if the Use same color for all columns check box is cleared, and lets you specify the default and conditional Foreground and Background colors for normal (unselected) and selected columns.

Create Greenbar Effect

Check this box to allow two color sets to be used in an alternating row format. If this box is cleared, you can use the Conditional Color Assignments dialog to specify any number of colored rows based on specified conditions.

Alternate columns

Only enabled when the Create Greenbar Effect check box is checked. Check this box to specify that the two color pattern will be used to each column display in addition to each row (producing a checkerboard pattern).

Conditional Color Assignments

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.

Icons

This tab is only available if you check the Icons box in the List Box Formatter. It displays a list of the Browse columns which can display icons.

To specify default icons and any conditional icons, highlight the column's field name then press the Properties button. This opens the Customize Browse Icons dialog.

Customize Browse Icons

This dialog lets you specify the default icon and conditional icons for the Browse column.

Default Icon

The default icon to display. Type the icon (.ICO) filename.

You can also name a variable to use as the default icon, using the !variable format. The variable may be a string type that stores the icon filename, or check the The expression is a number check box if you are referencing a previously named icon assigned to the IconList property.

Conditional Icon Usage

Below the Default Icon section is the Conditional Icon Usage list. This list lets you set icons to apply when an expression evaluates to true (nonzero or non-blank). To add an expression and its associated icon, press the Insert button.

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

Styles

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

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

Create GreenBar Effect

Check this box to create a GreenBar effect (alternating colors on each row) on your list box. You will be prompted to select two styles to use that represent the appearance of each alternating row

Alternate Columns

Check this box to apply an alternate style to every other column defined with the style attribute. You will be prompted to select two styles to use that represent the appearance of each alternating 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.

Default Style

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

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.

Tooltips

This tab is only active if you check the Tooltip box in the List Box Formatter. It displays a list of the Browse columns which may have applied tool tips. Press the Properties button to display the Customize Browse Tooltips dialog.

Tooltip variable

You can specify a default tool tip string value in the List Box Formatter. This entry lets you override the default tooltip to use a value contained in a variable. Press the ellipsis button to select a variable that will contain the text of your column's tool tip.

Totaling

This tab contains a list box that lets you define total fields for a Browse.

Always Calculate Totaling?

Check this box to always calculate browse totaling fields each time the browse box is refreshed. If this box is unchecked, you can apply a condition to the calculation.

Condition

Enter a variable or expression on this line. If the variable or expression evaluates to a non-zero value, the browse totaling loop will be executed, and all total values updated. Press the “E” button to call the Expression Editor. This dialog is used to help you construct syntactically correct expressions to use in the Condition prompt.

Press the Insert button to add total fields. This opens the Browse Totaling dialog where you can define total fields for the Browse.

Total Target Field

The variable to store the calculated total. This can be a local, module, or global variable. You may also use a file field; however, you must write the code to update the file.

Total Type

Choose Count, Sum, or Average from the drop-down list. Count tallies the number of records. Sum adds the values of the Field to Total. Average determines the arithmetic mean of the Field to Total.

Field to Total

The field to sum or average. This box is disabled when the Total Type is Count. Press the “E” button to call the Expression Editor. This dialog is used to help you construct syntactically correct expressions to use in the Field to Total prompt.

Total Based On

Choose Each Record Read or Specified Condition from the drop-down list. This specifies whether to consider every record or only those that meet the Total Condition criteria.

Total Condition

The condition to meet when using a Total based on a specified condition. You can use any valid Clarion expression. You must BIND any file field, variable, or EQUATE that is used in a filter expression. The Hot Fields tab lets you BIND fields. Press the “E” button to call the Expression Editor. This dialog is used to help you construct syntactically correct expressions to use in the Total Condition prompt.

Extended Options

Do not include Primary key in view

Check this box to specify that primary key components are not projected into the view. This is useful when working with SQL tables, and allows valid GROUP BY SQL statements to be generated. See also SQL Advanced Tab

Disable Browse Popup menu

Check this box to disable the popup menu for this Browse Box.

Enable Sort Header (ABC Template Chain Only)

Check this box to allow your list box header to determine the sort order of your list box.

At runtime:

This option is compatible with the List Format Manager and the Auto-Size option discussed below.

This option is not valid with MEMO, BLOB or fields not defined in the browse VIEW structure.

Customize Browse Sort Header

Press this button to access a dialog that allows you to control the sort headers for each individual column. You can disable any or all columns, and specify custom sorts for local variables and other special program conditions. See Customize Browse Sort Header

Disable Auto Size Browse Columns?

If you have enabled the Auto Size Column feature in the Global Properties, check this box if you wish to disable this feature for this procedure's Browse Box.

Disable List Format Manager?

If you have enabled the List Format Manager in the Global Properties' App Settings, check this box to disable this feature

List Format Manager

If the List Format Manager is enabled in the Global Properties, and not disabled, press this button to access the List Format Manager dialog.

IPDRV Options

If you are using the IP Driver in your application, press this button to access the IPDRV Options dialog.

SQL Advanced Tab

When the Browse Control template is using an SQL Accelerator driver, SQL Accelerator Drivers convert standard Clarion file I/O statements and function calls into optimized SQL statements, which they send to their backend SQL servers for processing. This means you can use the same Clarion code to access both SQL tables and other file systems such as TopSpeed files. It also means you can use Clarion template generated code with your SQL databases.

This tab control (which only appears when you are using an SQL table) allows you to extend the optimized SQL statements generated by the template.

The following options are available:

Query Elements

The Query Elements items allow you to assign special SQL clauses to your browse box result set. This is accomplished by selecting an existing element in the SQL table, and assigning it to a special function or expression. See Runtime SQL Properties for Views using SQL Drivers

View Field

Select an SQL column from the drop list provided.

Assignment

Enter a valid SQL statement to assign to the View Field.

Example: 'count(*)'

The example above is equivalent to:

“SELECT count(*) FROM tablename”

Grouping

If you have enabled the Do not include Primary key in view option in the Browse controls' Extended Options, the following options are enabled.

Group

To add a GROUP BY clause to the template generated SQL statement, check this box and enter the appropriate SQL string in the Grouping Definition field. Press the “E” button to call the Expression Editor. This dialog is used to help you construct syntactically correct expressions to use in the Group prompt.

Having

To add a HAVING clause to the template generated SQL statement, check this box and enter the appropriate SQL string in the Having Definition field. You must set a GROUP BY definition first to enable the HAVING clause. Press the “E” button to call the Expression Editor. This dialog is used to help you construct syntactically correct expressions to use in the Having prompt.

See GROUP BY and HAVING and VIEW support for aggregate functions for more information and examples.

Classes Tab

Use the Classes tab to override the global settings for the Class. See Classes Tab.