Frame class

A Frame is a Win32 native container control that groups a set of related controls inside a captioned border. It serves two distinct purposes — a visual cue that the enclosed controls belong together, and a logical grouping for OptionButton controls: option buttons inside the same frame are mutually exclusive of one another but independent of option buttons elsewhere on the form. Controls dropped onto a frame at design time become its children, and moving, hiding, disabling, or destroying the frame moves, hides, disables, or destroys the entire group with it.

A frame cannot itself receive the input focus. The mnemonic marker (&) in its Caption is honoured, but pressing Alt+ that character moves the focus to the next control in tab order rather than to the frame itself — exactly like a Label.

The default property is Caption and the default event is Click.

Private Sub Form_Load()
    fraOutput.Caption = "&Output format"
    optHTML.Caption     = "&HTML"
    optMarkdown.Caption = "&Markdown"
    optPlain.Caption    = "&Plain text"
    optHTML.Value = True            ' default selection within fraOutput
End Sub

Private Sub fraOutput_Click()
    Debug.Print "Frame clicked (between the option buttons)"
End Sub

• Container behaviour
• Caption, mnemonics, and the border
• OptionButton groups
• Transparency and opacity
• Properties
• Methods
• Events

Container behaviour

A frame is a true container: each control inside it has the frame’s hWnd as its Win32 parent and its coordinates are relative to the frame’s client area, not the form. As a result:

• Toggling Visible or Enabled affects every contained control.
• Calling Move re-positions the frame and the children move with it without each child raising its own resize.
• The frame’s Anchors and Dock settings let it stretch with its parent so the whole group resizes together.
• A control’s Container property returns the frame it lives in (and the frame’s own Container returns the form, or another frame, that hosts it).

Caption, mnemonics, and the border

The text in Caption is rendered along the top edge of the border by the standard Win32 group-box style. An ampersand in the caption marks the next character as a keyboard mnemonic; use && to display a literal ampersand. Pressing Alt+ the marked character moves the focus to the next control in tab order — the frame does not take focus itself.

BorderStyle chooses between the standard captioned single-line border (vbFixedSingleBorder, the default) and a borderless mode (vbNoBorder). In vbNoBorder mode the standard group-box rendering is bypassed entirely — neither the line nor the caption text is drawn — and the frame becomes a plain rectangular region. Appearance further selects between the 3-D and flat variant of the standard border.

OptionButton groups

Each frame defines its own option-button group. When the user selects an OptionButton whose parent is this frame, every other option button on the same frame is automatically cleared, but option buttons on the form (or in sibling frames) are not affected. Use frames to present multiple independent radio-style choices on the same form:

' Two independent option-button groups on one form:
'   fraSize:    optSmall, optMedium, optLarge
'   fraColour:  optRed, optGreen, optBlue

Transparency and opacity

Opacity and TransparencyKey drive Windows’ layered-window features. Setting Opacity below 100 makes the frame and its contained controls translucent; setting TransparencyKey to a colour makes pixels of that colour fully transparent on screen. Both features require Windows 8 or later when the frame contains child controls — otherwise only the frame’s own background is affected.

Properties

Anchors

The set of edges of the parent that the frame’s corresponding edges follow when the parent resizes. Read-only — assign individual .Left, .Top, .Right, .Bottom flags through the returned Anchors object.

Appearance

Determines how the frame’s border is drawn by the OS. A member of AppearanceConstants: vbAppearFlat or vbAppear3d (default).

BackColor

The background colour of the frame’s client area, as an OLE_COLOR. Defaults to the system 3-D face colour. Painted behind contained controls.

BorderStyle

The style of the frame’s border. A member of ControlBorderStyleConstants: vbFixedSingleBorder (1, default — the captioned group-box line) or vbNoBorder (0). With vbNoBorder the caption is also suppressed and the frame becomes a borderless background panel.

Caption

The text rendered along the top edge of the frame’s border. String. Default property.

Syntax: object.Caption [ = string ]

An ampersand marks the next character as a mnemonic; && produces a literal ampersand. The string is read directly from the underlying window — assigning to Caption updates the rendering immediately.

ClipControls

Whether child controls are clipped out of the frame’s drawing region during paint. Boolean, default True. Changing ClipControls at run time recreates the underlying window.

Container

The control that hosts this frame — typically the form, or another frame. Read with Get, change with Set. Setting Container re-parents the frame to a different container at run time.

ControlType

A read-only ControlTypeConstants value identifying this control as a frame. Always vbFrame.

