Directives
VARLIST_BOX 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]
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]

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

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 Variable List 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 Refer to the 'FONT' Mnemonic for details.
KEY=char$ Hot key
MNU=ctl CTL value associated with right-click menu event.
MSG=text$ Message line
OPT=char$ Single character parameter/option.(See below)
TBL=char$ Translation characters
TIP=text$ Mouse pointer message. To change the colour, refer to the 'TC'= System Parameter.

The single character parameters for OPT= are:

  • "A"-Auto. Generate CTL signal for every character entered.
  • "D"-Disabled. User cannot access the list box.
  • "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.
dlm_list$ Delimited list of elements to load. String expressions.
element$ Single element to load. Maximum string size 8kb. Use the asterisk (*) instead, to delete an element. For instance, VARLIST_BOX LOAD 86,4,* removes element 4 from VARLIST_BOX 86.
index Position of the element in the list box. Numeric expression. Integers:the index of the 1st element is 1.
mode$ String variable. ProvideX returns a single-character hex value in this variable to report the last method / keystroke the user chose to toggle the check 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 variable list boxes 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. The list of properties available for manipulating a variable list box are described in Control Object Properties, .

   
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, 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 list box that generates a CTL=100 when any item is selected from it. It's loaded with the items Cat, Dog, and Pig.

0010 VARLIST_BOX 100,@(2,14,12,6)
0020 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; e.g.,

0100 VARLIST_BOX LOAD 10000,"Fox/Cat/Dog/Cow/Sheep/Horse/Pig/Elephant/Ant/"
0500 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,{lement$ | *}[,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 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 on a list than will fit the physical screen size of a variable list box, ProvideX automatically supplies scrollbars. To delete or remove a specified element from a variable list box, use an asterisk in place of the element string; e.g.,

VARLIST_BOX LOAD 86,4,* ! Deletes item whose index=4 from list box 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

LIST_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 list box.

This is a +PxPlus Exclusive
   
Formats 9 and 10 Read Current Selection

Use the VARLIST_BOX READ formats 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 described 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 variable list boxes.

*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 ProvideX generate a CTL value whenever the current selection is changed. This lets you track changes in which selection is highlighted in a VARLIST_BOX.