McBasic™Get McBasic™ ↗
Build 881
Controls · Visual control
OptionButton component icon

OptionButton

Build mutually exclusive choices without coupling unrelated decisions.

40 properties18 events1 methodsDefault: Click

Use it in a Form#

Group identity matters more than distance on the canvas. Delivery, payment and customer type are independent decisions in this sample. Update the summary from the selected states, and inspect the difference between clicking the already-selected option and changing a value.

Add OptionButton to its intended parent and name it optStandard for this example:

PropertyExample value
EnabledTrue
VisibleTrue
Caption"Standard delivery"
GroupName"delivery"
CheckedTrue

Use the full lesson for the owner’s initialization code and its complete layout.

Properties#

Contract defaults are shown below. Where a new control has a different Designer starting value, that value is listed separately.

Left

DoubleDefault: 0

Horizontal position in device-independent points, relative to the parent container.

Range: -100000 to 100000.

Top

DoubleDefault: 0

Vertical position in device-independent points, relative to the parent container.

Range: -100000 to 100000.

Width

DoubleDefault: 120

Control width in device-independent points.

Range: 0 to 100000.

Designer starting value: 160.

Height

DoubleDefault: 32

Control height in device-independent points.

Range: 0 to 100000.

MinWidth

DoubleDefault: 0

Minimum control width in device-independent points; 0 lets the parent layout choose.

Range: 0 to 100000.

MinHeight

DoubleDefault: 0

Minimum control height in device-independent points; 0 lets the parent layout choose.

Range: 0 to 100000.

MaxWidth

DoubleDefault: 100000

Maximum control width in device-independent points.

Range: 0 to 100000.

MaxHeight

DoubleDefault: 100000

Maximum control height in device-independent points.

Range: 0 to 100000.

TabIndex

LongDefault: 0

Keyboard navigation order within the parent container; lower values come first.

Range: 0 to 100000.

ZIndex

LongDefault: 0

Stacking order among sibling controls; larger values appear in front. Equal values preserve document order.

Range: -100000 to 100000.

Anchor

StringDefault: "Left,Top"Not in InspectorNot serialized

Edges kept at their authored distance when the parent resizes. Use a comma-separated combination of Left, Top, Right and Bottom; Dock overrides the effective anchor without deleting it.

Dock

StringDefault: "None"

Automatic placement within the parent: None, Left, Top, Right, Bottom or Fill. Dock overrides effective Anchor layout without deleting the stored anchors.

Visible

BooleanDefault: True

Whether the control is shown in the running application.

Enabled

BooleanDefault: True

Whether the control accepts user interaction in the running application.

HitTestVisible

BooleanDefault: True

Whether the running control participates in pointer hit testing. The control remains selectable in the Designer.

AllowDrop

BooleanDefault: False

Whether this running control accepts application drag-and-drop operations; Designer movement is separate.

DragMode

LongDefault: 0

VB control drag: 0 Manual (code starts a drag with the Drag method) or 1 Automatic (a left-button press starts a drag, and the control raises no Click, MouseDown or MouseUp for that press).

Range: 0 to 1.

DragIcon

StringDefault: ""

Case-insensitive name of a declared project image resource shown under the pointer while this control is dragged; empty shows a grey outline of the control.

TabStop

BooleanDefault: True

Whether Tab navigation can move focus to this OptionButton.

Font

StringDefault: ""

Font as Family|Size or Family|Size|Regular/Bold|Normal/Italic, size 6–96 DIP. Empty uses the theme font; System uses the theme family.

ForeColor

StringDefault: ""

Text color as #RRGGBB. Empty uses the current macOS theme color.

BackColor

StringDefault: ""

Background color as #RRGGBB. Empty uses the current macOS theme color.

Margin

StringDefault: "0"

External spacing as one non-negative DIP value or Left,Top,Right,Bottom.

Cursor

StringDefault: "Default"

Pointer shown over the control: Default, Arrow, Hand, IBeam, Cross, Wait, Help, SizeAll, SizeNS, SizeWE, SizeNWSE, SizeNESW or NotAllowed.

Opacity

DoubleDefault: 1

Visual opacity from 0 (transparent) to 1 (opaque).

Range: 0 to 1.

