|
VARLIST_BOX |
Create/Control Variable List Box |
|
1. |
VARLIST_BOX ctl_id,@(col,ln,wth,ht)[,ctrlopt] | |
|
2. |
VARLIST_BOX REMOVE ctl_id[,ERR=stmtref] | |
|
3. |
VARLIST_BOX {DISABLE | ENABLE} ctl_id[,ERR=stmtref] | |
|
4. |
VARLIST_BOX GOTO ctl_id[,ERR=stmtref] | |
|
5. |
VARLIST_BOX LOAD ctl_id,dlm_list$[,ERR=stmtref] | |
|
6. |
VARLIST_BOX LOAD ctl_id,array_name${ALL}[,ERR=stmtref] Note:
| |
|
7. |
VARLIST_BOX LOAD ctl_id,index,{element$|*}[,ERR=stmtref] | |
|
8. |
VARLIST_BOX FIND ctl_id,index,var$[,ERR=stmtref] | |
|
9. |
VARLIST_BOX READ ctl_id,var$[,mode$][,ERR=stmtref] | |
|
10. |
VARLIST_BOX READ ctl_id,var[,mode$][,ERR=stmtref] | |
|
11. |
VARLIST_BOX WRITE ctl_id,element$[,ERR=stmtref] | |
|
12. |
VARLIST_BOX WRITE ctl_id,index[,ERR=stmtref] | |
|
13. |
VARLIST_BOX WRITE ctl_id,"" [,ERR=stmtref] | |
|
14. |
VARLIST_BOX SET_FOCUS ctl_id,alt_ctl[,ERR=stmtref] | |
|
15. |
VARLIST_BOX AUTO ctl_id[,ERR=stmtref] |
|
@(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:
| ||||||||||||||||||||||||||||||||||
|
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). |
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.
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.
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.
VARLIST_BOX REMOVE ctl_id[,ERR=stmtref]
Use the VARLIST_BOX REMOVE format to delete a variable list box.
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.
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.
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
VARLIST_BOX FIND ctl_id,index,var$[,ERR=stmtref]
Use VARLIST_BOX FIND to retrieve a specific element from a list box.
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.)
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.
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.
VARLIST_BOX WRITE ctl_id,"" [,ERR=stmtref]
Use this format to clear the currently selected entry in a variable list box.
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.
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.
VARLIST_BOX Properties
LIST_BOX Create/Control List Box
DROP_BOX Create/Control Drop Box