CONTROL ADD LISTBOX

Description

Create a new ListBox control inside a dialog.

Syntax

hndl = CONTROL ADD LISTBOX, hwnd, ctrlID, [StringArray()], xPos, yPos, Width, Height [, [Style] [, [ExStyle]]] [[,] CALL CallBack]

Returns

Number

Control window handler.

Parameters

Name	Type	Optional	Meaning
hwnd	Number	No	Handle of the dialog containing the control
ctrlID	Number	No	Control identifier
StringArray	String	Yes	Optional dynamic string array containing the initial items to be displayed in the list box. Items are copied from the array to the list box. To create a list box that is initially empty, either omit this parameter, or specify an array whose first element contains an empty string. If the list box uses the %LBS_SORT style, the items are sorted alphanumerically as they are added to the list box. Both fixed or dynamic string arrays are handled. In case of fixed strings, elements are right trimmed.
xPos	Number	No	Horizontal position of the control inside the dialog
yPos	Number	No	Vertical position of the control inside the dialog
Width	Number	No	Control width
Height	Number	No	Control height
Style	Number	Yes	Primary style of the control. See LISTBOX Style equates. Custom style values replace the default values. That is, they are not additional to the default style values - your code must specify all necessary primary and extended style parameters.
ExStyle	Number	Yes	Extended style of the control. See LISTBOX ExStyle equates.
Callback	Function	Yes	Optional name of a Callback Function that receives all %WM_COMMAND and %WM_NOTIFY messages for the control. If a callback for the control is not designated, you must create a dialog Callback Function to process messages from your control. If the Callback Function processes a message, it should return %TRUE (non-zero) to prevent the message being passed unnecessarily to the dialog callback (if one exists). The dialog callback should also return %TRUE if the notification message is processed by that Callback Function.

Remarks

When the user with a listbox, a message is sent to the Callback Function designated for the control. If there is no Callback Function designated then the message is sent to the callback for the dialog.

If the control callback processes the notification message, it should return %TRUE (non-zero) to prevent the message being passed needlessly to the dialog callback.

Notification messages are sent to the Callback Function, with CBMSG = %WM_COMMAND, CBCTL holding the ID (ctrlID) of the control, and CBCTLMSG holding the following values:

Message	Meaning
%LBN_DBLCLK	Sent when the user double-clicks a string in the list portion of a list box.
%LBN_ERRSPACE	Sent when a list box cannot allocate enough memory to meet a specific request.
%LBN_KILLFOCUS	Sent when a list box loses the keyboard focus.
%LBN_SELCANCEL	Sent when the user selects an item, but then selects another control or closes the dialog box. It indicates the user's initial selection is to be ignored.
%LBN_SELCHANGE	Sent when the selection in the list box is about to be changed as a result of the user either clicking in the list box or changing the selection by using the arrow keys.
%LBN_SETFOCUS	Sent when a list box receives the keyboard focus.

When a Callback Function receives a %WM_COMMAND message, it should explicitly test the value of CBCTL and CBCTLMSG to guarantee it is responding appropriately to the notification message.

Restrictions