CONTROL ADD COMBOBOX statement

Purpose

Add a combo box to a dialog. A combo box is often used to allow a user to select an item from a predefined list, or enter a fresh (unlisted) item. A combo box may contain only text strings. To put numbers in a combo box, convert them to strings with the FORMAT$, USING$, or STR$ functions.

Syntax

CONTROL ADD COMBOBOX, hDlg, id&, [items$()], x, y, xx, yy [, [style&] [, [exstyle&]]] [[,] CALL callback]

hDlg

Handle of the dialog in which the combo box will be created. The dialog will become the parent of the control.

id&

Unique identifier for the control in the range 1 to 65535, frequently specified with numeric equates for clarity of the code. For example, the equate %StockNumberList is more informative than a literal value such as 497. Best practice suggests identifiers should start at 100 to avoid conflict with any of the standard predefined identifiers

items$()

Optional dynamic (variable length) string array, containing the initial items to be displayed in the combo box. Items are copied from the array to the combo box, starting at the lowest subscript of the array (LBOUND), continuing on toward the end of the array, until an empty string is encountered, or the highest subscript is reached. If an array with an LBOUND of zero (the default) is specified, be sure that the 1st element (0) contains data.

To create a combo box that is initially empty, either omit this parameter, or specify an array whose first element contains an empty string. If the combo box uses the %CBS_SORT style, the items are sorted alphanumerically as they are added to the combo box.

x, y

Integral expressions, variables, or numeric literal values, specifying the location of the control inside the dialog client area. x is the horizontal position, and y is the vertical position. 0,0 refers to the upper left corner of the dialog box client area. Coordinates are specified in the same terms (pixels or dialog units) as the parent dialog.

Integral expression, variable, or numeric literal value, specifying the width of the control. The width is given in the same terms (pixels or dialog units) as the parent dialog. The most common value used in the Microsoft Dialog Editor and Visual Studio is around 100 dialog units.

Integral expression, variable, or numeric literal value, specifying the height of the control. The height is given in the same terms (pixels or dialog units) as the parent dialog. The most common value used in the Microsoft Dialog Editor and Visual Studio is 40 dialog units.

style&

Primary style of the control.

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.

Combo box style	List box control	Text box control
Simple	No	Yes
Dropdown (default)	Yes	Yes
Dropdownlist	Yes	No

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.

The default combo box style comprises %CBS_DROPDOWN, %CBS_SORT, and %WS_TABSTOP. The default style is used only if both the primary and extended style parameter values are omitted from the statement. For example:

CONTROL ADD COMBOBOX, hDlg, id&, txt$(), 100, 100, 100, 40, , , CALL ComboCallback() ' Use default styles

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.

The primary combo box style value can be a combination of any values below, combined together with the OR operator to form a bitmask:

%CBS_AUTOHSCROLL	Automatically scroll the text in the text box to the right when the user types a character at the end of the line. If this style is not set, only text that fits within the rectangular boundary is allowed.
%CBS_DISABLENOSCROLL	Show a disabled vertical scroll bar in the list box when the box does not contain enough items to scroll. Without this style, the scroll bar is hidden when the list box does not contain enough items.
%CBS_DROPDOWN	Similar to %CBS_SIMPLE, except that the list box is not displayed unless the user selects the icon next to the edit control. (default)
%CBS_DROPDOWNLIST	Similar to %CBS_DROPDOWN, except that the text box is replaced by a (non-editable) label item that displays the current selection in the list box.
%CBS_HASSTRINGS	The combo box will contain strings. (persistent)
%CBS_LOWERCASE	Convert to lowercase any uppercase characters entered into the text box control portion of the combo box.
%CBS_NOINTEGRALHEIGHT	Create the list box portion of the combo box with exactly the size specified by the CONTROL ADD COMBOBOX statement. Without this style, Windows reduces the height of the list box portion of the combo box so that it does not display any partial (clipped) items.
%CBS_SIMPLE	Display the list box at all times. The current selection in the list box is displayed in the text box.
%CBS_SORT	Automatically sorts strings added to the combo box. (default)
%CBS_UPPERCASE	Convert any characters entered into the text box of a combo box into uppercase.
%WS_DISABLED	Create a control that is initially disabled. A disabled control cannot receive input from the user. Use the CONTROL ENABLE statement to re-enable a disabled control.
%WS_GROUP	Define the start of a group of controls. The first control in each group should also use %WS_TABSTOP style. The next %WS_GROUP control in the tab order defines the end of this group and the start of a new group.
%WS_TABSTOP	Allow combo box control to receive keyboard focus when the user presses the TAB and SHIFT+TAB keys. The TAB key shifts keyboard focus to the next control with the %WS_TABSTOP style, and SHIFT+TAB shifts focus to the previous control with %WS_TABSTOP. (default)
%WS_VSCROLL	Allow the control to display a vertical scroll bar if the list is longer than the height of the combo box. Use in conjunction with %CBS_DISABLENOSCROLL to make the scroll bar visible at all times.

Do not intermix list box styles with similarly named combo box styles as the numeric values of similar styles can produce unexpected results. For example, %LBS_SORT =&H2 and %CBS_SORT = &H100. Combo box styles are prefixed with %CBS.

exstyle&

Extended style of the combo box control. The default extended combo box style comprises %WS_EX_LEFT, and %WS_EX_CLIENTEDGE. The default extended style is only used if both the primary and extended parameters are omitted from the CONTROL ADD COMBOBOX statement, in the same manner as style& above.

The extended combo box style value can be a combination of any values below, combined together with the OR operator to form a bitmask:

%WS_EX_CLIENTEDGE	Apply a sunken edge border to the control. (default)
%WS_EX_LEFT	The control has generic "left-aligned" properties. (default)
%WS_EX_RIGHT	The control has generic "right-aligned" properties. This style has an effect only if the shell language is Hebrew, Arabic, or another language that supports reading order alignment; otherwise, the style is ignored.
%WS_EX_STATICEDGE	Apply a three-dimensional border style to the control (intended to be used for items that do not accept user input).
%WS_EX_TRANSPARENT	Controls/windows beneath the control are drawn before the control is drawn. The control is deemed transparent because elements behind the control have already been painted - the control itself is not drawn differently. True transparency is achieved by using Regions - see MSDN for more information.
%WS_EX_WINDOWEDGE	Apply a raised edge border to the control.

callback

Optional name of a Callback Function that receives all %WM_COMMAND and %WM_NOTIFY messages for the control. See the #MESSAGES metastatement to choose which messages will be received. If a callback for the control is not designated, you must create a dialog Callback Function to process messages from your control.

In general, when the control 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. Otherwise, the DDT engine processes unhandled messages.

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, and eventually to the DDT engine itself.

Notification messages are sent to the Callback Function, with CB.MSG = %WM_COMMAND, CB.CTL holding the ID (id&) of the control, and CB.CTLMSG holding the following values:

%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 CB.CTL and CB.CTLMSG to guarantee it is responding appropriately to the notification message.