LIST_BOX Create/Control List Box

Property

Description

Auto

When set, the control will generate a 'Change' event whenever its value changes as opposed to the default Off state where the control will only generate the change event when losing focus.

Possible values are:

AutoColSize

This property is used to control the automatic adjustment of column sizes so that the total space occupied by the columns will fill the control width.

When this property is set to 1, the system will adjust all columns in the control so that the sum of the column widths will completely fill the control width exclusive of any scrollbars that may be present. Once set, any resizing of the control will again re-apply the automatic columns sizing logic. (Default: 0 - No automatic column resizing)

When adjusting the column sizes, the system will compute the new size based on percentages.

Example:

Consider the following - Control has three columns:

• Column 1 is 40 pixels wide.
• Column 2 is 10 pixels wide.
• Column 3 is 50 pixels wide.

If this control had AutoColSize enabled, it would determine that column 1 was 40% of the total column width, column 2 was 10%, and column 3 was 50%. These columns would each be adjusted based on the total width of the control to retain the same percentages. Therefore, if the control itself was 150 pixels wide, column 1 would become 150*40%=60 pixels, column 2 would become 150*10%=15 pixels, and column 3 would become 150*50%=75 pixels.

BackColor$
BackColour$

Background color. For information on valid color names and color specifications, see Color Properties. (Default: "DEFAULT")

BackHilight1$

Background color, alternating lines: Background color for every second line. (Default: "DEFAULT")

If set to other than the value "DEFAULT", the color set in this property will be used as the background color on every second line in a list. For information on valid color names and color specifications, see Color Properties.

BackHilight2$

Background color, alternating three lines: Background color for every third line. (Default: "DEFAULT")

If set to other than the value "DEFAULT", the color set in this property will be used as the background color on every third line in a list. For information on valid color names and color specifications, see Color Properties.

BringToTop

This property, when set to any value, will cause the control to be moved to the top of the display order. Once at the top of the display order, the control will appear visually on top of any other control on the window. (Default: Not Applicable - Always returns 0)

Col

Screen position (column) of control.

Colno

Column number of report view. This property is fundamentally the same as referring to the 'Column property, however, is included to allow a numeric column number to be specified as a string with accessing the properties.

Referencing 'Colno$ will return the column number as a string.

Cols

Width of control in column units.

Column

Currently referenced column number of report view: This property does not contain the current column number of the control, but rather the column number being referenced when used in conjunction with other properties.

Column$

Report view column name.

ColumnClicked

This property contains the column number of the column where the last mouse click occurred in the report view. It is set automatically by the system when the user clicks the mouse on a line within the report view. It is reset to 0 (zero) if the user positions/selects items in the report view using the keyboard.

ColumnHdrTip$

This property is used to control the tip to display below the column header in a report view control. To set/reference the tip, you must first set the 'Column property for the report view to identify the column you are referencing. By default, if no column tip is defined, the standard report view tip will be displayed.

ColumnSizeLock

This property controls the ability of the user to resize the width of a column by dragging the column header.

If set to 0, the column may not be resized. If set to 1, the column is resizable. (Default: 1 - resizable)

ColumnsWide

Number of columns.

ColumnWidth

Width of column in column units.

CtlName$

See LIST_BOX directive.

CurrentItem

Current item with focus/selected. (Default: 1; 0 if no data)

DisableBackColor$
DisableBackColour$

Background color when the control is disabled. For information on valid color names and color specifications, see Color Properties.

(Report View support was added in PxPlus 2019.)

DisableOnEmpty

This property can be set to have the system automatically disable a list style control (list box, list view, report view or drop box) if the list contents are empty -- that is, there are no potential selections for the user to select. Once the list is populated (with at least one entry), the list box will be re-enabled.

This setting is independent of the 'Enabled property; that is, if the list box is already forcibly disabled, adding entries to the list will not cause the list to be re-enabled.

(Default: 0 - The list will not be automatically disabled.)

DisableTextColor$

