CONTROL ADD BUTTON statement

Purpose

Add a command button to a dialog. A command button is a button that causes an action to occur when the button is clicked. A common example of a command button is the "OK" button on a message box dialog.

Syntax

CONTROL ADD BUTTON, hDlg, id&, txt$, x, y, xx, yy [, [style&] [, [exstyle&]]] [[,] CALL callback]

hDlg

Handle of the dialog in which the button will be created. The dialog will become the parent of the command button.

id&

Unique identifier for the button in the range 1 to 65535, frequently specified with numeric equates for clarity of the code. For example, the equate %NewAccount 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.

However, it is typical for a dialog to include an OK and/or a Cancel button, represented by the predefined equates %IDOK and %IDCANCEL respectively. A button with an ID of %IDOK is triggered (clicked) when the ENTER key is pressed by the user, and a button with the ID of %IDCANCEL is triggered when the ESCAPE key is pressed. These and other predefined "standard" equates can be found in the WIN32API.INC and DDT.INC files.

txt$

Text to be displayed in the button. An ampersand (&) may be included in txt$ to specify a hot-key. See the Remarks section below. OK and Cancel/Close buttons do not usually contain accelerators, since such buttons usually respond to the ENTER and ESCAPE keystrokes, respectively.

x, y

Integer 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.

Integer expression, variable, or numeric literal value, specifying the width of the button. 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 50 dialog units.

Integer expression, variable, or numeric literal value, specifying the height of the button. 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 14 dialog units.

style&

Primary style of the button. The default button style comprises %BS_CENTER, %BS_VCENTER, and %WS_TABSTOP. The default style is used if both the primary and extended style parameters are omitted from the statement. For example:

CONTROL ADD BUTTON, hDlg, id&, txt$, 100, 100, 150, 200, , , _

CALL ButtonCallback() ' 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 button style value can be a combination of any values below, combined together with the OR operator to form a bitmask:

%BS_BOTTOM	Place the text at the bottom of the button.
%BS_CENTER	Center the text horizontally in the button. (default)
%BS_DEFAULT	Create a button with a heavy black border. The user can select this button by pressing the ENTER key. This style is useful for enabling the user to quickly select the most likely option. You can only have one Default button per dialog. It is recommended to make id& = 1, or id& = %IDOK for this control. Synonym of %BS_DEFPUSHBUTTON.
%BS_DEFPUSHBUTTON	Synonym of %BS_DEFAULT.
%BS_FLAT	Create a flat button (without the raised 3D look).
%BS_LEFT	Place the text on the left side of the button.
%BS_MULTILINE	Wrap the caption text across multiple lines, if the text string is too long to fit on a single line. To force a wrap, insert a $CR (or $CRLF) into the caption text at the desired wrap position.
%BS_NOTIFY	Enable a button to send the %BN_KILLFOCUS and %BN_SETFOCUS notification messages to the button Callback Function.
%BS_PUSHLIKE	Button state alternates (toggles) between normal (raised) and depressed (sunken) modes.
%BS_RIGHT	Place the text on the right side of the button.
%BS_TOP	Place the text at the top edge of the button.
%BS_VCENTER	Center the text vertically in the button. (default)
%WS_BORDER	Add a thin line border around the control.
%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 the button.
%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. Groups configured this way permit the arrow keys to shift focus between the controls within the group, and focus can jump from group to group with the usual TAB and SHIFT+TAB keys. Both tab stops and groups are permitted to wrap from the end of the tab order back to the start.
%WS_TABSTOP	Allow button 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)

exstyle&

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

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

%WS_EX_LEFT	The button has generic "left-aligned" properties. (default)
%WS_EX_RIGHT	The button 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_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.

callback

Optional name of a Callback Function to receive all %WM_COMMAND notification messages for the button. If a callback for the button is not designated, you must create a Callback Function for the dialog to process notification messages from your button.

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

Remarks

If the ampersand (&) character appears in the txt$ parameter, the letter that follows will be displayed underscored. This adds a control accelerator (hot-key) to enable the user to directly "click" a control, simply by pressing and holding the ALT key while pressing the specified hot-key. For example, "E&xit" makes ALT+x the hot-key.

Unless the %BS_FLAT style is used, the button is drawn on the dialog using a 3-dimensional look. When the user clicks a button, a message is sent to the Callback Function designated for the button. If there is no Callback Function designated, the message is sent to the callback for the dialog.

In general, if 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.

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

%BN_CLICKED	Sent when the user clicks a mouse button, or activates the button with the hot-key (unless the button has been disabled).
%BN_DISABLE	Sent when a button is disabled.
%BN_KILLFOCUS	Sent when a button loses the keyboard focus. The button must include the %BS_NOTIFY style.
%BN_SETFOCUS	Sent when a button receives the keyboard focus. The button must include the %BS_NOTIFY style.

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.