Dock

Where the frame is docked within its container. A member of DockModeConstants: vbDockNone (default), vbDockLeft, vbDockTop, vbDockRight, vbDockBottom, or vbDockFill. Docked frames ignore Anchors.

DragIcon

A StdPicture used as the mouse cursor while the frame is being drag-and-dropped (see Drag and DragMode).

DragMode

Whether the frame should drag itself when the user holds the mouse over it. A member of DragModeConstants: vbManual (0, default — call Drag from code) or vbAutomatic (1).

Enabled

Determines whether the frame and its contained controls accept user input. A disabled frame dims its contents and ignores mouse and keyboard interaction. Boolean, default True. Changing Enabled triggers an immediate repaint so the border reflects the new state.

Font

The StdFont used to render Caption. The convenience properties FontBold, FontItalic, FontName, FontSize, FontStrikethru, and FontUnderline read or write the corresponding members of this object.

FontBold

Shortcut for Font.Bold. Boolean.

FontItalic

Shortcut for Font.Italic. Boolean.

FontName

Shortcut for Font.Name. String.

FontSize

Shortcut for Font.Size. Single, in points.

FontStrikethru

Shortcut for Font.Strikethrough. Boolean.

FontUnderline

Shortcut for Font.Underline. Boolean.

ForeColor

The colour used to draw Caption, as an OLE_COLOR. Defaults to the system button-text colour.

Height

The frame’s height, in twips by default (or in the container’s ScaleMode units). Double.

HelpContextID

A Long identifying a topic in the application’s help file, retrieved when the user invokes context help while the frame has the active control underneath it.

hWnd

The Win32 window handle for the frame, as a LongPtr. Read-only. Useful for passing to API functions.

Index

When the frame is part of a control array, the Long zero-based index of this instance within the array. Reading Index on a non-array instance raises run-time error 343 (Object not an array). Read-only at run time.

Left

The horizontal distance from the left edge of the container to the left edge of the frame. Double.

MouseIcon

A StdPicture used as the mouse cursor when MousePointer is vbCustom and the pointer is over the frame.

MousePointer

The mouse cursor shown when the pointer is over the frame (and not over a child control with its own setting). A member of MousePointerConstants.

MultiFramePosition

When the frame is hosted inside a MultiFrame layout container, the Long zero-based position of this frame in the MultiFrame’s ordered sequence. Default -1 (no position assigned). Outside of a MultiFrame the value is ignored.

MultiFrameSize

When the frame is hosted inside a MultiFrame, its size as a percentage of the MultiFrame’s usable extent (0 for “share evenly”). Double. Outside of a MultiFrame the value is ignored.

Name

The unique design-time name of the frame on its parent form. Read-only at run time.

OLEDropMode

How the frame responds to OLE drops. A restricted member of OLEDropConstants: vbOLEDropNone or vbOLEDropManual. Automatic-drop mode is not supported on a Frame; assigning vbOLEDropAutomatic raises run-time error 5.

Opacity

The frame’s opacity as a percentage (0–100, default 100). Values outside the range are clamped on Initialize. Values below 100 require Windows 8 or later when the frame has child controls; out-of-process child windows are not affected.

OriginalMultiFramePosition

The frame’s MultiFramePosition at the moment the MultiFrame was last reflowed. Long, default -1. Used internally by the MultiFrame layout engine to compact positions after a frame is moved; not normally written from user code.

Parent

A reference to the Form (or UserControl) that ultimately contains the frame. Read-only. Distinct from Container, which returns the immediate parent (form or enclosing frame).

RightToLeft

Note

Reserved for compatibility with VB6; not currently implemented in twinBASIC.

TabIndex

The position of the frame in the form’s TAB-key navigation order. Long. The frame itself does not receive focus, but TabIndex controls where the frame’s mnemonic forwards focus to: Alt+ the marked character moves to the next focusable control whose TabIndex is greater than this one.

Tag

A free-form String the application can use to associate custom data with the frame. Ignored by the framework.

ToolTipText

A multi-line String displayed as a tooltip when the user hovers over the frame’s border or background.

Top

The vertical distance from the top of the container to the top of the frame. Double.

TransparencyKey

An OLE_COLOR that, when set, becomes fully transparent in the rendered frame — clicks pass through to whatever is underneath, and the corresponding pixels do not paint. Default -1 disables the effect. Requires Windows 8 or later when the frame has child controls.

Visible