Foreground text color when the control is disabled. For information on valid color names and color specifications, see Color Properties.

(Report View support was added in PxPlus 2019.)

DroppedOn

This property indicates the index number that dragged items were dropped onto; if items are not dropped onto a specific line, 0 is returned.

Enabled

Enabled indicator: 1 = True; 0 = False (Default: 1)

Eom$

Last change terminator. See also LIST_BOX directive.

ExcelStyle

This property is used to control the display of grid lines in either the grid or the report view controls.

Possible values are:

Note:
Prior to PxPlus v8.11 (build 9182), this property was only available on the grid and only accepted a value of 0 or 1. As of PxPlus v8.11, PxPlus supported the property in the report view and options 2/3.

FindColNo

This property is used to control which column the 'FindItemText will search. If not set, the search encompasses all rows/columns within the report view. See FindItemText$ and FindOptions$ properties. (Default: 0 - No column specified; searches all columns)

FindItemText$

This property, when set, causes the system to search the list box or grid for the text supplied. If the text is found, the system will set the 'Column and 'Item (or 'Row) property for the control to the entry where the match was found. If no match is found, the 'Column and 'Item ('Row for the Grid) property is set to zero.

A typical use of this property would be to locate a value in the list box and then change or delete it. It can also be used to validate that an entry exists in the list box. This property is generally only written to. Reading this value will return the same as reading the 'ItemText$ property.

Controlling the Search (List View/Grid Only): The search is controlled by the settings found in 'FindOptions$. These options are provided as a series of characters in 'FindOptions$:

Search Range (List View/Grid Only): When searching, if the "W"rap option is not specified, the search will start from the beginning of the data in the control and proceed through the end. If the "R"everse option is set, the search starts at the end and proceeds to the beginning. If the "W"rap option is set, the search will start from the position immediately after that specified in the 'Item ('Row for Grid) and 'Column and search through all the data wrapping around the end/start back to the starting point.

If the property 'FindColNo (or 'Column for Grid) is set, only data in that column will be searched. If the "S"ort option is specified, only the column specified in the 'Sort property will be checked and its setting (Ascending/Descending) will be used to determine the assumed sort sequence. If 'Sort is not set, the system will assume that the column specified in 'FindColNo has been pre-sorted in Ascending order. If 'FindColNo is not set, then the system will assume the first column is to be used and is in ascending sequence.

If both "W"rap and "S"ort options are specified, the system will use the starting point set in 'Item ('Row on Grid) and 'Column and determine the search direction based on the value at the starting point. If the value at the start point matches that of the search value, the "R" option will determine the search direction.

See 'FindColNo and 'FindOptions$ properties.

Note:
Prior to PxPlus v11, this property and functionality was not available on the grid. In addition, the 'Column was not set nor were the 'FindOptions$ and 'FindColNo (list view only) supported.

Example 1: Changing item text in a list box

To change the value of the list box entry of "CAT" to "DOG" for list box "LIST1", you could do the following:

     List1'FindItemText$="CAT" ! Locate the item
     List1'ItemText$ = "DOG" ! Change the value

Example 2: Locate and delete an item from a list box

To locate and delete a value from a list box:

     List1'FindItemText$="CAT" ! Locate the item to delete
     LIST_BOX LOAD List1, List1'Item, *

Example 3: Validate the existence of an item in a list

To search a list box to find a specific value, set the FindItemText$ to the desired search value then read 'Item. If zero, the item does not exist.

     List1'FindItemText$=X$ ! Locate the item
     IF List1'Item=0 THEN MSGBOX X$+" is not found"

FindOptions$

This property is used to control how the 'FindItemText will search the data in the report view. It can have one of the following characters specified in its value:

(Default value is "" - no options specified.)

See 'FindItemText$ and 'FindColNo properties.

(The "I" option was added in PxPlus 2023.)

Fmt$

Control format definition. Refer to the FMT= option as described in the LIST_BOX directive.

Focus

Focus indicator: 1 = Control has focus. (Default: 0)

