Directives

Note:
These formats also apply to List View List Boxes, Report View List Boxes and Tree View List Boxes.

Formats

Where:

Description

Use the LIST_BOX directive to create and control list boxes on the screen. A list box is used to display a pre-set series of selections or elements from which the user can choose. Depending on the implementation of OPT= and FMT= control options, the LIST_BOX directive can be used to create standard list boxes, as well as the following list box types:

Formatted List Boxes

List View List Boxes

Tree View List Boxes

Note:
A standard Windows list box can only use vertical scrollbars; however, you can use List View list boxes or grids to incorporate horizontal scrollbars into applications.

Users can select any element from a list of items you assign to the list box; however, variable input is not allowed; that is, the user can only select, not enter, values.

If you need a list box that allows both variable input and selection from a list, see VARLIST_BOX Create/Control Variable List Box.

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.

For the properties available for manipulating the different list box types, see the following:

LIST_BOX OPT= Settings

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

Format 1

Define/Create List Box

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:

Example:

The example below creates a list box that generates a CTL=100 when an item is selected from it and uses FNT= text mode fixed font. The list box is loaded with the items Dog, Cat, and Pig. The programmer writes Cat as the initial/highlighted selection and removes Dog from the top of the list.

print 'CS';
list
list_box 100,@(2,14,12,6),fnt="*"
list_box load 100,"Dog/Cat/Pig/";
wait 1
list_box write 100,"Cat";
wait 1
list_box load 100,1,*;
wait 1
end

Note:
The LIST_BOX formats described below apply to all list box types.

Format 2

Delete

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.)

Format 3

Disable/Enable  

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.

Format 4

Set Focus

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.

Formats 5, 6 and 7

Load/Delete

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:

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:

List View	When you load a List View 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.
Tree View	If you create a Tree View with OPT="!", then you can use LIST_BOX LOAD statements to define optional bitmaps or icons for individual elements of a Tree View.

Place the bitmap or icon filename in the data, enclosing the path and filename 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 information on internal/external images and recognized image file types, see Displaying Bitmaps/Icons.

Example:

list_box load 100,"{cat.ico}Cat/{dog.bmp}Dog/{hog.bmp}Pig/"

PxPlus displays these images to the left of the related elements in the Tree View. 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.

