Note:   The curly braces enclosing {ALL} are part of format 6 above.

Where:

Because a variable drop box list is in dropdown form, it takes a smaller amount of space on the screen than a comparable variable list box. In addition, ProvideX automatically supplies vertical scrollbars if the number of elements overflows the dropdown box size. Combine these features to optimize screen design when display space is at a premium.

Variable Drop Box Properties

The Apostrophe Operator can be used with the unique logical identifier (ctl_id) to dynamically read and alter a wide variety of control attributes (properties) directly from the programming language. The list of properties available for manipulating a variable drop box are described in Control Object Properties, .

VARDROP_BOX ctl_id,@(col,ln,wth,ht)[,ctrlopt]

Use the format above to create a variable drop box, giving it a unique ctl_id. When a user selects an item from a variable drop box, or enters an item that is not on the list, the associated ctl_id you give to the variable drop box is used to generate a CTL value. Use the FNT= option to establish the font for variable drop box. If you omit the font option, ProvideX uses the system default font. Use FNT="*" (asterisk) to set the font as standard text mode fixed font.

The following example creates a variable drop box that generates a CTL=100 when any item is selected from it. It's loaded with the items Cat, Dog, and Pig.

0010 VARDROP_BOX 100,@(2,14,12,6)
0020 VARDROP_BOX LOAD 100,"Cat/Dog/Pig/"

The user can select any of the three items supplied or enter any other value.

VARDROP_BOX REMOVE ctl_id[,ERR=stmtref]

Use the VARDROP_BOX REMOVE format to delete a drop box.

VARDROP_BOX {DISABLE | ENABLE}ctl_id[,ERR=stmtref]

Use the VARDROP_BOX DISABLE format to gray out a variable drop box so that it will be visible but inaccessible to users. To reactivate it, use VARDROP_BOX ENABLE.

VARDROP_BOX GOTO ctl_id[,ERR=stmtref]

Use VARDROP_BOX GOTO to set the focus on the variable drop box, ready for the user's next input.

Use the VARDROP_BOX LOAD formats below to load items into a variable drop box. The element(s) can be loaded as a delimited string, as an array of string elements, or individually.

VARDROP_BOX LOAD ctl_id,dlm_list$[,ERR=stmtref]

Load List. When you load items from a delimited string, the last character in the string must be the delimiter; e.g.,

0100 VARDROP_BOX LOAD 10000,"Fox/Cat/Dog/Cow/Sheep/Horse/Pig/Elephant/Ant/"
0500 VARDROP_BOX LOAD 15000,"Fox"+SEP+"Cat"+SEP+"Dog"+SEP

VARDROP_BOX LOAD ctl_id,array_name${ALL}[,ERR=stmtref]

Load Array. Use this format to load a complete array into the variable drop box. Note that the curly braces enclosing {ALL} are part of the syntax.

VARDROP_BOX LOAD ctl_id,index,{lement$ | *}[,ERR=stmtref]

Load Element. When you load a variable drop box one element at a time, the index value refers to the element before which the new element is to be inserted. For instance, if index is 1, the new element will be inserted before 1, at the start of the list. If index is 0 (zero), the new element will be appended to the end of the list.

If you have more items in the list than will fit the physical screen size of the variable drop box, ProvideX automatically supplies scrollbars. To delete or remove a specified element from a variable drop box, use an asterisk in place of the element string; e.g.,

VARDROP_BOX LOAD 86,4,* ! Deletes item whose index=4 from drop box 86.

VARDROP_BOX FIND ctl_id,index,var$[,ERR=stmtref]

Use VARDROP_BOX FIND to retrieve a specific element from a drop box.

Retrieve complete contents

VARDROP_BOX FIND ctl_id, 0 ,var$[,ERR=stmtref]

If the index value of zero (0) is used PxPlus will return the complete contents of the drop box.

This is a +PxPlus Exclusive

Use the VARDROP_BOX READ formats to read which element the user has selected from the variable drop box. Note that you must READ the user's selection before your application can use it.

Use a string variable to return information on how the element was selected. The value returned will be:

• $01$ for MOUSE-CLICK.
• 0D$ for Enter .

After this value is read, it resets to $00$ (null).

VARDROP_BOX READ ctl_id,var$[,mode$][,ERR=stmtref]

Read Current Element. Use a string variable in a VARDROP_BOX READ to receive the value of the currently selected element. Use an optional second variable to receive the selection method (i.e., mode$).

VARDROP_BOX READ ctl_id,var[,mode$][,ERR=stmtref]

Read Current Index. Use a numeric variable in a VARDROP_BOX READ to receive the index of the element the user has selected. Once a user has made a selection, it is your responsibility to read it to return the value to your program.

Use the VARDROP_BOX WRITE formats described below to update the current selection in the variable drop box. The value you write can be one of the elements loaded into the drop box or any other value.

VARDROP_BOX WRITE ctl_id,element$[,ERR=stmtref]

Update Current Setting. Use VARDDROP_BOX WRITE with a string expression to update the current selection by element.

VARDROP_BOX WRITE ctl_id,index[,ERR=stmtref]

Update Current Index. Use VARDDROP_BOX WRITE with a numeric expression to update the current selection by element index.

VARDROP_BOX WRITE ctl_id,"" [,ERR=stmtref]

Use this format to clear the currently selected entry in variable drop boxes.

VARDROP_BOX SET_FOCUS ctl_id,alt_ctl[,ERR=stmtref]

Use the VARDROP_BOX SET_FOCUS format to obtain notification when focus changes. SET_FOCUS generates an alternate CTL value whenever focus shifts to the variable drop box.

VARDROP_BOX AUTO ctl_id[,ERR=stmtref]

Use the VARDROP_BOX AUTO format to have ProvideX generate a CTL value whenever the current selection is changed. This lets you track changes in which selection is highlighted in a VARDROP_BOX.

VARDROP_BOX {HIDE | SHOW} ctl_id[,ERR=stmtref]

With the VARDROP_BOX HIDE format, the drop box remains active, but is not displayed. It is still accessible programmatically. Use the SHOW format to restore the display and user access.