FocusBackColor$
FocusBackColour$

Background color when the control has focus. For information on valid color names and color specifications, see Color Properties.

(Report View support was added in PxPlus 2018.)

FocusTextColor$
FocusTextColour$

Foreground text color when the control has focus. For information on valid color names and color specifications, see Color Properties.

(Report View support was added in PxPlus 2018.)

Font$

This property is used to reference the font for a control. It will contain (or can be set to) a string containing three comma-separated fields of the font name, size and attributes. See 'FONT' mnemonic.

Example:

To set the font to Arial, 1.5 times normal size, and Bold, the format would be xxx'Font$="Arial,1.5,B".

HdrBackColor$
HdrBackColour$

This property sets the background color for the report view header. For information on valid color names and color specifications, see Color Properties.

(The HdrBackColor$ (or HdrBackColour$) property was added for Report Views in PxPlus 2016.)

HdrFont$

This property defines the font for the report view header.

(The HdrFont$ property was added for Report Views in PxPlus 2016.)

HdrHeight

This property can be used to control the height of the header in the report view in pixels.

Setting this property to -1 restores the height to its default size. Setting this property to 0 results in no header.

(The HdrHeight property was added in PxPlus 2020.)

HdrTextColor$
HdrTextColour$

This property sets the color of the text for the report view header. For information on valid color names and color specifications, see Color Properties.

(The HdrTextColor$ (or HdrTextColour$) property was added for Report Views in PxPlus 2016.)

HeaderLock

This property controls the ability of the user to click on or drag the header of a report view.

If set to 0 (zero), the column header is not locked. If set to 1, the column header is locked and mouse clicks or dragging of the column header is not accepted. (Default: 0)

Height

Height of control in pixels.

HotLinkColor$

This color is applied to the text of a column defined as a hotlink in the report view to provide a visual cue. For information on valid color names and color specifications, see Color Properties.

(The HotLinkColor$ property was added in PxPlus 2018.)

HoverBackColor$
HoverBackColour$

Background color when mouse is over a report view row. If two colors are specified, use the / (slash) as a separator (i.e. RGB:100 100 100/Light Blue). For information on valid color names and color specifications, see Color Properties.

(Report Views support was added in PxPlus 2018.)

HoverColor$
HoverColour$

Hover color. For information on valid color names and color specifications, see Color Properties. (Default: "DEFAULT")

hWnd

Windows handle for control.

Item

Index number of item in list.

ItemCount

Number of items in list. See Load on Demand.

ItemLoadedCtl

Signal/CTL event number to generate when items are loaded in the list.

ItemNeededCnt

Number of items whose text value is still undefined when using Load on Demand for lists.

Example:

You can define a list box to contain 1000 items but only supply the item values (display text) as the user scrolls them into view. The 'ItemNeededCnt is the number of items whose value has still not been loaded.

ItemNeededCtl

Signal/CTL event number to generate when items are requested from the list box: This property must be set prior to pre-declaring the number of items the list box is to have by setting the 'ItemCount property. See Load on Demand.

ItemNeededFrom

Index number of the items requested: The 'ItemNeededFrom and 'ItemNeededTo properties are set once the user scrolls the list box to request more items to be loaded. See Load on Demand.

ItemNeededTo

Index number of the items requested: See Load on Demand.

ItemText$

Value of the current item set by 'Item.

Key$

Hot key to jump to control.

Left

Left margin for control in pixels.

Line

Screen position of control.

LineColor$
LineColour$

This property contains the color of the lines drawn between rows and columns when the 'ExcelStyle property is set. For information on valid color names and color specifications, see Color Properties. (Default: DEFAULT (normally BLACK))

(The LineColor$ (or LineColour$) property was added in PxPlus 2020.)

LinePixels

Returns the height of a row in a report view in pixels. (Read Only)

(The LinePixels property was added in PxPlus 2017.)

Lines

Height of control in number of lines.

LinesPerRow