See LIST_BOX OPT= Settings and Tree View 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,{element$ | * } [,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, PxPlus 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:

list_box load 86,4,* ! * deletes element 4 from a list_box whose ctl_id is 86

Note:
When a LIST_BOX LOAD is issued with no index, the current contents of the list box will first be cleared and the new data will replace it. Setting the 'LoadPoint property to a non-zero value alters this behavior.

If 'LoadPoint is set to -1, the data included with the LIST_BOX LOAD will be appended to the list.

If 'LoadPoint is set to -2, the data included with the LIST_BOX LOAD will replace the current contents of the list starting at the item number set in the 'Item property, which will be updated to the next item number once the load is complete (new items will be added, if required).

If 'LoadPoint is set to a value > 0, the data will be inserted into the list at the point specified and the value in 'LoadPoint will be reset.

This functionality allows list boxes to load a block of records at a time.

(The LoadPoint property was added in PxPlus v8.11.)
(The LoadPoint setting of -2 was added in PxPlus 2019.)

Format 8

Find Element

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

(The ability to issue a FIND 0 was added in PxPlus v7.10.)

Formats 9 and 10

Read

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$.

PxPlus 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.

Note:
If LIST_BOX READ includes an OPT="A" setting, all changes will have an effect on the EOM or mode$ value returned during the read.

Formats 11 and 12

Write Current Selection

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, PxPlus returns Error #11: Record not found or Duplicate key on write.

Writing Tree View Data with Bitmaps or Icons

If you create a Tree View with OPT="!", then you can use LIST_BOX LOAD statements to define optional bitmaps or icons for individual elements of a Tree View. PxPlus 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:

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. See Format 1: Define/Create List Box and Tree View 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.

Note:
A WRITE to the list box using an index of 0 (zero) will reset all highlighted lines.

Format 13

Clear Current Selection

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

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

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

Format 14

Set Focus Notification

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.

Format 15

Report All Changes

LIST_BOX AUTO ctl_id [,ERR=stmtref]

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

Format 16

Hide/Show

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.

Formatted List Boxes

Formatted list boxes are created using the format definition option in the LIST_BOX definition. The information in the FMT= def$ string expression describes each of the columns and/or rows. Each column is formatted with an alignment code, usually followed by a width in column units. The list of columns is a space-separated string enclosed in quotation marks. Each new row is delineated by a / (slash).

Example:

list_box 10000,@(5,5,35,10),fmt="L15 R5.00 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:
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.

Example:

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.00	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

For data you want hidden, use S (with no length) as the alignment character to indicate that a column is to be skipped. (The data is present but not displayed. The user cannot see or gain access to the column.)

Note:
The maximum length of an element in a formatted list box is 255 bytes.

Color in a Formatted List Box

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

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

Normally, background colors are dimmer than their respective foreground colors. If you want to use the background (dimmer) color for foreground text, prefix the color with the 'SB' (Set Background) mnemonic. If you want to use foreground color brightness for the background, prefix the color with the 'SF' (Set Foreground) mnemonic. All colors are reset to LIST_BOX default standards at the end of each column.

Note:
This is not standard text plane color handling. To get light gray background, use 'SF'+ '_WHITE' since '_WHITE' yields bright white.

Example:

The following example creates a formatted list box using the standard definition elements:

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

List View List Boxes

List View list boxes are created by setting OPT=char$ in the definition. See Format 1: Define/Create List Box.

Two List View styles are supported:

Example:

This example shows definitions for both List View styles:

0200 list_box 100,@(2,14,12,6),fnt="*",opt="l"
...
0500 list_box 15000,@(10,10,20,10),opt="r",err=2000

Multiple Bitmap Support

The List View control also allows for the inclusion of multiple bitmaps within the data along with a number of new properties. When a column starts with a 'PICTURE' mnemonic, the system inserts the image associated with the mnemonic into the List View row.

Example:

The list box above was generated by the program shown below. It 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 and thus are generally set to 0 (zero). In addition, 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.

begin
FORMAT$="[SalesRep]10 [Name]18 [Dept]C8 [Quota]R14 [Merit]10"
list_box 10,@(5,5,60,15),opt="rV",fmt=FORMAT$,fnt="*guifont"
while 1
     read ("/users/mike king/demo/data/salesrep",end=*break)
     if YTDSALES>=100000 \
          then QUOTA$="!checkedbox" \
          else QUOTA$="!xinbox"
     QUOTA$='picture'(0,0,0,0,QUOTA$)
     if YTDSALES>500000 \
          then QUOTA$+='picture'(0,0,0,0,"!Star")
     list_box load 10,0,SALESREPCODE$+sep+NAME$+sep+DEPARTMENT$+sep+str(YTDSALES:"$#,###,##0")+sep+QUOTA$+sep
wend
input *

(The ability to insert multiple images in a List View was added in PxPlus v9.00.)

Note:
The unique logical identifier (ctl_id) assigned during the creation of a List View list box can be used with the Apostrophe Operator to dynamically read and alter a wide variety of control attributes (properties). See LIST_VIEW Properties.

List View Format Options 

Use FMT= to define List View column widths, titles and the placement of an optional bitmap or icon. You can include a series of space-separated column definitions with an optional column title in [square brackets], alignment code and width specification:

list_box 10000,@(5,5,35,10),fmt="[Company]L10 [Vendor]C6 [Amount]#R12",opt="r"

List View FMT= settings can include the following:

Load List View data into the columns from SEP -delimited data strings. See Format 6: Load via Delimited String.

Example:

In the following example, PxPlus automatically supplies a horizontal scrollbar where the total width of the data columns is greater than the list box display width:

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 0100 in this example:

Color in List View (Report Style)

List View (Report Style) list box supports colors on a per column basis. Color mnemonics can precede the data in the column or be intermixed with the data itself so more than one foreground/background color can be set up per column. If a background color mnemonic precedes all the data in a column, then the entire background of the column will be set to that color. See Color in a Formatted List Box.

Row Highlighting in List View (Report Style)

List View (Report Style) list box supports first column highlight (where the user must click on the first column to highlight the row) and full-line highlight (where the user can click on any column to highlight the row). You can set highlighting style for individual list boxes by using OPT= either "v" or "V" when you create the control object or you can control the highlighting style system-wide by setting the print mnemonics ' -V' and ' +V'. See Format 1: Define/Create List Box and '+V' & '-V' mnemonics.

Example: List View (Report Style)

     open (1)"."
     set_param 'SD'
     list_box 10,@(5,5,25,10),opt="r",fmt="[Name]L15 {} [Size]R7"
LOOP:
     read (1,end=0150)F$
     if mid(F$,-1)=dlm \
          then B$="!File",SZ$="<dir>";
                  goto LOADIT
     B$=""
     open input (2,isz=-1)F$
     X$=fin(2)
     close (2)
     SZ$=str(dec(X$(1,4)))
LOADIT:
     list_box load 10,0,F$+sep+B$+sep+SZ$+sep
     goto LOOP
     close (1)
     escape

Horizontal Bar Charts in List Views

The List View control can also be used to display horizontal bar charts using the 'FILL' mnemonic. This mnemonic, when included in the text of a List View field, will generate a horizontal bar. (Horizontal bar chart support in List Views was added in PxPlus 2017.)

The length of the bar and fill color are defined by the parameters passed with the 'FILL' mnemonic. The first parameter defines the length of the bar as a percentage of the List View column. A value of 100 results in the bar covering the complete column, 50 will cover half of the column, etc. If the column is resized, the bar length will be adjusted accordingly. The second and optional third parameters define the color of the bar with the second parameter representing the color for the top of the bar and the third parameter, if present, the bottom of the bar. If the third parameter is omitted, the bottom of the bar will be automatically generated by the system to make the bar appear slightly three-dimensional.

Multiple 'FILL' mnemonics may be supplied to create multiple bars within the column. Any portion of the bars that exceeds the total column width will be truncated.

Example:

For this example, let us assume that we are dealing with client information that is comparing CurrentYTDSales against PriorYTDSales with the following data:

If we want to present a simple graph in the List View, we might code something like this:

0010 begin
0020 print 'CS'
0030 let lv=10
0040 list_box lv,@(5,5,60,5),fmt="[ID]10C [Name]20 [Performance]20 [Sales]10R",opt="r"
0050 while 1
0060 read data id$,name$,CurrentSales,PriorSales,end=*break
0070 let sales$=str(CurrentSales:"$##,##0")
0080 let pct=(100*CurrentSales)/PriorSales
0090 let bar$='fill'(pct,"Green")
0100 list_box load lv,0,id$+sep+name$+sep+bar$+sep+sales$+sep
0110 wend
0120 input *
0130 data "0001","First Client",80000,100000
0140 data "0002","Secondary Client",55000,50000
0150 data "0003","Third Client",45000,90000

This would result in a List View something like this:

If we want to include the percentage as a number following the bar, we could make the following change:

0090 let bar$='fill'(pct,"Green")+str(pct)+"%"

This would result in the following:

Notice that the percentage does not show on the second line because the bar completely fills the column width. In fact, the percentage for ID 0002 is 110%. To resolve this, we need to adjust the bar display percentage to allow for both the full bar and the text. This can be done by factoring the bar percentage itself:

0090 let bar$='fill'(pct/1.5,"Green")+str(pct)+"%"

This would result in the following:

Let us assume we want to enhance this as follows:

If the Percentage is < 70%, display the bar in Red, and for any percentage over 100%, display the bar in Yellow.

To do this, we could change line 90 and add 95 as follows:

0090 let bar$='fill'(min(pct,100)/1.5,tbl(pct<70,"Green","Red"))

0095 let bar$+='fill'(max(pct-100,0)/1.5,"Yellow")+str(pct)+"%"

This would result in the following:

Note:
Negative percentage values will be treated as 0 (zero) for both displaying and sorting.

Tree View List Boxes

A Tree View control object can be created by setting OPT="e" in the definition of a list box. See Format 1: Define/Create List Box. Tree Views provide a hierarchical view of the data using a collapsible tree structure to represent a list box. As items are loaded into the Tree View, PxPlus automatically parses the entries based on your given delimiter and creates all intervening tree levels required.

Example:

If you use a slash as your delimiter and load the single entry aaa/bbb/ccc, PxPlus will generate three entries in the Tree View:

aaa
aaa/bbb
aaa/bbb/ccc

If you then load aaa/bbb/ddd, PxPlus only creates one new entry for aaa/bbb/ddd (since aaa and aaa/bbb already exist). If you add aaa/xxx/iiid, PxPlus 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.

Note:
The unique logical identifier (ctl_id) assigned during the creation of a Tree View list box can be used with the Apostrophe Operator to dynamically read and alter a wide variety of control attributes (properties). See TREE_VIEW Properties.

OPT="e" establishes a Tree View definition. Several other OPT = settings can be used to refine the definition:

See LIST_BOX OPT= Settings.

Tree View 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, see Displaying Bitmaps/Icons.

Filenames are mandatory in FMT={images$} clauses. Place them inside {curly braces} in a pipe ( | ) separated list:

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, PxPlus treats the size of the first bitmap/icon as the size of all images for a given list box.

If you use internal bitmaps, PxPlus converts the background light gray to match the background color of the LIST_BOX entries. You can define up to six default bitmaps or icons in Tree Views. 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 Tree View.

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.

Note:
When OPT="e,!" (Tree View data has bitmaps or icons), any images you set up for individual elements in Tree View LIST_BOX LOAD and WRITE statements will override the default FMT= bitmap or icon for the individual element.

Example: Tree View

     list_box 10,@(5,5,25,10),opt="e|",fmt="{!diskette|!File|!File_open}",sep=dlm
     F=1,D$="."
NXTDIR:
     set_param 'SD'=1
     open (F)D$
NXTFILE: \
     read (F,end=ENDDIR)F$
     if F$(1,1)="." \
          then goto NXTFILE
     if mid(F$,-1)<>dlm \
          then list_box load 10,0,pth(F)+dlm+F$;
                  goto NXTFILE
     D$=pth(F)+dlm+F$
     F++
     goto NXTDIR
ENDDIR: \
     close (F)
     F--
     if F>0 \
          then goto NXTFILE
     escape

Note:
Use SEP=DLM when reading directories to have PxPlus append the operating system delimiter to sub-directory names.

See Also

LIST_BOX Properties
LIST_VIEW Properties
REPORT_VIEW Properties
TREE_VIEW Properties