Control ListBox / MultiListBox clause - MapBasic - 2023

Purpose

Part of a Dialog statement; adds a list to a dialog box

Syntax

Control { ListBox | MultiListBox } 
	[ Position x, y ] [ Width w ] [ Height h ] 
	[ ID control_ID ] 
	[ Calling handler ] 
	[ Title { str_expr | From Variable str_array_var } ] 
	[ Value i_selected ] 
	[ Into i_variable ] 
	[ Disable ] [ Hide ]

x, y specifies the control's position in dialog box units.

w specifies the width of the control in dialog box units; default width is 80.

h specifies the height of the control in dialog box units; default height is 70.

control_ID is an integer; cannot be the same as the ID of another control in the dialog box.

handler is the name of a procedure to call if the user clicks or double-clicks on the list.

str_expr is a string expression, containing a semicolon-delimited list of items to appear in the control.

str_array_var is the name of an array of string variables.

i_selected is a SmallInt value indicating which list item should appear selected when the dialog box first appears: a value of one selects the first list item; if the clause is omitted, no items are selected initially.

i_variable is the name of a SmallInt variable which stores the user's final selection.

The Disable keyword makes the control disabled (grayed out) initially.

The Hide keyword makes the control hidden initially.

Description

If a Dialog statement includes a Control ListBox clause, the dialog box includes a listbox control. If the list contains more items than can be shown in the control at one time, MapBasic automatically adds a scroll-bar at the right side of the control.

A MultiListBox control is identical to a ListBox control, except that the user can Shift+Click to select multiple items from a MultiListBox control.

The Title clause specifies the contents of the list. If the Title clause specifies a string expression containing a semicolon-delimited list of items, each item appears as one item in the list. The following sample Title clause demonstrates this syntax:

Title "1st Quarter;2nd Quarter;3rd Quarter;4th Quarter"

Alternately, if the Title clause specifies an array of string variables, each entry in the array appears as one item in the list. The following sample Title clause demonstrates this syntax:

Title From Variable s_optionlist

Processing a MultiListBox control

To read what items the user selected from a MultiListBox control, assign a handler procedure that is called when the user dismisses the dialog box (for example, assign a handler to the OKButton control). Within the handler procedure, set up a loop to call the ReadControlValue() function repeatedly.

The first call to the ReadControlValue() function returns the number of the first selected item; the second call to the ReadControlValue() function returns the number of the second selected item; etc. When the ReadControlValue() function returns zero, you have exhausted the list of selected items. If the first call to the ReadControlValue() function returns zero, there are no list items selected.

Processing Double-click events

If you assign a handler procedure to a list control, MapBasic calls the procedure every time the user clicks or double-clicks an item in the list. In some cases, you may want to provide special handling for double-click events. For example, when the user double-clicks a list item, you may want to dismiss the dialog box as if the user had clicked on a list item and then clicked OK.

To see an example, refer to the sample application NVIEWS.MB in <Your MapBasic Installation Directory>\SAMPLES\MAPBASIC\SNIPPETS.

To determine whether the user clicked or double-clicked, call the CommandInfo() function within the list control's handler procedure, as shown in the following sample handler procedure:

Sub lb_handler 
	Dim i As SmallInt 
	If CommandInfo(CMD_INFO_DLG_DBL) Then 
	' ... then the user double-clicked. 
		i = ReadControlValue( TriggerControl() ) 
		Dialog Remove 
		' at this point, the variable i represents
		' the selected list item...
	End If 
End Sub 

Example

Control ListBox 
	Title "1st Quarter;2nd Quarter;3rd Quarter;4th Quarter" 
	ID 3
	Value 1
	Into i_quarter
	Position 10, 92 Height 40 

The NVIEWS.MB sample program demonstrates how to create a dialog box which provides special handling for when the user double-clicks. The NVIEWS program displays a dialog box with a ListBox control. To complete the dialog box, the user can click on a list item and then choose OK, or the user can double-click an item in the list.

The following Control ListBox clause adds a list to the Named Views dialog box. Note that the ListBox control has a handler routine, "listbox_handler."

Control ListBox 
	Title desc_list 
	ID 1
	Position 10, 20 Width 245 Height  64 
	Calling listbox_handler

If the user clicks or double-clicks on the ListBox control, MapBasic calls the sub procedure "listbox_handler." The procedure calls the CommandInfo() function to determine whether the user clicked or double-clicked. If the user double-clicked, the procedure issues a Dialog Remove statement to dismiss the dialog box. If not for the Dialog Remove statement, the dialog box would remain on the screen until the user clicked OK or Cancel.

Sub listbox_handler 
	Dim i As SmallInt 
	' First, since user clicked on the name of a view, 
	' we can enable the OK button and the Delete button. 
	Alter Control 2 Enable 
	Alter Control 3 Enable 
	If CommandInfo(CMD_INFO_DLG_DBL) = TRUE Then 
	' ...then the user DOUBLE-clicked. 
	' see which list item the user clicked on. 
		i = ReadControlValue(1) ' read user's choice.
		Dialog Remove 
		Call go_to_view(i) ' act on user's choice. 
	End If 
End Sub 

MapBasic calls the handler procedure whether the user clicks or double-clicks. The handler procedure must check to determine whether the event was a single- or double-click.

See Also:

Alter Control statement, Dialog statement, ReadControlValue() function, CommandInfo() function