DesignLocked

BooleanDefault: FalseDesigner only

Prevents movement and resizing in the Designer without changing runtime interaction.

AccessibleDescription

StringDefault: ""

Additional help text announced by assistive technology.

AutomationId

StringDefault: ""

Stable automation identifier; empty uses the component Name.

AccessibleName

StringDefault: ""

Name announced by assistive technology. Empty uses the stable control Name.

AccessibleRole

StringDefault: "Auto"

Accessibility role override. Auto preserves the native semantic role; explicit values use the corresponding platform automation role.

ToolTipText

StringDefault: ""

Help text shown when the pointer rests over the running control; empty disables the tooltip.

Tag

StringDefault: ""

Application-defined text associated with this control; McBasic™ does not interpret it.

Caption

StringDefault: ""

Text displayed by the control.

Designer starting value: "OptionButton".

WordWrap

BooleanDefault: False

Wraps the displayed caption within the available control width; false keeps a single line.

TextTrimming

StringDefault: "None"

Overflow behavior for an unwrapped caption: None, CharacterEllipsis or WordEllipsis.

Padding

StringDefault: "4"

Inner spacing around the glyph and caption as one non-negative DIP value or Left,Top,Right,Bottom.

Checked

BooleanDefault: FalseNot in Inspector

Legacy BASIC/layout alias for Value. New designs edit Value; both names address one Boolean state.

Value

BooleanDefault: False

Canonical VB-compatible Boolean state of the OptionButton.

GroupName

StringDefault: ""

Optional Form-wide exclusive group name. Empty groups the OptionButton with siblings in its immediate container.

Index

LongDefault: -1Read only in BASICDesigner Index row

Position of this control in its control array, 0 to 32767. Several controls share one name only when every one of them has an Index. Absent from the layout, and -1 in code, when the control is not in an array.

Designer values: 0 to 32767. Clear the dedicated Index row for a non-array control; BASIC then reads -1.

Events and parameters#

Replace control with the object’s Name when creating a handler. ByRef arguments may be changed by your handler; ByVal arguments report an input value.

Click

Occurs once when the component is logically activated by the user.

Signature — see the complete lesson for an implementation
Private Sub control_Click()

No parameters.

Change

Occurs after the component value changes according to its McBasic™ change policy.

Signature — see the complete lesson for an implementation
Private Sub control_Change()

No parameters.

DragEnter

Occurs when runtime drag data enters this control; set Effect to Copy, Move, Link or None.

Signature — see the complete lesson for an implementation
Private Sub control_DragEnter(ByVal Data As DragData, ByRef Effect As DragEffect, ByVal X As Double, ByVal Y As Double)
ParameterTypeDirection
DataDragDataByVal
EffectDragEffectByRef
XDoubleByVal
YDoubleByVal

DragOver

Occurs while runtime drag data moves over this control; Effect may be updated for the current position.

Signature — see the complete lesson for an implementation
Private Sub control_DragOver(ByVal Data As DragData, ByRef Effect As DragEffect, ByVal X As Double, ByVal Y As Double)
ParameterTypeDirection
DataDragDataByVal
EffectDragEffectByRef
XDoubleByVal
YDoubleByVal

DragOver

Occurs while a control dragged inside the app (DragMode or the Drag method) moves over this control: State is 0 when it enters, 2 while it moves over and 1 when it leaves; Source is the dragged control and X, Y are local DIP coordinates.

Signature — see the complete lesson for an implementation
Private Sub control_DragOver(ByVal Source As Control, ByVal X As Single, ByVal Y As Single, ByVal State As Integer)
ParameterTypeDirection
SourceControlByVal
XSingleByVal
YSingleByVal
StateIntegerByVal

DragLeave

Occurs when runtime drag data leaves this control without a drop.

Signature — see the complete lesson for an implementation
Private Sub control_DragLeave()

No parameters.

Drop

Occurs when runtime drag data is dropped on this control with a stable McBasic™ effect and local DIP coordinates.

Signature — see the complete lesson for an implementation
Private Sub control_Drop(ByVal Data As DragData, ByVal Effect As DragEffect, ByVal X As Double, ByVal Y As Double)
ParameterTypeDirection
DataDragDataByVal
EffectDragEffectByVal
XDoubleByVal
YDoubleByVal