This property is used to define the number of lines that each entry on a list box contains. When set to a value > 1, the system will apply word wrap to the text in the list box and support line breaks with the line feed ($0a$) character. (Default: 1 - Each row in the list box is one line high.)

LoadPoint

This property controls where the data loaded to a list_box, drop_box, varlist_box or vardrop_box will be inserted. When a list/drop box LOAD directive is issued with no index, the current contents of the control 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/drop box LOAD directive will be appended to the list box contents.

If 'LoadPoint is set to -2, the data included with the list/drop box LOAD directive 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.

Note:
A positive value in the 'LoadPoint property is reset to 0 (zero) when a list/drop box LOAD directive is executed. A value of -1, which indicates 'append', is not reset by the LOAD directive.

This functionality allows drop boxes to be loaded a block of records at a time.

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

LockBottom

Number of rows at the bottom of the report view to exclude from sorting. See LockTop property.

LockTop

Number of rows at the top of the report view to exclude from sorting. See LockBottom property.

(The LockTop property was added in PxPlus 2019.)

LookAndFeel

Defines how a control will look. It can have the following values:

MenuCtl

This property reports/sets the CTL value to generate when an object is selected on a right-click of the mouse.

MouseOver

This property returns the item number of an object when the mouse pointer is over it. If the mouse is not over an object, -1 is returned. 0 is returned if the cursor is over an area in the control with no data.

Msg$

Message line text for the control.

ObjectID

User object method. (Default: 0 - No object specified)

The 'ObjectID property allows applications to intercept property values and add methods to controls. When set to a valid Object ID by the application, you can add methods and add/override property logic for any control in the system. When set in the system, it allows the application to logically request methods against the control that, in turn, will be performed by the related Object ID. It will also first check the object for any property requests and, if the property is defined in the object, set or get that property instead of the controls.

To allow the specified object to get true access to the control, while executing within the object identified by the 'ObjectID property, the system will direct any property requests directly to the control.

Note:
When a control is deleted from the system, any object identified by an 'ObjectID property will be automatically dropped.

OnFocusCtl

On Focus CTL event. 0 is returned if no On Focus CTL value is set up for the control.

OnLoadCtl

This property, when set to a non-zero value, causes the system to generate an internal CTL event following any changes to a list box. It can be used to monitor changes to a list style control so that external action (such as updating screen or files) can be performed. (Default: 0)

If the value of this property is non-zero, the system will use its value as a CTL event to generate. If zero (default state), no event will be generated.

To avoid multiple signals being generated, the system will defer the generation for approximately 1/2 second following the last update. This means that when multiple rows are being updated, the event will generally only occur once the updating is complete.

OnTipCtl

This property controls the CTL event that will be fired prior to the system displaying the Tip for any control. If the value of this property is non-zero, the system will use its value of a CTL event to fire and will defer the display of the tip until the application changes the value in 'Tip$. If the value in 'Tip$ is not changed, no tip will be displayed.

Setting this to zero (Default) disables the event from being sent and the current 'Tip$ will be displayed.

Parent

Parent window handle.

RowHeight

Height of current row in lines.

ScrollWheel

This property is used to define how many lines each click of the scroll wheel will move a list box. Possible values are:

SelectBackColor$

Sets the background color. For information on valid color names and color specifications, see Color Properties.

(The SelectBackColor$ property was added in PxPlus 2018.)

SelectCount

Number of items selected: Set this property to zero to deselect all items. See Multiple Selections.

SelectIndex

Index to 'SelectItem: Set this property to point to a selected element; e.g. 1 points to the first item selected, 2 points to the second item selected, etc. See Multiple Selections.

SelectItem

Item number in list selected: This property returns the sequential location within the list of the item being pointed to by 'SelectIndex property. See Multiple Selections.

SelectTextColor$

Sets the text color. For information on valid color names and color specifications, see Color Properties.

(The SelectTextColor$ property was added in PxPlus 2018.)

Sep$

Separator character between each field, column or data point.

SepLoad$

Separator character for each row.

SepSort$

