Check Box-List Box Control

Description

A check box-list box is a control type that displays a list of choices in a list box. Each entry has a check box to the left of the entry. The user can select multiple entries in the list box by checking the check box for each entry that he wants to select.

The check box-list box control would be useful, for example, if you want to prompt the user for a list of fields in which to perform a search. You can turn a list box into a check box-list box, by changing the '^#' directive to '^$', or '^$$'. The syntax for a list box object is:

[.size variable_name^${choice1,choice2,choiceN}]     or,
[.size variable_name^$${choice1,choice2,choiceN}]     or,
[.size variable_name^$choice_variable]     or,
[.size variable_name^$$choice_variable]     or,
[.size variable_name^$choice_array]       or,
[.size variable_name^$$choice_array]

Where choice1, choice2, choiceN are the actual choices, or choice_variable is the name of a string that contains CR-LF delimited choices, or choice_array is the name of an array that contains the choices. The value of variable_name is the list of choices selected by the user. If the ^$ directive is used, variable_name is a string of characters with either a space, or 'T' in each position in the string. The string has a length equal to the number of choices listed in the check box-list box. If an entry in the check box-list box is selected, the corresponding position in the string is set to 'T'. If it is not selected, then the corresponding position in the string is set to a blank value. For example, if the check box-list box has 5 entries, and the 1 st and 3 rd entries are selected by the user, variable_name will be: 'T-T-- ' (where - designates a space). If the ^$$ directive is used, variable_name is a CR-LF delimited list of entries corresponding to the values in the check box-list box selected by user.

If the list of choices contains a blank value, then the list will be truncated at the first blank entry when it is processed.

The size parameter is specified as characters_wide,lines_high. The following script displays two check box-list boxes. One of the controls uses the '^$' directive, and the other uses the '^$$' directive. In addition, the value of the variable that contains the user selections is shown. You can see how in one case this variable contains a string of blanks and 'T's, and in the other case the variable contains a CR-LF delimited string.

colors = "Red,Green,Yellow,Blue,Purple,Orange,Lime,Cyan"
colors = stritran(colors,",",crlf())
dim a_colors[20] as C
a_colors.initialize(colors)
dim a_selected[20] as C
ui_dlg_box("Check Box-List Box",<<%dlg%
{frame=1,1}
{region}
This control uses the '^$' directive.;
[.25,10color1_selected^$colors];
{lf};
Value of check box-list box variable:;
[.25color1_selected];
{endregion}|
{frame=1,1}
{region}
This control uses the '^$$' directive.;
[.25,10color2_selected^$$colors!select_color];
{lf};
Value of check box-list box variable:;
[.25,10colorname^#a_selected];
{endregion}
%dlg%,<<%code%
if a_dlg_button = "select_color" then
a_dlg_button = ""
a_selected.clear()
a_selected.initialize(color2_selected)
end if
%code%)

This script produces this dialog:

In the above script, an event is generated whenever the values in the second check box-list box change (the one that uses the '^$$' directive). The event is called 'select_color'. The event handler for this event executes this code:

if a_dlg_button = "select_color" then
    a_dlg_button = ""
    a_selected.clear()
    a_selected.initialize(color2_selected)
end if

Setting a_dlg_button to "" ensures that the dialog remains open. The next line clears out the a_selected array. Then, this array is initialized with the string, color2_selected. This string contains a CR-LF delimited list of the selections made by the user.

Limitations

Desktop applications only.