FORM SET DYNAMICLIST

Sets the contents of a dynamic list box.

Syntax

FORM SET DYNAMICLIST < formfield> FROM < setname> \
 FORMAT <expression1> [ HEADING <expression2>] \
 [<expression1_n> [HEADING <expression2_n>]]

Parameters

formfield

A form field in the current form or display. Formfield must have been created as a list box with a drop style of "Dynamic Multi-Column" in the screen painter.

expression1

Any expression. For each member of setspec (up to num members), the value of expression1 is determined and used as the contents of the first column of each list box row. Expression1 can use fields in setspec.

expression2

A character string, or an expression that evaluates to a character string.
This string appears as the column heading for the first column.

- expression1_n

Any expression. For each member of setspec (up to num members), the value of expression1_n is determined and used as the contents of the nth column of each list box row. Expression1_n can use fields in setspec.

- expression2_n

A character string, or an expression that evaluates to a character string.
This string appears as the column heading for the nth column.

Formatting

When a dynamic list box is populated from a result set, the following formatting is applied:

Comments

A multicolumn dynamic list box corresponds to a dynamic list box form field. The data contained within such a form field can be composed of multiple columns, each with its own heading. Unlike other list boxes (static list boxes), dynamic list boxes acquire their data, on demand, from the database and can be used to display (but not update) large amounts of data.

In the screen painter, the Edit List Box dialog enables the dynamic list box to be specified by setting the drop style attribute to "Dynamic Multi-Column".

This command is valid only for a formfield which is a dynamic list box. The list box is set up with a number of columns corresponding to the number of expressions that appear after FORMAT. Each column takes its heading from the HEADING specification. If none is provided and the FORMAT item is a field, then the field's heading is used. Otherwise, the heading is blank. The visible rows of the list box are filled in using all the members of setname starting at the top of the set.

Column widths can be adjusted using a mouse to drag the boundaries between columns. A horizontal scroll bar can appear, if necessary.  Vertical scroll bars appear if there are more members in setname than are visible members.

If the list box is scrolled up or down so that new members ought to appear, these set members are read from the database. This is done relative to the set members currently displayed. That is, the records read from the set do not depend on changes made to the set's current member after the FORM SET DYNAMICLIST command is executed. If a dynamic list box field is displayed, the currently visible members are fetched again in case changes have been made to the database. However, changes to the database do not immediately affect any data currently displayed in a dynamic list box.

If the user selects a row of a dynamic list box, the value of the form field becomes the member number in the set corresponding to the selected row. A Zim program can use this value to position the set on the selected row. If a program assigns a value to a dynamic list box and the corresponding row is not currently visible, the list box scrolls to display the selected item.

The dynamic multi-column list box is supported only in Windows environments. In non-Windows environments, the dynamic multi-column list box behaves as an always dropped list box. The FORM SET DYNAMICLIST command generates an error but the FORM SET LIST command can be performed. Multi-platform code using the dynamic list box should check the value of $ zimos to determine the appropriate course of action.

Example

Assume you want to list the first and last name of all the Customers in an open form called myform that contains a dynamic multi-column listbox widget called dynalist. Assume that you want to use the default column heading for the firstname field and that you want to set the column heading for the lastname column to " SurName". Enter the following:

find all customers -> custset
form set dynamiclist myform.dynalist from \
   custset format firstname lastname heading " SurName"

 

Related Topics