This property is used to define a character, which will separate the contents of a report view column that is to be displayed from the values of the column as it will be used for column sorting.

Often when displaying data in a report view, it is desirable to have what is displayed be different from how the value should be sorted. For instance, the display value of a report view may be a bitmap or some other graphical information, which is not able to be sorted. If you define a SepSort$ value, any data in the column before the specified character will define what will be displayed, and data following the character will be used for the purposes of sorting.

SignalOnExit

This property controls whether a 'Change' signal will be generated when the control (or region of a grid control) is exited regardless of whether the control's value changes. Normally, controls only signal changes when the control loses focus and the contents have changed. Setting 'SignalOnExit allows a change signal to also be generated whenever focus leaves the control (or region for grid).

Sort

Column sorting: Sorts the contents of the control. In report views, this property sets the number of the column on which the data is to be sorted. Positive integers indicate normal ascending sort order; negative integers indicate descending order. (Default for Report View: 0)

SortOnHdrClick

This property is used to control the sorting of report view columns based on the user clicking the column header.

This property is used to enable/disable the column sorting options. Possible values are:

(Default for Report View: 1 - Column sorting is enabled; column will sort on click of column header.)

(Value of -1 for Report Views was added in PxPlus 2017.)

SortOrder$

Sorting control settings. This property is used to control how column data will be sorted in the report view. It can have one of the following values or be set to Null, which indicates the sort order is defined by the system StdSortOrder setting using the SETDEV SET directive or the 'OPTION' mnemonic.

(Default: Null - Data is sorted using the StdSortOrder setting.)

Alternatively, this property can be accessed as a string comprising the characters C, A or N. An empty string is used to indicate all settings are Off.

Tbl$

Controls the translation of the values selected in a control and how the value will be passed to/from the application.

Generally, it contains a table of single-character values representing selections from the controls with each character representing each of the values in the control in sequence. The size of each entry can be changed using the 'TblWidth property.

TblWidth

This property can be used to set the length of each of the items in the 'Tbl$ property. It can be set to any positive value. (Default: 1)

Setting 'TblWidth to 0 (zero) indicates that 'Tbl$ contains a delimited string with the last character of the string being the delimiter character.

TextColor$
TextColour$

Foreground text color. For information on valid color names and color specifications, see Color Properties. (Default: "DEFAULT")

Tip$

Tip message for control.

Top

Top of control in pixels.

TopVisibleItem

This property is used to access the item number that is currently displayed at the top of the list.

It can be used to determine/control vertical scrolling of the data. If set, it must be set to a value between 1 and the number of items in the list. (Default: 1)

Setting this property to a row near the bottom of the list contents does not always guarantee that the row identified will be the first line within the control. The system will attempt to leave the bottom few lines visible; however, it will assure that the item indicated is visible.

Value$

Current item value.

ValueNoSignal$

Change control's value without generating OnChange event: Same as 'Value$; however, when used to change the value in the control, no OnChange event will occur.

Normally, on list style or input controls which have Signal All Changes enabled, changing the control value under either program control or by user input will generate an OnChange event. Changing the value of a control using the ValueNoSignal$ property allows the control's value to change without generating the OnChange event.

Visible

Control visible flag: 1 = Yes; 0 = No (Default: 1)

Width

Width of control in pixels.

_PropList$

Controls the list of properties to be returned in '_PropValues$. Each value is separated by the value in '_PropSep$.

This property can be used to speed up the processing of multiple property accesses but reducing the number of interactions with the control. See Multi-Property Access.

_PropSep$

Controls the separator used between each of the values of the properties returned in '_PropValues$ as defined by '_PropList$.

This property can be used to speed up the processing of multiple property accesses but reducing the number of interactions with the control. See Multi-Property Access.

_PropValues$

Accesses the values of the properties defined in '_PropList$. Each value is separated by the value in '_PropSep$.

This property can be used to speed up the processing of multiple property accesses but reducing the number of interactions with the control. See Multi-Property Access.