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

Where:

• Formatted List Boxes.
• Listview List Boxes.
• Treeview List Boxes.

Dynamic 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. Complete lists of the properties available for manipulating LIST_BOX, LISTVIEW, or TREEVIEW objects are described in Control Object Properties, .

LIST_BOX OPT= Settings

The following single character OPT= settings are used to refine list box definitions and to establish Listview controls (OPT="r" for Report Style or OPT="l" for List Style ), and Treeview controls (OPT="e"):

"!"	Exclamation Mark. Treeview controls only.. Data has bitmaps or icons; e.g. 0020 LIST_BOX 100,@(10,10,10,10),OPT="e,!" If the OPT= setting includes "!"(as above), you can use LIST_BOX LOAD statements to define bitmaps or icons for individual elements of a Treeview. ProvideX displays the bitmap or icon to the left of the related element. Include the image filename in LIST_BOX WRITE statements to select (highlight) a Treeview element with a bitmap or icon; e.g., 0030 LIST_BOX LOAD 100,"{Cat.bmp}Cat/{Dog.bmp}Dog/{Hog.ico}Pig/" or 0040 LIST_BOX WRITE 100,"{Cat.bmp}Cat" Bitmaps or icons you define for individual elements using LIST_BOX LOAD statements will override any default bitmaps or icons (defined using FMT=). See Treeview Format Options.
"#"	Pound Sign. Users can select more than one entry from the list box. (This option is not supported for Treeview.) If OPT="#", and items were loaded in a single string, then when you read/write the element(s) highlighted in the list box, the item(s) will be returned in the variable using either the delimiter from the LIST_BOX LOAD statement or, as default delimiter, the SEP character. Example: 0010 PRINT 'CS'; BEGIN; LIST 0020 LIST_BOX 100,@(2,16,12,6),OPT="#" 0030 LIST_BOX LOAD 100,"Cat/Dog/Pig/"; WAIT 1 0040 ! If you read the ITEMS$ now, the returned value is null: 0050 LIST_BOX READ 100,ITEMS$;WAIT 1; PRINT ITEMS$+"Before Write" 0060 LIST_BOX WRITE 100,"Cat"; WAIT 1 ! Select "Cat" 0070 LIST_BOX READ 100,ITEMS$; PRINT ITEMS$ 0080 LIST_BOX LOAD 100,2,*; WAIT 1 ! Removes "Dog" 0090 LIST_BOX WRITE 100,2 ! Select second item 0100 LIST_BOX READ 100,ITEMS$; WAIT 1; PRINT ITEMS$ 0110 ESCAPE -:run Before Write Cat/ Cat/Pig/
"|"	Pipe. Treeview controls only. Show connecting lines. LIST_BOX 100,@(10,10,10,10),OPT="e,|" If OPT="|", the Treeview displays connecting lines between various nodes of the tree.
"~"	Tilde. No height adjustment. Normally, a list box displays an integral number of lines. If OPT="|", the list box will not be forced to show only complete lines. ProvideX will truncate the last line horizontally (i.e., displaying a partial line to ensure that the height of the list box matches the size you defined).
"A"	Auto signal is on. ProvideX returns a signal on all changes in the list box.
"b"	Suppress column heading or expansion and collapse buttons – Listview (Report Style) and Treeview controls only. In Listview (Report Style) "b" suppresses the column header buttons; e.g., LIST_BOX 100,@(10,10,10,10),OPT="r,b" When you use "b" for a Treeview, the "+" and " -" buttons (for the expansion and collapse of the tree) are suppressed; e.g., LIST_BOX 100,@(10,10,10,10),OPT="e,b"
"B"	List box has no border or frame.
"d"	List box is permanently disabled. (Cannot be enabled.)
"D" or "1"	List box is initially disabled.
"e"	Define Treeview control object. By default, a Treeview shows the data as a tree with tree level {+}and {-} buttons (for the expansion and collapse of the tree). A Treeview displays and maintains the data in sorted order. When you add elements to a Treeview list box, ProvideX automatically creates and inserts the elements. Bitmaps or icons are optional. See also Treeview List Boxes.
"E"	Edit Mode - Treeview controls only. This enables automatic editing; i.e., the user can double click on an item to change its value.The editing of items does not support the following input options: Format mask processing Justification (right/center) Password masking Input start at end (append text) Force numeric or uppercase Reverse input Input length limitations Signal on all keystrokes
"h"	List box is permanently hidden. (Cannot be shown.)
"H"	List box is initially hidden.
"l"	Define Listview (List Style) control object. Lowercase L defines a List Style Listview control object. This is a simple multi-column list of the first element of data. It lists a series of data columns as items from which the user can select. (Columns wrap from the bottom of one to the top of the next column.) You can include an optional bitmap or an icon in the first column (i.e., as the first piece of data in the row / line). See Listview List Boxes.
"L"	List box is initially locked.
"p"	Highlight partial match(es) – Listview controls only. If OPT="p", WRITE directives with strings are interpreted as selecting / highlighting those items whose leading characters match the data you are writing. For example, if you write "ABC", then the first item which starts with “ABC”is highlighted (or all items that start with "ABC" if OPT="#" (above) is also set to allow users to make multiple selections); e.g., LIST_BOX 100,@(10,10,10,10),OPT="l,p,#" or LIST_BOX 100,@(10,10,10,10),OPT="r,p"
"q"	Disable sorting – Listview (Report Style) and Treeview controls only. In Listview (Report Style), that suppresses the use of the column header button to sort data; e.g., LIST_BOX 100,@(10,10,10,10),OPT="r,q" In Treeview, items added to the list are always added at the end of their respective trees; e.g., LIST_BOX 100,@(10,10,10,10),OPT="e,q"
"r"	Define Listview (Report Style) control object. Lowercase R defines a Report Style Listview control object. This has column headings and variable column widths and alignments. Each column of data has an optional {column-header}button for sorting data. You can include an optional bitmap or an icon for the first column (i.e., as the first piece of data in the row/line). See Listview List Boxes.
"s"	List box will scroll in a ‘Scrollable' window.
"T"	Strip trailing spaces when reading or writing data for a list box.
"v"	First Column highlight – Listview (Report Style) controls only; e.g., LIST_BOX 100,@(10,10,10,10),OPT="r,v" Use OPT='v'to control the highlight style for individual list boxes and override any system-wide use of the print mnemonic '+V'. If OPT='v', the user can only click in the first column to highlight a row in the list box. See also, '+V' & '-V' Mnemonics.
"V"	Full Row highlight – Listview (Report Style) controls only. LIST_BOX 100,@(10,10,10,10),OPT="r,V" Use OPT='V'to control the highlight style for individual list boxes and override any system-wide use of the print mnemonic '-V'. If OPT='V', the user can click in any column to highlight a row in the list box. See also, '+V' & '-V' Mnemonics.
"X"	Signal when focus exits from the list box
"Z"	Cursor changes to resize pointer if within 4 pixels from the edge of the control.

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

