Purpose |
Add an option button to a dialog. An option button is just like a conventional "radio button" control. | ||||||||||||||||||||||||||
Syntax |
CONTROL ADD OPTION, hDlg, id&, txt$, x, y, xx, yy [, [style&] [, [exstyle&]]] [[,] CALL callback] | ||||||||||||||||||||||||||
hDlg |
Handle of the dialog in which the option button 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 %DefCon5 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. | ||||||||||||||||||||||||||
txt$ |
Text to be displayed next to the option button. An ampersand (&) may be included in txt$ to specify a hot-key. See the Remarks section below. | ||||||||||||||||||||||||||
x, y |
| ||||||||||||||||||||||||||
xx |
Integer 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 40 dialog units. | ||||||||||||||||||||||||||
yy |
Integer 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 14 dialog units. | ||||||||||||||||||||||||||
style& |
Primary style of the option button control. The default option button styles are %WS_TABSTOP, %BS_LEFT, and %BS_VCENTER. The default styles are used if both the primary and extended style parameters are omitted from the statement. For example: CONTROL ADD OPTION, hDlg, id&, txt$, 100, 100, 150, 200, , , _ CALL OptionButtonCallback() ' Use default styles Custom style values replace the default values. That is, they are not in addition to the default style values - your code must specify all necessary primary and extended style parameters. The primary option button style value can be a combination of any values below, combined together with the OR operator to form a bitmask:
| ||||||||||||||||||||||||||
exstyle& |
Extended style of the option button control. The default extended option 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 OPTION statement completely, in the same manner as style& above. The extended option button style value can be a combination of any values below, combined together with the OR operator to form a bitmask:
| ||||||||||||||||||||||||||
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. 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 |
Option buttons are used for presenting a list of choices, only one of which may be selected. So, there is no point in having just a single option button. If what you want is to allow turning a single item on or off, use a Checkbox instead. When a group of option buttons are created, you should explicitly set the "selected" and "unselected" state of all option buttons, using the CONTROL SET OPTION statement to set the Check State of all the buttons in the group. In addition, the first OPTION control in a group should have the style %WS_GROUP (to mark the beginning of a group of buttons) and %WS_TABSTOP. The remainder of the OPTION controls in the group should not have %WS_GROUP or %WS_TABSTOP styles. However, the very next non-OPTION control to appear in the tab order after the group should be given the %WS_GROUP and %WS_TABSTOP styles (the latter may depend on the type of control it is). If there are no other controls after the group, add %WS_GROUP to the first control in the dialog. This ensures that keyboard navigation with the arrow keys will operate within the group of OPTION controls, and that the TAB and SHIFT+TAB keys will switch focus between whole groups of controls (instead of individual controls as is common when each group member has the %WS_TABSTOP style). 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 select the Option control, simply by pressing and holding the ALT key while pressing the specified hot-key. For example, "Level &3" makes ALT+3 the hot-key. When the user clicks an option button, 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. The following notifications are sent to the Callback Function:
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. | ||||||||||||||||||||||||||
See also |
Dynamic Dialog Tools, CONTROL ADD CHECK3STATE, CONTROL ADD CHECKBOX, CONTROL GET CHECK, CONTROL SET COLOR, CONTROL SET FONT, CONTROL SET OPTION | ||||||||||||||||||||||||||
Example |
Refer to the example in the CONTROL SET OPTION topic. |