# Directives

VARLIST_BOX | Create/Control Variable List Box

## Formats

1. | Define/Create: | VARLIST_BOX ctl_id,@(col,ln,wth,ht)[,ctrlopt]
2. | Delete: | VARLIST_BOX REMOVE ctl_id[,ERR=stmtref]
3. | Disable/Enable: | VARLIST_BOX {DISABLE | ENABLE} ctl_id[,ERR=stmtref]
4. | Set Focus: | VARLIST_BOX GOTO ctl_id[,ERR=stmtref]
5. | Load List: | VARLIST_BOX LOAD ctl_id,dlm_list$[,ERR=stmtref]
6. | Load Array: | VARLIST_BOX LOAD ctl_id,array_name${ALL}[,ERR=stmtref] #### Note: The curly braces enclosing {ALL} are part of Format 6.
7. | Load/Delete Element: | VARLIST_BOX LOAD ctl_id,index,{element$|*}[,ERR=stmtref]
8. | Retrieve Element: | VARLIST_BOX FIND ctl_id,index,var$[,ERR=stmtref]
9. | Read Current Selection: | VARLIST_BOX READ ctl_id,var$[,mode$][,ERR=stmtref]
10. | Read Current Index: | VARLIST_BOX READ ctl_id,var[,mode$][,ERR=stmtref]
11. | Update Current Item: | VARLIST_BOX WRITE ctl_id,element$[,ERR=stmtref]
12. | Update Current Index: | VARLIST_BOX WRITE ctl_id,index[,ERR=stmtref]
13. | Clear Current Selection: | VARLIST_BOX WRITE ctl_id,"" [,ERR=stmtref]
14. | Set Focus Notification: | VARLIST_BOX SET_FOCUS ctl_id,alt_ctl[,ERR=stmtref]
15. | Report All Changes: | VARLIST_BOX AUTO ctl_id[,ERR=stmtref]

Where:

@(col,ln,wth,ht) | Position and size of the list box region. Numeric expressions. Column and line coordinates for top left corner, width in number of columns and height in number of lines. Note that width and height are for the total area (box plus text/description). Use line value -1 to display the check box on the tool bar.
alt_ctl | CTL value to generate when the list box gains focus.
array_name$ | Name of array to load into list box. String variable followed by {ALL}.
ctl_id | Unique logical identifier for a variable list box (any integer -32000 to +32000). Avoid integers that conflict with keyboard definitions (e.g. 4 cancels CTL=4 for the F4 key) or Negative CTL Definitions. Use this value with the Apostrophe Operator to access VARLIST_BOX Properties.
ctrlopt | Control options. Supported options for LIST_BOX include:
ERR=stmtref | Error transfer
FMT=def$ | Format definitions depending on the list box type
FNT="font,size[,attr]" | Font name, size, optional properties (See 'FONT' mnemonic)
KEY=char$ | Hot key
MNU=ctl | CTL value associated with right-click menu event
MSG=text$ | Message line
OPT=char$ | Single character parameter/option:
"A" | Auto. Generate CTL signal for every character entered.
"D" | Disabled. User cannot access the list box.
"d" | List box is permanently disabled (cannot be enabled).
"H" | Hide. Do not display the list box.
"s" | Scroll. Allow scroll within resizable/scrollable dialogue box.
"T" | Strip trailing spaces.
"X" | Signal on Exit.
"Z" | Cursor changes to resize pointer if within 4 pixels of control.
TBL=char$ | Translation characters
TIP=text$ | Mouse pointer message (To change the colour, see 'TC'= system parameter)
dlm_list$ | Delimited list of elements to load. String expressions.
element$ | Single element to load. Maximum string size 8KB. The * (asterisk) can be used to delete an element (e.g. varlist_box load 86,4,* removes element 4 from a variable list box whose ctl_id is 86).
index | Position of the element in the list box. Numeric expression. Integers: the index of the 1st element is 1.
mode$ | String variable. The system returns a single-character Hex value in this variable to report the last method/keystroke the user chose to toggle the list box ($01$ for MOUSE-CLICK or $0D$ for Enter).
stmtref | Program line number or statement label to which to transfer control.
var[$] | Receives the value of the selected element (string variable) or index (numeric variable).

## Description

Use the VARLIST_BOX directive to create and control a variable list box on the screen; that is, the user can select any element from a list of items associated with the variable list box or can enter any other value.

Variable List 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 VARLIST_BOX Properties for the list of properties available for manipulating a variable list box object.

## Format 1

Define/Create

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

Use the format above to create a variable list box, giving it a unique ctl_id. When a user selects an item from a variable list box or enters an item that is not on the list, the associated ctl_id you give to the variable list box is used to generate a CTL value.

Use the FNT= option to establish the font for the variable list 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 list box that generates a CTL=100 when any item is selected from it. It is loaded with the items Cat, Dog, and Pig:

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

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

## Format 2

Delete

VARLIST_BOX REMOVE ctl_id[,ERR=stmtref]

Use the VARLIST_BOX REMOVE format to delete a variable list box.

## Format 3

Disable/Enable

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

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

## Format 4

Set Focus

VARLIST_BOX GOTO ctl_id[,ERR=stmtref]

Use VARLIST_BOX GOTO to set the focus on the variable list box, ready for the next user action.

## Formats 5, 6 and 7

Load a Variable List Box

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

VARLIST_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:

> varlist_box load 10000,"Fox/Cat/Dog/Cow/Sheep/Horse/Pig/Elephant/Ant/"
> varlist_box load 15000,"Fox"+sep+"Cat"+sep+"Dog"+sep

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

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

VARLIST_BOX LOAD ctl_id,index,{element$ | *}[,ERR=stmtref]

Load Element. When loading a variable list 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 on a list than will fit the physical screen size of a variable list box, the system automatically supplies scrollbars.

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

> varlist_box load 86,4,* ! Deletes item whose index=4 from a variable list box whose ctl_id is 86

## Format 8

Retrieve Element

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

Use VARLIST_BOX FIND to retrieve a specific element from a list box.

Retrieve Complete Contents

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

If the index value of 0 is used, PxPlus will return the complete contents of the list 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 VARLIST_BOX READ formats below to read which element the user has selected from the variable list box. Note that you must read the user's selection before an application can use it.

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

> $02$ for DOUBLE MOUSE-CLICK
> $0D$ for Enter

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

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

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

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

Read Current Index. Use a numeric variable in a VARLIST_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 VARLIST_BOX WRITE formats below to update the current selection in the variable list box. The value you write can be one of the elements loaded into the list box or any other value.

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

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

VARLIST_BOX WRITE ctl_id,index[,ERR=stmtref]

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

## Format 13

Clear Current Selection

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

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

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

## Format 14

Set Focus Notification

VARLIST_BOX SET_FOCUS ctl_id,alt_ctl[,ERR=stmtref]

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

## Format 15

Report All Changes

VARLIST_BOX AUTO ctl_id[,ERR=stmtref]

Use the VARLIST_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 VARLIST_BOX.

## See Also

VARLIST_BOX Properties
LIST_BOX Create/Control List Box
DROP_BOX Create/Control Drop Box