Use this format to define or create a list box and give it a unique identifier in ctl_id. When a user selects an item from a list box, the item's associated ctl_id is used in generating a CTL value. Use an integer or numeric expression between -32000 and +32000 for the ctl_id. Depending on the implementation, the list box may also require some control options:

• FNT= sets the font for the list box. If you omit the font option, ProvideX uses the system default font. Use FNT="*" (asterisk) to set the font to the standard text-mode fixed font.
• FMT= defines columns and/or rows, titles and images depending on the type of list box required. For specific format definitions, see Formatted List Boxes, Listview List Boxes, or Treeview List Boxes.
• OPT= expands the definition. See LIST_BOX OPT= Settings.

0010 PRINT 'CS'; LIST
0020 LIST_BOX 100,@(2,14,12,6),FNT="*"
0030 LIST_BOX LOAD 100,"Dog/Cat/Pig/"; WAIT 1
0040 LIST_BOX WRITE 100,"Cat"; WAIT 1
0050 LIST_BOX LOAD 100,1,*; WAIT 1
0060 END

LIST_BOX REMOVE ctl_id[,ERR=stmtref]

Use the LIST_BOX REMOVE format to delete a list box. (To delete an individual element, use the LIST_BOX LOAD directive instead.)

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

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

LIST_BOX GOTO ctl_id[,ERR=stmtref]

Use the LIST_BOX GOTO format to set the focus on a list box, ready for the next user action.

Use the LIST_BOX LOAD formats below to add or delete the elements in a list box. The formats set up the elements using a delimited string, an array of string elements or individually.

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

Load Via Delimited String. When you load elements into a list box from a delimited string, the last character in the string must be a delimiter. That ending delimiter must be identical to the separator between the elements in the string; e.g.,

