Browse - control template

Top  Previous  Next

 

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:

None

Specifies no locator.

Step

Specifies a single-character locator with no locator control required. When the Browse has focus and the user types a character, the list box advances to the first occurrence of the key field beginning with that character (or the next higher character if no keys match the locator character). Retyping the same character advances the list to the next occurrence of the key field beginning with that character.

 

Use a step locator when the first free key element is a STRING, CSTRING, or PSTRING and you want the search to take place immediately upon the user's keystroke. Step locators are not appropriate for numeric keys. If there is no browse key, the Application Generator converts to no locator. Step locators are case-sensitive only if the key defined as the browse sort is defined as case-sensitive.

Entry

Specifies a multi-character locator that activates when the locator control is accepted (not upon each keystroke). The locator control may be an ENTRY, COMBO, or SPIN. Use an Entry locator when you want to search on numeric or alphanumeric keys, and delay the search until the user accepts the locator control (presses ENTER or TAB). This delayed search reduces network traffic and provides a smoother search in a client-server environment.

 

The locator control should come after the LIST control in the Set Control Order dialog.

 

By default, the locator control is the control whose USE attribute is the first free key element of the browse key. A free component is one that is not range limited to a single value. If there is no such control, the Application Generator converts to a Step locator. If there is no browse key, the Application Generator converts to no locator.

 

When the end user places one or more characters in the locator control, then accepts the control by pressing TAB, pressing a locator button, or selecting another control on the screen, the list box advances to the nearest matching record.

Incremental

Specifies a multi-character locator, with no locator control required (but strongly recommended). Use an Incremental locator when you want to search on numeric or alphanumeric keys and you want the search to take place immediately upon the user's keystroke.

 

The locator control may be a STRING, ENTRY, COMBO, or SPIN, however, any control other than a STRING causes the Incremental locator to behave like an Entry locator--the search is delayed until the control is accepted.

 

With a STRING control, when the list has focus, characters are automatically placed in the locator string for each keystroke, and the list box immediately advances to the nearest matching record. The backspace key removes characters from the locator string.

 

We strongly recommend using a STRING control as the Incremental locator control so the search occurs immediately with each keystroke, and so the user can see the key value for which the Browse is searching.

 

By default, the locator control is the control whose USE attribute is the first free key element of the browse key. A free component is one that is not range limited to a single value. If there is no such control, the Application Generator converts to a Step locator. If there is no browse key, the Application Generator converts to no locator.

Filtered

Specifies a multi-character locator, with no locator control required (but strongly recommended). Use a Filter Locator when you want to search on alphanumeric keys and you want to minimize network traffic.

 

This locator is like an Incremental Locator with a record filter. It specifies a range of values for which to search and returns a limited result set--only those records that fall within the specified range. Each additional (incremental) search character supplied results in a smaller, more refined result set. For example, a search value of 'A' returns all records from 'AA' to 'AZ'; a search value of 'AB' returns all records from 'ABA' to 'ABZ'.

 

The Filtered Locator determines the boundaries for the search based on the user specified search value. The implementation of the boundaries depends on the database driver--for SQL databases, the Filter Locator uses a LIKE; for ISAM databases it supplies upper and lower bounds.

 

The locator returns only the records that match the search value, providing, in effect, a dynamic range limit or filter for the browse.

 

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:

Condition

Any valid Clarion expression. 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.

Key to Use

Optionally, the Key to use to sort the Browse data when the expression is true.

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

Th