CONTROL ADD COMBOBOX

<< Click to Display Table of Contents >>

Navigation:  ThinBASIC Modules > UI (User Interface) > CONTROLS > Control Types > ComboBox Control > ComboBox Control Creation >

CONTROL ADD COMBOBOX

 

Description

 

Create a new combo box control inside a dialog.

 

Syntax

 

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

 

Returns

 

Number

Control window handler.

 

Parameters

 

Name

Type

Optional

Meaning

ControlName

String

Yes

Optional name for the control.

 

This name must be globally unique, and is used to create a global variable to be used with control name methods and properties.

hwnd

Number

No

Handle of the dialog containing the control

ctrlID

Number

No

Control identifier

StringArray

String

Yes

Optional 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 %CBS_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 both left and right.

 

If no array is specified, a simple string expression can be indicated. If string data will contain "\n" it will be interpreted as string separator for control items. Example "one\ntwo\nthree" will create 3 items.

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 COMBOBOX Style equates.

There are three types of combo boxes: simple, dropdown, and dropdownlist. A simple combo box consists of a text box control and a list box; the list box is always displayed. A dropdown combo box consists of a text box control and a list box; the list box is not displayed unless the user clicks an icon. A dropdownlist combo box consists of a label control (not editable) and a list box; the list box is not displayed unless the user clicks an icon.

Note that some styles of combo box are mutually exclusive. In other words, you cannot combine certain styles that may conflict with one another. For example, you cannot specify %CBS_SIMPLE and %CBS_DROPDOWN at the same time.

ExStyle

Number

Yes

Extended style of the control. See COMBOBOX 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 selects an item or edits the text of a combo box, a message is sent to the Callback Function designated for the combo box. 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

%CBN_CLOSEUP

Sent when the list box of a combo box has been closed.

%CBN_DBLCLK

Sent when the user double-clicks a string in the list box of a combo box.

%CBN_DROPDOWN

Sent when the list box of a combo box is about to be made visible.

%CBN_EDITCHANGE

Sent after the user has taken an action that may have altered the text in the text box portion of a combo box. Unlike the %CBN_EDITUPDATE notification message, this notification message is sent after Windows updates the screen.

%CBN_EDITUPDATE

Sent when the text box portion of a combo box is about to display altered text. This notification message is sent after the control has formatted the text, but before it displays the text.

%CBN_ERRSPACE

Sent when a combo box cannot allocate enough memory to meet a specific request.

%CBN_KILLFOCUS

Sent when a combo box loses the keyboard focus.

%CBN_SELCHANGE

Sent when the selection in the list box of a combo 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.

%CBN_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.

%CBN_SELENDOK

Sent when the user selects a list item, or selects an item and then closes the list. It indicates that the user's selection is to be processed.

%CBN_SETFOCUS

Sent when a combo 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

 

See also

 

Examples