LIST_BOX LOAD 11000,"Fox/Cat/Dog/Cow/Sheep/Horse/Pig/Elephant/Ant/"
LIST_BOX LOAD 15000,"Fox"+SEP+"Cat"+SEP+"Dog"+SEP

If loading data with images:

Listview	When you load a Listview list box, you can include an optional bitmap or icon to be displayed to the left of the row/line. Enclose the bitmap or icon path and filename in curly braces as the first piece of data in the row.
Treeview	If you create a Treeview with OPT="!", then you can use LIST_BOX LOAD statements to define optional bitmaps or icons for individual elements of a Treeview.

Example:

0030 LIST_BOX LOAD 100,"{cat.ico}Cat/{dog.bmp}Dog/{hog.bmp}Pig/"

ProvideX displays these images to the left of the related elements in the Treeview. Bitmaps or icons you define for the individual elements in LIST_BOX LOAD statements will override any default FMT= images in a LIST_BOX definition. For more information, see LIST_BOX OPT= Settings, Treeview List Boxes.

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

Load Via Array. When an array is loaded into a list box, the curly braces in {ALL} must be included in the syntax.

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

Load/Delete Index Element. When a list box is loaded one element at a time, the index value refers to the index before the element to be inserted. (Use a value of 1 to insert an element at the start of the list. If the value of the index is 0 (zero), the element will be appended to the end of the list.)

If you have more elements on the data list than the physical screen size of the list box can display at one time, ProvideX automatically supplies vertical scrollbars. To remove or delete individual elements from the box, use LIST_BOX LOAD with an asterisk instead of the element string; e.g.,

LIST_BOX LOAD 86,4,* ! * deletes element 4 from list_box 86

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

Use a string variable to get the specific element’s text from a list box. By passing a specific element number, you can retrieve the text of that element into a string variable

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

Use LIST_BOX READ formats to read which element in the list box has been selected. The string variable mode$ returns a hex value showing how the element was selected. Possible values are described below:

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

Once this value is read, it is reset to $00$.

ProvideX returns an EOM value and event when the user hits the Insert or Delete keys, Insert returns $2D$, Delete returns $2E$.

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

Read Current Selection.

When you use LIST_BOX READ with a string variable, you can return the value of the currently selected element and the method used to make the selection (mode$).

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

Read Current Index.

If you use LIST_BOX READ with a numeric variable, you can return the element by index and the user's method of selection (mode$) from the list box.

Use the LIST_BOX WRITE formats to make the element the current selection, highlighted in the list box.

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

Write Selection.

The string expression to write an element to a list box as the current selection must exactly match the value of one of the elements in the list box. Otherwise ProvideX returns Error #11: Record not found or Duplicate key on write.

Writing Treeview data with bitmaps or icons.

If you create a Treeview with OPT="!", then you can use LIST_BOX LOAD statements to define optional bitmaps or icons for individual elements of a Treeview. ProvideX displays the image to the left of the element. When you write the current selection, enclose the image filename in curly braces, preceding the individual data element; e.g.,

0030 LIST_BOX WRITE 100,"{Cat.ico}Cat"

Bitmaps and icons you define for individual elements in LIST_BOX LOAD statements will override any FMT= images. For more information, see Format 1: Define/Create List Box and Treeview Format Options.

LIST_BOX WRITE ctl_id,index[,ERR=stmtref]

Write Index.

You can write the current selection to a list box by using its index.

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

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

LIST_BOX SET_FOCUS ctl_id,alt_ctl,[,ERR=stmtref]

Use the SET_FOCUS format to set an alternate CTL value to be generated whenever focus shifts to the list box.

LIST_BOX AUTO ctl_id[,ERR=stmtref]

Use the LIST_BOX AUTO format to have ProvideX generate a CTL value automatically whenever the current selection is changed. Use this to track changes to the highlighted selection in a list box.

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

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

Example:

LIST_BOX 10000,@(5,5,35,10),FMT="L15 R5 N12 C3/B5 L25"

The width in the format definition is the display/window width, not the number of characters in the text.

Load the contents of the columns in a formatted list box from a delimited data string (positional data for the entries in the list box). The default delimiter is the SEP character (e.g., $8A$). To change this, use the SEP= option. Note that the value for the field delimiter (in this case, SEP) and the value signaling the end of row (in this case, $0A$) must be different. For the previous example:

