VARLIST_BOX Create/Control Variable List Box

VARLIST_BOX Properties

The Variable List Box control operates like a Standard list box but will allow variable input, which means that the user can select any element from a list of items associated with the list box but can also enter any other value.

This control can be created either by using the VARLIST_BOX directive or by using the NOMADS Panel Designer to draw a Variable List Box Control and apply the desired attributes.

Below is a list of properties used to define and manipulate Variable List Box controls. For a list of properties for Standard list boxes, see LIST_BOX Properties.

Use the links in the Property column to access the PxPlus Help page for a selected property. The Help page may provide additional details, particularly if the property can be used to define other controls.

For a complete list of all the properties available, see Properties List.

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:

0

Only signal change when exiting the control or on special event such as double click/Enter. (Default)

1

Signal all changes to the value of the control regardless of why the change occurred.

2

Signal all changes done by the user but not done by the program.

BackColor$
BackColour$

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

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.

Cols

Width of control in column units.

CtlName$

Control type ("VARLIST_BOX"). See VARLIST_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.

(VarList Box 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.

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

Char.

Function

C

Search is case insensitive.

A

Accents will be ignored when comparing data.

W

Search should start from current position and wrap around.

*

Match is for data anywhere in the text (cannot be used with Sort option).

S

Data is sorted.

R

Search backwards.

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 also '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"

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.

(VarList Box 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.

(VarList Box 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".

FrameColor$

Color of the frame/border around the control.

(The FrameColor$ property was added in PxPlus 2024.)

Height

Height of control in pixels.

hWnd

Windows handle for control.

Item

Index number of item in list.

ItemCount

Number of items in list. 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.

Len

Input length of line.

Line

Screen position of control.

Lines

Height of control in number of lines.

LoadPoint

Insertion point for list/drop box loads. 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.)

LookAndFeel

Defines how a control will look. Possible values are:

2

Old Windows 3.1 2D look.

3

Windows 95/98 3D look.

4

Windows XP/Vista/Windows 7 look.

MenuCtl

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

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/cells 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.

ScrollWheel

Set scroll wheel increment. This property is used to define how many lines each click of the scroll wheel will move a list box or grid.

Possible values are:

0

Scroll wheel support (all events go to parent window).

1

Scroll only if the control has focus (mouse can hover on or off control).

2

Scroll only if the control has focus (mouse must be hovered over control).

3

If control does not have focus, then scroll when mouse hovers over this control (otherwise, same as 1).

4

If control does not have focus, then scroll when mouse hovers over this control (otherwise, same as 2).

SelectLength

This property reports the number of characters currently highlighted. This allows for cut, copy and paste within a graphical user interface input region.

SelectOffset

This property indicates where the highlight begins within the data or, if nothing is highlighted, the current cursor location. This allows for cut, copy and paste within a graphical user interface input region.

SelectText$

Text contained within the highlight: This allows for cut, copy and paste within a graphical user interface input region. See Multiple Selections.

Sep$

Separator character between each field, column or data point.

SepLoad$

Separator character for each row or data set.

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

0

No signal on exit unless control value has changed.

1

Signal on exit regardless of whether value has changed (on grid, signals whenever changing cell).

2

Signal when changing row or on exit of grid (sets column value to 0 and row value to last row exited). (Grid Only)

3

Signal when exiting the grid (sets column and row values to zero). (Grid Only)

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.

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.

See Also

Multiple Selections
Load on Demand
Color Properties
'COLOUR' & '_COLOUR' Mnemonic
Using Property Names
Compound Properties