Using List Box Controls

About list box

A list box is a control window that contains a list of items from which the user can choose.

List box items are represented by text strings. If the list box is not large enough to display all the list box items at once, the list box can provide a scroll bar. The user maneuvers through the list box items, scrolling the list when necessary, and selects or removes the selection from items. Selecting a list box item changes its visual appearance, usually by changing the text and background colors to the colors specified by the operating system metrics for selected items. When the user selects an item or removes the selection from an item, Windows sends a notification message to the parent window of the list box.

Creating the control

List box controls are created in the same manner as the standard control types, either through the dialog editor or manually with the CONTROL statement.

List box control styles

The following list box style flags can be specified in the CONTROL statement or by ticking the corresponding check box in the control properties of the dialog editor:

@CTLISTEXTENDED

Allows multiple items to be selected by using the SHIFT key and the mouse or special key combinations.

@CTLISTMULTI

Turns string selection on or off each time the user clicks or double-clicks a string in the list box. The user can select any number of strings.

@CTLISTSORT

Sorts strings in the list box alphabetically.

@CTLISTSTANDARD

Sorts strings in the list box alphabetically. The parent window receives an input message whenever the user clicks or double-clicks a string. The list box has borders on all sides.

@CTLISTNOTIFY

Notifies the parent window with an input message whenever the user clicks or double-clicks a string in the list box.

@CTLISTTABS

Enables a list box to recognize and expand tab characters when drawing its strings.

@CTLISTCOLUMNS

Specifies a multicolumn list box that is scrolled horizontally. The SETLBCOLWIDTH statement sets the width of the columns.

In addition to the list box styles, the following window styles can also be specified:

@TABSTOP

Moves the input focus between controls if controls are in a dialog. This style has no effect for controls created in a window.

@GROUP

Specifies the first control of a group of controls in which the user can move from one control to the next with the arrow keys. All controls defined without the @GROUP style  after the first control belong to the same group. The next control with the @GROUP style starts the next group (that is, one group ends where the next begins)

@HSCROLL

The control has a horizontal scroll bar

@VSCROLL

The control has a vertical scrollbar

List box control functions and statements

The following EBASIC functions and statements are used to communicate with the list box control.

SETSELECTED window | dialog, ID, position

Sets the currently selected item in a list or combo box control. The position value is zero-based and the list or combo box must contain a string at that position.

GETSELECTED (window | dialog, ID)

Returns the zero-based index of the currently selected item in the list box of a combo or single selection list box. Returns -1 if no item is selected. ID must be a list box or combo box.

ISSELECTED (window | dialog, ID, position)

Returns TRUE if the string at position is selected in a multi-selection list or combo box.

GETSTRINGCOUNT (window | dialog, ID)

Returns the number of strings in a list box or combo box control.

GETSTRING (window | dialog, ID, position)

Returns the string at position in a list box or combo box. Position is a zero based index.

ADDSTRING window | dialog, ID, string

Adds a string to a list box or combo box control.   String is added to the end of the list unless sorting is specified in the style of the control.

INSERTSTRING window | dialog, ID, position, text

Inserts a string into a combo or list box control at position.  All other strings are moved down by one position.

DELETESTRING window | dialog, ID, position

Removes a string from a list box or combo box control. Remaining strings are moved up to fill the empty position.

SETLBCOLWIDTH window | dialog, ID, width

Sets the width of columns in a multi-column list box. The list box must have been created with the style @CTLISTMULTI either in the CONTROL statement or by selecting the multicolumn checkbox in the dialog editor.

SETHORIZEXTENT window | dialog, ID, width

Sets the horizontal scroll width of a list box or list box portion of a combo box. Control must have been created with the @HSCROLL style. The width is specified in pixels.

SETCONTROLCOLOR window|dialog, ID, fg, bg

Sets the text color and background color of the list box control.

return = CONTROLEXISTS (window | dialog, ID)

Returns 1 if the control with ID exists in the window or dialog.

ENABLECONTROL window | dialog, ID, 0 | 1

Disables or enables the list box control.

SETFOCUS window | dialog, ID

Gives the control the input focus.

SENDMESSAGE window | dialog, msg, wparam, lparam ,ID

Sends a message to the control for advanced functionality.

SHOWWINDOW window, flags, ID

Changes the visibility state of the control. Use @SWHIDE to hide the control and @SWRESTORE to show the control

SETSIZE dialog | window, L, T, W, H ,ID

Changes the size of the control.

Notification messages

An list box control sends notification messages to the parent window or dialog in the @NOTIFYCODE variable. The ID of the control is found in @CONTROLID. To receive @LBNDBLCLK or click messages it is necessary to create the control with the @CTLISTNOTIFY style. The following notification messages are defined:

@LBNDBLCLK

The user double-clicks an item in the list box.

@LBNERRSPACE

The list box cannot allocate enough memory to fulfill a request.

@LBNKILLFOCUS

The list box loses the keyboard focus.

@LBNSETFOCUS

The list box receives the keyboard focus.

@LBNSELCHANGE

The selection in a list box is about to change.

@LBNSELCANCEL

The user cancels the selection of an item in the list box.