"1123 East Main"+SEP+"Ont"+SEP+" 123.45"+SEP+SEP+"*"+SEP+"North Bay"+SEP+$0A$

Position	Width	Contents	Alignment
Col 1, Line 1	15	1123 East Main	L = Left
Col 2, Line 1	5	Ont	R = Right
Col 3, Line 1	12	123.45	N = Numeric/Decimal
Col 4, Line 1	3	*	C = Centered
Col 1, Line 2	5	<spaces>	B = Insert Blanks (5=Length)
Col 2, Line 2	25	North Bay	L = Left

To change the colour of any field in a formatted list box, simply prefix the data with one of the mnemonics in the following chart.

Colour	Foreground Mnemonic	Background Mnemonic
Black	'BLACK'	'_BLACK'
Red	'RED'	'_RED'
Green	'GREEN'	'_GREEN'
Yellow	'YELLOW'	'_YELLOW'
Blue	'BLUE'	'_BLUE'
Magenta	'MAGENTA'	'_MAGENTA'
Cyan	'CYAN'	'_CYAN'
White	'WHITE'	'_WHITE'
Light Gray		'SF'+'_WHITE'

0010 OPEN (1)"INVOICE",(2)"CUST"
0020 LIST_BOX 10,@(10,10,60,10),FMT="L8 B2 L20 C10 N15 C3"
0030 READ (1,END=1000)INV_ID$,INV_CUST$,INV_DATE$,INV_AMT,INV_STS$
0040 READ (2,KEY=INV_CUST$)CST_NAME$
0050 LET L$=INV_ID$ ! 1st column
0060 LET L$+=SEP+CST_NAME$ ! 2nd column
0070 LET L$+=SEP+INV_DATE$ ! 3rd column
0080 LET X$=STR(INV_AMT:"$###,##0.00-")
0090 IF INV_AMT<0 THEN LET X$='RED'+X$ ! Column is red if negative
0100 LET L$+=SEP+X$
0120 LET X$='SF'+TBL(POS(INV_STS$="ISP"),"",'_GREEN','_BLUE','_RED')+INV_STS$
0130 LET L$+=SEP+X$
0140 LIST_BOX LOAD 10,0,L$
0150 GOTO 0030
1000 CLOSE (1),(2)
1010 INPUT *; IF CTL<>4 THEN GOTO *SAME

Two Listview styles are supported:

0200 LIST_BOX 100,@(2,14,12,6),FNT="*",OPT="l"
...
0500 LIST_BOX 15000,@(10,10,20,10),OPT="r",ERR=2000

This is a +PxPlus Exclusive (build 9200)

When a column starts with a 'PICTURE' mnemonic the system will insert the image associated with the mnemonic into the list view row.

For Example

The list box to the right was generated by the program shown below displays a check mark for those sales reps making over 100K and a Star for those over $500K

NOTE: The position/size values within the 'PICTURE' mnemonic are ignored thus are generally set to zero. Also make sure all pictures used within a list view should be the same size.

Text and bitmaps may be interspersed through the field contents allowing text to appear before and after the images.

0010 BEGIN
0020 LET FORMAT$="[SalesRep]10 [Name]18 [Dept]C8 [Quota]R14 [Merit]10"
0030 LIST_BOX 10,@(5,5,60,15),OPT="rV",FMT=FORMAT$,FNT="*guifont"
0040 WHILE 1
0050 READ ("/users/mike king/demo/data/salesrep",END=*BREAK)
0060 IF YTDSALES>=100000 THEN LET QUOTA$="!checkedbox" ELSE LET QUOTA$="!xinbox"
0070 LET QUOTA$='PICTURE'(0,0,0,0,QUOTA$)
0080 IF YTDSALES>500000 THEN LET QUOTA$+='PICTURE'(0,0,0,0,"!Star")
0090 LIST_BOX LOAD 10,0,SALESREPCODE$+SEP+NAME$+SEP+DEPARTMENT$+SEP+STR(YTDSALES:"$#,###,##0")+SEP+QUOTA$+SEP
0100 WEND
0110 INPUT *

LIST_BOX 10000,@(5,5,35,10),FMT="[Company]L10 [Vendor]C6 [Amount]#R12",OPT="r"

Listview FMT= settings can include the following
 

LIST_BOX 10000,@(5,5,35,10),FMT="[Company]L10 ..."

indicates that column 1 is left justified and 10 columns wide.

