VScrollBar class

A VScrollBar is a Win32 native vertical scroll bar exposed as a stand-alone control. Unlike the scroll bars that automatically appear inside a ListBox, ComboBox, or TextBox, a VScrollBar is independent of any other control --- its Value is whatever code reads or writes. The typical use is to control a numeric setting (a scroll offset, a brightness or opacity level, a colour channel, the vertical position of a custom-drawn surface) by binding the VScrollBar's Change and Scroll events to whatever the value represents.

HScrollBar is the horizontal counterpart; the two classes are identical apart from orientation.

The default property is Value and the default event is Change.

Private Sub Form_Load()
    vsbLevel.Min = 0
    vsbLevel.Max = 100
    vsbLevel.SmallChange = 1
    vsbLevel.LargeChange = 10
    vsbLevel.Value = 50
End Sub

Private Sub vsbLevel_Change()
    lblLevel.Caption = "Level: " & vsbLevel.Value & "%"
End Sub

Private Sub vsbLevel_Scroll()
    lblLevel.Caption = "Level: " & vsbLevel.Value & "%"   ' live update during drag
End Sub

Range and value

Min and Max define the closed range of integer values the scroll bar can represent, and Value is the position within that range. Defaults are 0, 32767, and 0. Assigning a Value outside the current [Min, Max] interval raises run-time error 380 (Invalid property value); assigning the current value is a no-op (no Change is raised).

The two endpoints may be supplied in either order. When Min is greater than Max the scroll bar runs inverted --- moving the thumb downward decreases Value, and Max is the lower bound of the legal range. This is convenient for, for example, a "high-at-top" volume or brightness slider:

vsbVolume.Min = 100    ' topmost == loudest
vsbVolume.Max = 0      ' bottommost == silent
vsbVolume.Value = 75

Changing Min or Max at run time clips the current Value into the new range silently --- no Change event is raised for the implicit clip.

Increment sizes

The scroll bar produces value changes through four kinds of user input:

Input	Increment per step	Event raised
Click an end-arrow	SmallChange	Change
Click the track above or below the thumb	LargeChange	Change
Drag the thumb	continuous	Scroll during drag, Change on release
Press Home / End	jumps to Min / Max	Change

Both SmallChange and LargeChange default to 1. LargeChange also controls the visible height of the thumb relative to the track, so larger values produce a chunkier thumb.

Change versus Scroll

The split between the two events lets the application choose how often it reacts to user input. Scroll fires repeatedly while the user is dragging the thumb, so a handler can update a live preview as the thumb moves. Change fires once each time the value settles --- after the user releases the thumb, after a click on an arrow or the track, or whenever code assigns a different Value. Many applications wire both events to the same handler so that the bound display updates both during dragging and after.

Properties

Anchors

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

CausesValidation

Determines whether the previously focused control's Validate event runs before this control receives the focus. Boolean, default True.

Container

The control that hosts this scroll bar --- typically the form, a Frame, or a UserControl. Read with Get, change with Set.

ControlType

A read-only ControlTypeConstants value identifying this control as a vertical scroll bar. Always vbVScrollBar.

Dock

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

DragIcon

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

DragMode

Whether the control 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 scroll bar accepts user input. A disabled scroll bar is greyed out and does not respond to mouse or keyboard interaction. Boolean, default True.

Height

The scroll bar's height in twips (or in the container's ScaleMode units). Double. For a vertical scroll bar this is the long dimension --- i.e., the length of the track.

HelpContextID

A Long identifying a topic in the application's help file, retrieved when the user presses F1 while the control has focus.

hWnd

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

Index

When the scroll bar 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.

LargeChange

The amount Value is adjusted when the user clicks the track above or below the thumb (or presses Page Up / Page Down while the scroll bar has focus). Long, default 1. Also influences the visible height of the thumb: bigger values produce a taller thumb relative to the track.

Left

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

Max

The upper end of the scroll bar's value range. Long, default 32767. May be set lower than Min to invert the direction of travel --- see Range and value.

Syntax: object.Max [ = value ]

Changing Max clips the current Value into the new range silently if it now falls outside.

Min

The lower end of the scroll bar's value range. Long, default 0. May be set higher than Max to invert the direction of travel.

Syntax: object.Min [ = value ]

Changing Min clips the current Value into the new range silently if it now falls outside.

MouseIcon

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

MousePointer

The mouse cursor shown when the pointer is over the control. A member of MousePointerConstants.

Name

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

Opacity

The control's opacity as a percentage (0--100, default 100). Values outside the range are clamped on Initialize. Requires Windows 8 or later for child controls.

