Directives 

Formats

Where:

Description

Use the VARDROP_BOX directive to create and control a variable drop box on the screen. A variable drop box normally displays a single line on the screen with a down arrow on the right side and allows variable input; that is, the user can select any element from a list of items associated with the variable drop box or can enter any other value. To view the list, the user clicks on the down arrow.

Because a variable drop box list is in drop-down form, it takes a smaller amount of space on the screen than a comparable variable list box. In addition, the system automatically supplies vertical scrollbars if the number of elements overflows the drop-down 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.

See VARDROP_BOX Properties for the list of properties available for manipulating a variable drop box object.

Format 1

Create

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 in 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, the system uses the system default font. Use FNT="*" (asterisk) to set the font as standard text mode fixed font.

Example:

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

vardrop_box 100,@(2,14,12,6)
vardrop_box load 100,"Cat/Dog/Pig/"

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

Format 2

Delete

VARDROP_BOX REMOVE ctl_id[,ERR=stmtref]

Use the VARDROP_BOX REMOVE format to delete a variable drop box.

Format 3

Disable/Enable

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.

Format 4

Set Focus

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.

Formats 5, 6 and 7

Load a Variable Drop Box

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:

vardrop_box load 10000,"Fox/Cat/Dog/Cow/Sheep/Horse/Pig/Elephant/Ant/"
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:
The curly braces enclosing {ALL} are part of the syntax.

VARDROP_BOX LOAD ctl_id,index,{element$ | *}[,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 example, if index is 1, the new element will be inserted before 1 at the start of the list. If index is 0, 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, scrollbars will be automatically be supplied.

To delete or remove a specified element from a variable drop box, use an * (asterisk) in place of the element string:

vardrop_box load 86,4,* ! Deletes item whose index=4 from a variable drop box whose ctl_id is 86

Format 8

Retrieve Element

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 0 is used, PxPlus will return the complete contents of the drop box.

(The ability to use an index of zero to obtain the complete contents was added in PxPlus v7.10.)

Formats 9 and 10

Read Current Selection

Use the VARDROP_BOX READ formats to read which element the user has selected from the variable drop box. 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.

Formats 11 and 12

Write Current Selection

Use the VARDROP_BOX WRITE formats 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.

Format 13

Clear Current Selection

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

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

Note:
This behavior can be altered by use of the '+N' & '-N' mnemonics.

Format 14

Set Focus Notification

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.

Format 15

Report All Changes

VARDROP_BOX AUTO ctl_id[,ERR=stmtref]

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

Format 16

Hide/Show

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.

See Also

VARDROP_BOX Properties
DROP_BOX Create/Control Drop Box
VARLIST_BOX Create/Control Variable List Box