Note: Internal ProvideX bitmaps are generally 20 pixels wide by 16 pixels high.

0100 LET X$="[Custno]L10 [Name]L20 [Address]L20 [Category]C10 [Amount]R10"
0110 LIST_BOX 10000,@(10,10,50,10),OPT="r",FMT=X$,FNT="Arial,1"
0120 PRINT "Scroll to see columns"; WAIT 5
0130 LIST_BOX REMOVE 10000; END

The following chart describes FMT= settings for line 0100in the previous example:

0010 OPEN (1)"."
0020 SET_PARAM 'SD'
0030 LIST_BOX 10,@(5,5,25,10),OPT="r",FMT="[Name]L15 {} [Size]R7"
0040 LOOP:
0050 READ (1,END=0150)F$
0060 IF MID(F$,-1)=DLM
0060:   THEN LET B$="!File",SZ$="<dir>";
0060:            GOTO LOADIT
0070 LET B$=""
0080 OPEN INPUT (2,ISZ=-1)F$
0090 LET X$=FIN(2)
0100 CLOSE (2)
0110 LET SZ$=STR(DEC(X$(1,4)))
0120 LOADIT:
0130 LIST_BOX LOAD 10,0,F$+SEP+B$+SEP+SZ$+SEP
0140 GOTO LOOP
0150 CLOSE (1)
0160 ESCAPE

aaa
aaa/bbb
aaa/bbb/ccc

If you then load aaa/bbb/ddd, ProvideX only creates one new entry for aaa/bbb/ddd (since aaa and aaa/bbb already exist). If you add aaa/xxx/iiid, ProvideX creates two new entries: one for aaa/xxx and one for aaa/xxx/iii. When an item from a branch is selected, the list box READ returns the item, including its parent branches. In the example above, selecting ccc would return

"aaa/bbb/ccc/".

When loading a Tree view with lots of data, it is often advisable to pre-sort the data and load the tree view without the sort option enabled.

Treeview Format Options

Use FMT= settings to define default images to be displayed in the tree (optional). When adding bitmaps and icons, enclose the image name in curly braces. Use a leading exclamation point (!) to identify the image as internal, or specify the relative path and filename to access an image file that is external. For more information on internal/external images and recognized image file types, refer to Displaying Bitmaps/Icons.

Filenames are mandatory in FMT={images$}clauses. Place them inside curly braces in a pipe-separated list; e.g.,

LIST_BOX A,@(x,y,10,10),OPT="e",FMT="{Cat.ico|Dog.bmp|Pig.bmp} "

Null values in FMT={images$}are not allowed. For instance, FMT={||Pig.bmp} generates an Error #23: Missing/Invalid variable.)

Ensure that all bitmaps or icons in the same LIST_BOX control are the same size (mandatory). If you include different sizes, ProvideX treats the size of the first bitmap/icon as the size of all images for a given list box.

If you use internal bitmaps, ProvideX converts the background light gray to match the background colour of the LIST_BOX entries. You can define up to six default bitmaps or icons in Treeviews. The order of the images determines when they are used:

1. Default overall bitmap or icon: always used with any listed entries that do not have subordinates.
2. Default bitmap or icon for items with subordinates.
3. Default bitmap or icon for items with subordinates if the tree level is expanded (i.e., shown) in Treeview.
4. Bitmap or icon for entries that do not have any subordinates when the item is selected.
5. Bitmap or icon for entries that have subordinates when selected.
6. Bitmap or icon for entries that have subordinates when selected and level is expanded.

0010 LIST_BOX 10,@(5,5,25,10),OPT="e|",
0010:FMT="{!diskette|!File|!File_open}",SEP=DLM
0020 LET F=1,D$="."
0030 NXTDIR:
0040 SET_PARAM 'SD'=1
0050 OPEN (F)D$
0060 NXTFILE:
0060:READ (F,END=ENDDIR)F$
0070 IF F$(1,1)="."
0070:THEN GOTO NXTFILE
0080 IF MID(F$,-1)<>DLM
0080:THEN LIST_BOX LOAD 10,0,PTH(F)+DLM+F$;
0080:GOTO NXTFILE
0090 LET D$=PTH(F)+DLM+F$
0100 F++
0110 GOTO NXTDIR
0120 ENDDIR:
0120:CLOSE (F)
0130 F--
0140 IF F>0
0140:THEN GOTO NXTFILE
0150 ESCAPE