OptionButtonW class
An OptionButtonW is an option button: a round button with a caption beside it, one of several in a container of which the user selects one. It can show a picture, look like a push button that stays down while it is selected, and leave its drawing to the program.

OptionButtonW1.Caption = "&Metric " & ChrW$(&H3A9) ' the caption is Unicode: a Greek capital omega
Debug.Print OptionButtonW1.Value
OptionButtonW1.Value = True
Debug.Print OptionButtonW1.Value; Len(OptionButtonW1.Caption)
' Output:
' False
' True 9
The control stands in place of the OptionButton of VB6, which in twinBASIC is the OptionButton of the VB package. This one adds a picture from an image list beside the caption (ImageList), PushLike, WordWrap, TextAlignment and VerticalAlignment, Transparent, and drawing by the program (DrawMode).
Of the common members, the control has those under Name and place, Window handles, Font and visual styles, Mouse, Keyboard and focus, Dragging the control, OLE drag and drop and Right-to-left but RightToLeftLayout. Its Click event has a meaning of its own.
- Selecting an option
- Caption and pictures
- The graphical style
- Drawing the control in code
- Properties
- Events
- OptImageListAlignmentConstants
- OptDrawModeConstants
- See Also
Selecting an option
Value is True while the option is selected. The user selects it with a click on the control. The option buttons of one container are a group, of which one is selected at a time; those in a frame or a picture box are a group of their own. The control leaves it to the form to clear the other option buttons of the group when one becomes True.
Warning BETA 1042
The form does not clear the other option buttons of the group, so two of them can be selected at once, by the user or by the program. A program clears them itself, in each button’s Click event:
Private Sub OptionButtonW1_Click()
OptionButtonW2.Value = False
End Sub
Private Sub OptionButtonW2_Click()
OptionButtonW1.Value = False
End Sub
Click is raised when Value becomes True, whether the user or the program made it so. Nothing is raised when it becomes False, and nothing when the user clicks an option that is selected already.
Private Sub OptionButtonW1_Click()
Debug.Print "Selected: "; OptionButtonW1.Caption
End Sub
Caption and pictures
In the standard Style the control shows its round button and, beside it, either the Caption or a picture. Alignment puts the button at the left or the right of the control. TextAlignment, VerticalAlignment and WordWrap place the caption in the room that is left.
A picture comes from one of two places:
- Picture is shown in place of the caption.
- An ImageList control assigned to the ImageList property is shown together with the caption, at the side that ImageListAlignment names and at the distance of ImageListMargin from the edge. The control shows the image list’s pictures when the program has visual styles. While an image list is assigned, Picture is not shown.
The image list holds one picture, which the control shows in every state, or one picture for each state in this order: normal, under the mouse, pressed, disabled, with the focus, under a pen.
OptionButtonW1.ImageList = "ImageList1" ' by the name of the control on the form
OptionButtonW1.ImageListAlignment = OptImageListAlignmentTop
OptionButtonW1.ImageListMargin = 60
The graphical style
With Style set to vbButtonGraphical the control is a push button that stays down while it is selected, drawn by the control itself: the picture in the middle and the caption under it, centered. Picture is the picture of the button when it is up, DownPicture when it is down or selected, and DisabledPicture when it is disabled. With UseMaskColor the color MaskColor of a bitmap is not drawn. The button has the BackColor and the caption the ForeColor.
In this style Alignment, TextAlignment, VerticalAlignment, WordWrap, PushLike and ImageList have no effect.
PushLike is the other way to a button that stays down: it keeps the standard style, so the caption’s alignment and the image list still apply, and Windows draws the button.