Whether the frame and its contained controls are shown. Boolean, default True.

VisualStyles

Whether the OS theme engine should be used when drawing the frame border and caption. Boolean, default True.

WhatsThisHelpID

Note

Reserved for compatibility with VB6; not currently implemented in twinBASIC. See ShowWhatsThis.

Width

The frame’s width. Double.

Methods

Drag

Begins, completes, or cancels a manual drag-and-drop operation. Typically called from a MouseDown handler when DragMode is vbManual.

Syntax: object.Drag [ Action ]

Action

optional A member of DragConstants: vbCancel (0), vbBeginDrag (1, default), or vbEndDrag (2).

Move

Repositions and optionally resizes the frame in a single call. Contained controls are repositioned with it.

Syntax: object.Move Left [, Top [, Width [, Height ] ] ]

Left

required A Single giving the new horizontal position.

Top, Width, Height

optional New values for the corresponding properties. Omitted values are left unchanged.

OLEDrag

Initiates an OLE drag operation from the frame, raising the OLEStartDrag event so the application can populate the DataObject.

Syntax: object.OLEDrag

Refresh

Forces an immediate repaint of the frame and its border.

Syntax: object.Refresh

SetFocus

Attempts to move the input focus to the frame. Because a frame is not focusable, this call has no observable effect on which control holds the focus, but it is provided for parity with the rest of the control surface and for compatibility with code that calls SetFocus generically.

Syntax: object.SetFocus

ShowWhatsThis

Note

Reserved for compatibility with VB6; not currently implemented in twinBASIC.

Syntax: object.ShowWhatsThis

ZOrder

Brings the frame to the front or back of its sibling stack within the container.

Syntax: object.ZOrder [ Position ]

Position

optional A member of ZOrderConstants: vbBringToFront (0, default) or vbSendToBack (1).

Events

Click

Raised when the user single-clicks the frame’s client area or border (i.e. not over any contained control). Default event.

Syntax: object_Click( )

DblClick

Raised when the user double-clicks the frame’s client area or border.

Syntax: object_DblClick( )

DragDrop

Raised on the destination control when a manual drag operation ends over this frame.

Syntax: object_DragDrop( Source As Control, X As Single, Y As Single )

DragOver

Raised on the frame while a manual drag operation is in progress over it.

Syntax: object_DragOver( Source As Control, X As Single, Y As Single, State As Integer )

Initialize

Raised once, after the frame’s underlying window has been created but before any contained controls are populated. Useful for setting initial values that the frame’s children will read on their own initialisation.

Syntax: object_Initialize( )

MouseDown

Raised when the user presses any mouse button over the frame’s client area or border.

Syntax: object_MouseDown( Button As Integer, Shift As Integer, X As Single, Y As Single )

MouseMove

Raised when the cursor moves over the frame’s client area or border.

Syntax: object_MouseMove( Button As Integer, Shift As Integer, X As Single, Y As Single )

MouseUp

Raised when the user releases a mouse button over the frame’s client area or border.

Syntax: object_MouseUp( Button As Integer, Shift As Integer, X As Single, Y As Single )

MouseWheel

Raised when the mouse wheel turns over the frame. New in twinBASIC.

Syntax: object_MouseWheel( Delta As Integer, Horizontal As Boolean )

OLECompleteDrag

Raised on the source control when the OLE drag operation finishes, indicating which effect (copy, move, none) the destination accepted.

Syntax: object_OLECompleteDrag( Effect As Long )

OLEDragDrop

Raised on the frame when the user drops data on it.

Syntax: object_OLEDragDrop( Data As DataObject, Effect As Long, Button As Integer, Shift As Integer, X As Single, Y As Single )

OLEDragOver

Raised on the frame while an OLE drag passes over it.

Syntax: object_OLEDragOver( Data As DataObject, Effect As Long, Button As Integer, Shift As Integer, X As Single, Y As Single, State As Integer )

OLEGiveFeedback

Raised on the source control during a drag so the application can adjust the cursor or other visual feedback.

Syntax: object_OLEGiveFeedback( Effect As Long, DefaultCursors As Boolean )

OLESetData

Raised on the source control when the destination requests data in a format that was registered but not yet supplied.

Syntax: object_OLESetData( Data As DataObject, DataFormat As Integer )

OLEStartDrag

Raised on the source control at the start of an OLE drag, so the application can populate the DataObject and choose the allowed effects.

Syntax: object_OLEStartDrag( Data As DataObject, AllowedEffects As Long )