DragDrop

Occurs when a control dragged inside the app (DragMode or the Drag method) is released over this control; Source is the dragged control and X, Y are local DIP coordinates.

Signature — see the complete lesson for an implementation
Private Sub control_DragDrop(ByVal Source As Control, ByVal X As Single, ByVal Y As Single)
ParameterTypeDirection
SourceControlByVal
XSingleByVal
YSingleByVal

MouseDown

Occurs when a pointing-device button is pressed over this control; Button is stable McBasic™ identity and X/Y are control-local DIP coordinates.

Signature — see the complete lesson for an implementation
Private Sub control_MouseDown(ByVal Button As MouseButton, ByVal Shift As KeyModifiers, ByVal X As Double, ByVal Y As Double)
ParameterTypeDirection
ButtonMouseButtonByVal
ShiftKeyModifiersByVal
XDoubleByVal
YDoubleByVal

MouseUp

Occurs when a pointing-device button is released for this control; Button is stable McBasic™ identity and X/Y are control-local DIP coordinates.

Signature — see the complete lesson for an implementation
Private Sub control_MouseUp(ByVal Button As MouseButton, ByVal Shift As KeyModifiers, ByVal X As Double, ByVal Y As Double)
ParameterTypeDirection
ButtonMouseButtonByVal
ShiftKeyModifiersByVal
XDoubleByVal
YDoubleByVal

MouseMove

Occurs when the pointer moves over the logical McBasic™ control; Button contains the currently held buttons and X/Y are local DIP coordinates.

Signature — see the complete lesson for an implementation
Private Sub control_MouseMove(ByVal Button As MouseButtons, ByVal Shift As KeyModifiers, ByVal X As Double, ByVal Y As Double)
ParameterTypeDirection
ButtonMouseButtonsByVal
ShiftKeyModifiersByVal
XDoubleByVal
YDoubleByVal

MouseEnter

Occurs once when the pointer enters the effective bounds of the logical McBasic™ control.

Signature — see the complete lesson for an implementation
Private Sub control_MouseEnter()

No parameters.

MouseLeave

Occurs once when the pointer leaves the effective bounds of the logical McBasic™ control.

Signature — see the complete lesson for an implementation
Private Sub control_MouseLeave()

No parameters.

DoubleClick

Occurs when native system timing recognizes a primary-button double activation on the same logical McBasic™ control.

Signature — see the complete lesson for an implementation
Private Sub control_DoubleClick()

No parameters.

GotFocus

Occurs once when the OptionButton receives effective keyboard focus.

Signature — see the complete lesson for an implementation
Private Sub control_GotFocus()

No parameters.

LostFocus

Occurs once when the OptionButton loses effective keyboard focus.

Signature — see the complete lesson for an implementation
Private Sub control_LostFocus()

No parameters.

KeyDown

Occurs when a physical key is pressed while this control owns effective keyboard focus; setting Handled suppresses normal processing.

Signature — see the complete lesson for an implementation
Private Sub control_KeyDown(ByVal KeyCode As KeyCode, ByVal Shift As KeyModifiers, ByRef Handled As Boolean)
ParameterTypeDirection
KeyCodeKeyCodeByVal
ShiftKeyModifiersByVal
HandledBooleanByRef

KeyPress

Occurs for committed Unicode text input; set Handled to suppress the control default.

Signature — see the complete lesson for an implementation
Private Sub control_KeyPress(ByVal Character As String, ByRef Handled As Boolean)
ParameterTypeDirection
CharacterStringByVal
HandledBooleanByRef

KeyUp

Occurs when a physical key is released while this control owns effective keyboard focus; setting Handled suppresses normal processing.

Signature — see the complete lesson for an implementation
Private Sub control_KeyUp(ByVal KeyCode As KeyCode, ByVal Shift As KeyModifiers, ByRef Handled As Boolean)
ParameterTypeDirection
KeyCodeKeyCodeByVal
ShiftKeyModifiersByVal
HandledBooleanByRef

Methods#

SetFocus

Method contract
Sub SetFocus()

Call on your instance: optStandard.SetFocus.

Source baseline 20f4bfed6b · Build manifest