Parent

A reference to the Form (or UserControl) that ultimately contains this scroll bar. Read-only.

RightToLeft

INFO

Reserved for compatibility with VB6; not currently implemented in twinBASIC. To run the scroll bar in reverse, swap Min and Max.

SmallChange

The amount Value is adjusted when the user clicks one of the end-arrows (or presses an arrow key while the scroll bar has focus). Long, default 1.

TabIndex

The position of the control in the form's TAB-key navigation order. Long.

TabStop

Whether the user can reach the control by pressing the TAB key. Boolean, default True. A disabled control is skipped regardless of this setting.

Tag

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

Top

The vertical distance from the top of the container to the top of the scroll bar. Double.

TransparencyKey

An OLE_COLOR that, when set, becomes fully transparent in the rendered control. Default -1 disables the effect. Requires Windows 8 or later for child controls.

Value

The scroll bar's current position within [Min, Max]. Long, default 0. Default property.

Syntax: object.Value [ = value ]

value

A Long in the closed interval [Min, Max] (or [Max, Min] for an inverted scroll bar). Values outside that interval raise run-time error 380 (Invalid property value).

Assigning a value that differs from the current one moves the thumb and raises a single Change event. Assigning the current value is a silent no-op.

Visible

Whether the scroll bar is shown. Boolean, default True.

VisualStyles

Whether the OS theme engine should be used when drawing the scroll bar. Boolean, default True.

WhatsThisHelpID

A Long identifying a "What's This?" help-pop-up topic in the application's help file. See ShowWhatsThis.

Width

The scroll bar's width in twips (or in the container's ScaleMode units). Double. For a vertical scroll bar this is the small dimension --- typically the OS standard scroll-bar thickness; values larger than that simply enlarge the surrounding hit area.

Methods

Drag

Begins, completes, or cancels a manual drag-and-drop operation. Typically called from code 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 scroll bar in a single call.

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.

Refresh

Forces an immediate repaint of the scroll bar.

Syntax: object.Refresh

SetFocus

Moves the input focus to the scroll bar. The control must be both Visible and Enabled, or run-time error 5 (Invalid procedure call or argument) is raised.

Syntax: object.SetFocus

ShowWhatsThis

Displays the topic identified by WhatsThisHelpID as a "What's This?" pop-up.

Syntax: object.ShowWhatsThis

SyncScrollBar

Re-applies the current Min, Max, LargeChange, and Value to the underlying Win32 scroll bar. Property assignments already do this implicitly --- call SyncScrollBar only when external code (typically a Win32 API call) has reached around the control and changed its native state.

Syntax: object.SyncScrollBar

ZOrder

Brings the control to the front or back of its sibling stack.

Syntax: object.ZOrder [ Position ]

Position

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

Events

Change

Raised after Value settles on a new value --- when the user releases the thumb after a drag, when the user clicks an arrow or the track, when the user presses Home, End, or an arrow key with focus on the scroll bar, or when code assigns a different Value. Not raised for the continuous updates that happen during a drag --- see Scroll for that. Default event.

Syntax: object_Change( )

DragDrop

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

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

DragOver

Raised on the control under the cursor while a manual drag operation is in progress.

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

GotFocus

Raised when the scroll bar receives the input focus.

Syntax: object_GotFocus( )

Initialize

Raised once, after the underlying window has been created and the scroll bar is connected to its Win32 range, but before the scroll bar is first painted. Useful for last-minute setup that needs the underlying handle.

Syntax: object_Initialize( )

KeyDown

Raised when the user presses any key while the control has focus. Note that the scroll bar already handles the arrow keys, Page Up / Page Down, and Home / End internally --- but KeyDown still fires for them in addition to the resulting Change.

Syntax: object_KeyDown( KeyCode As Integer, Shift As Integer )

KeyPress

Raised when the user types a character that produces an ANSI keystroke.

Syntax: object_KeyPress( KeyAscii As Integer )

KeyUp

Raised when the user releases a key while the control has focus.

Syntax: object_KeyUp( KeyCode As Integer, Shift As Integer )

LostFocus

Raised when the scroll bar loses the input focus.

Syntax: object_LostFocus( )

Scroll

Raised continuously while the user is dragging the thumb, once for each tick that produces a different Value. After the user releases the thumb, a single Change event fires with the final value. Scroll is the right event for a live preview while the thumb is moving; Change fires only the final value.

Syntax: object_Scroll( )

Validate

Raised when the focus is moving to another control whose CausesValidation is True. Setting Cancel to True keeps the focus on this control.

Syntax: object_Validate( Cancel As Boolean )