Drawing the control in code
With DrawMode set to OptDrawModeOwnerDraw the control draws nothing. It raises OwnerDraw each time it has to be drawn, and the handler draws the whole control, its state included, on the device context the event gives it.
The graphical style and this mode exclude each other. Setting Style to vbButtonGraphical in this mode raises run-time error 383, and setting DrawMode to OptDrawModeOwnerDraw makes a graphical Style standard.
OptionButtonW1.Style = vbButtonGraphical
OptionButtonW1.DrawMode = OptDrawModeOwnerDraw
Debug.Print OptionButtonW1.Style
On Error Resume Next
OptionButtonW1.Style = vbButtonGraphical
Debug.Print Err.Number; OptionButtonW1.Style
' Output:
' 0
' 383 0
In the graphical style and in this mode, the option also becomes selected when the control takes the focus.
Properties
Alignment
The side of the control that the round button is at. A member of CCLeftRightAlignmentConstants. Default: CCLeftRightAlignmentLeft, with the caption to the right of the button. Another value raises run-time error 380.
Appearance
Whether the round button is drawn flat or with a sunken edge. A member of CCAppearanceConstants. Default: CCAppearance3D. Another value raises run-time error 380. The flat button shows where the control is drawn without visual styles.
Setting the property also sets ForeColor: to vbWindowText for the flat appearance and to vbButtonText for the other.
BackColor
The color behind the round button and the caption, and the color of the button in the graphical style where the control is drawn without visual styles. OLE_COLOR. Default: vbButtonFace.
Caption
The text beside the round button. String. A control newly drawn on a form has its own name.
The character after an & is underlined, and the Alt key with that character moves the focus to the control. Two of them, &&, show one &.
DisabledPicture
The picture of a disabled control in the graphical Style. A picture object, or Nothing (the default): the control then shows Picture, grayed.
DownPicture
The picture of the control in the graphical Style while it is held down or selected. A picture object, or Nothing (the default): the control then shows Picture.
DrawMode
Whether the control draws itself or leaves the drawing to the OwnerDraw event. A member of OptDrawModeConstants. Default: OptDrawModeNormal. Another value raises run-time error 380. A change makes the control’s window again, so hWnd changes. See Drawing the control in code.
ForeColor
The color of the caption. OLE_COLOR. A control newly drawn on a form has black. Appearance changes it.
The control uses it in the graphical Style. In the standard style a control drawn with visual styles has the caption color of the visual style.
Hot
Whether the mouse is over the control, as Windows reports it for a control with visual styles. Boolean, read-only.
Assigning to it raises run-time error 383.
ImageList
The image list whose pictures the control shows beside its caption. See Caption and pictures.
The property takes one of three things:
- an ImageList control of the package. The property then returns the control.
- a String: the name of an ImageList control on the same form. The property then returns the control.
- a Long or a LongLong: the handle of an image list of Windows. The property then returns the handle.
Nothing, the handle 0, a name that no ImageList control on the form has, and an image list that holds no picture all leave the control without an image list: the property then returns Nothing. An object of another class raises run-time error 35610, and a value of another type, an Integer included, raises run-time error 13.
ImageListAlignment
Where the picture of the image list is, relative to the caption. A member of OptImageListAlignmentConstants. Default: OptImageListAlignmentLeft. Another value raises run-time error 380.
Setting RightToLeft to True changes OptImageListAlignmentLeft to OptImageListAlignmentRight, and setting it to False changes it back.
ImageListMargin
The distance between the picture of the image list and the edge of the control that ImageListAlignment names, in the scale units of the control’s container. Single. Default: 0. The control keeps it as a whole number of pixels. With OptImageListAlignmentCenter it has no effect.
A negative value raises run-time error 380.
MaskColor
The color of a bitmap that the control does not draw, in the graphical Style and while UseMaskColor is True. OLE_COLOR. Default: &HC0C0C0, light gray.
Picture
The picture the control shows. A picture object, or Nothing (the default).
In the standard Style an icon or a bitmap is shown in place of the caption, unless an ImageList is assigned. In the graphical style the picture is drawn in the middle of the button, above the caption.
Pushed
Whether the control is drawn as held down. Boolean. It is True while the user holds the mouse button or the space key down on the control. Setting it changes how the control is drawn and raises no event.
PushLike
Whether the control, in the standard Style, looks like a push button that stays down while it is selected. Boolean. Default: False.
Style
Whether Windows draws the control as an option button or the control draws itself as a button with a picture. A member of ButtonConstants: vbButtonStandard (the default) or vbButtonGraphical. Another value raises run-time error 380. See The graphical style.
Setting it to vbButtonGraphical while DrawMode is OptDrawModeOwnerDraw raises run-time error 383. A change makes the control’s window again, so hWnd changes.
TextAlignment
Where the caption is in the room beside the round button. A member of AlignmentConstants. Default: vbLeftJustify. Another value raises run-time error 380.
Setting RightToLeft to True changes vbLeftJustify to vbRightJustify, and setting it to False changes it back.
Transparent
Whether the control’s background is a copy of what its container draws behind it, so that a picture or a gradient on the form shows through. Boolean. Default: False. The control takes the copy when it is first drawn, and again after a change of its size and after Refresh.
UseMaskColor
Whether the color MaskColor of a bitmap is left out when the control draws the bitmap in the graphical Style. Boolean. Default: False.
Value
Whether the option is selected. Boolean. Default: False. It is the control’s default property. See Selecting an option.
VerticalAlignment
Whether the caption is at the top, the middle or the bottom of the control. A member of CCVerticalAlignmentConstants. Default: CCVerticalAlignmentCenter. Another value raises run-time error 380.
WordWrap
Whether a caption too long for one line continues on the next. Boolean. Default: True.
Events
Click
Raised when Value has become True: by the user, or by an assignment in code. See Selecting an option.
Syntax: object_Click( )
HotChanged
Raised when the mouse moves onto the control or leaves it, where the control is drawn with visual styles. Hot tells which.
Syntax: object_HotChanged( )
OwnerDraw
Raised when the control has to be drawn, while DrawMode is OptDrawModeOwnerDraw.
Syntax: object_OwnerDraw( ByVal Action As Long, ByVal State As Long, ByVal hDC As Long, ByVal Left As Long, ByVal Top As Long, ByVal Right As Long, ByVal Bottom As Long )
- Action
- Why the control is drawn, as a sum of: 1, the whole control has to be drawn; 2, it was pressed or released; 4, it took or lost the focus.
- State
- The state to draw, as a sum of: 1, held down; 4, disabled;
&H10, with the focus;&H40, under the mouse, which the control reports only while MouseTrack is True;&H100, without the underline of the access key;&H200, without the focus rectangle. - hDC
- The handle of the device context to draw on.
- Left, Top, Right, Bottom
- The rectangle of the control, in pixels.
The event does not give the control’s Value: the handler reads it and draws the round button accordingly.
OptImageListAlignmentConstants
The values of ImageListAlignment.
| Member | Value | Description |
|---|---|---|
| OptImageListAlignmentLeft | 0 | The picture is to the left of the caption. |
| OptImageListAlignmentRight | 1 | The picture is to the right of the caption. |
| OptImageListAlignmentTop | 2 | The picture is above the caption. |
| OptImageListAlignmentBottom | 3 | The picture is under the caption. |
| OptImageListAlignmentCenter | 4 | The picture is in the middle of the control. |
OptDrawModeConstants
The values of DrawMode.
| Member | Value | Description |
|---|---|---|
| OptDrawModeNormal | 0 | The control is drawn by Windows, or by itself in the graphical style. |
| OptDrawModeOwnerDraw | 1 | The program draws the control, in the OwnerDraw event. |
See Also
- Common members – the members this control shares with the package’s other controls
- CheckBoxW class – a check box with the same pictures, styles and drawing
- CommandButtonW class – a push button
- FrameW class – a frame that makes the option buttons in it a group
- OptionButton – the option button of the VB package