HypernovaDesktop Components · docs
Binarymission
WinForms › Scroll Bars › VerticalScrollBar

VerticalScrollBar

class.NET 6 / 8 / 10.NET Framework 4.8Binarymission.WinForms.Controls.ScrollBars

A themeable vertical scroll bar: arrow buttons at the top and bottom, a thumb sized to the share of the range in view, and a right-click menu of scroll commands.

public class VerticalScrollBar : ScrollBarBase

Inherits from / implements: ScrollBarBase

Remarks

Using it

Place it beside the view it scrolls, set ScrollBarBase.MaximumScrollRange to the content's height and ScrollBarBase.LargeChange to the visible height (in the same units), and move the view in ScrollBarBase.PositionChanged. The range model, the thickness and the appearance are described on ScrollBarBase.

Mouse and keyboard

  • An arrow moves by ScrollBarBase.SmallChange and a click on the track above or below the thumb by ScrollBarBase.LargeChange; holding either repeats every AutoScrollInterval milliseconds until the button comes up or Esc is pressed.
  • The thumb can be dragged; the wheel, Up / Down and Page Up / Page Down also scroll while the bar has the focus.
  • Right-click opens Scroll Here, Top, Bottom, Page Up, Page Down, Scroll Up and Scroll Down (see IsDefaultScrollContextMenuEnabled).

Events

Mouse actions raise LineUp / LineDown, PageUp / PageDown, ThumbUp / ThumbDown and Scroll. Every change of position, from any source, raises ScrollBarBase.PositionChanged.

Examples

using Binarymission.WinForms.Controls.ScrollBars;

// A themed bar driving an order grid, one row per step.
ordersGrid.ScrollBars = System.Windows.Forms.ScrollBars.None;

var rowsBar = new VerticalScrollBar
{
    Location = new Point(ordersGrid.Right, ordersGrid.Top),
    Height = ordersGrid.Height,
    MaximumScrollRange = ordersGrid.RowCount,
    LargeChange = ordersGrid.DisplayedRowCount(false),
    SmallChange = 1,
};
rowsBar.ScrollBarRenderingConfigurator.ColorTheme = ColorTheme.Win8;
rowsBar.PositionChanged += (sender, e) =>
    ordersGrid.FirstDisplayedScrollingRowIndex = (int)e.NewPosition;
rowsBar.Scroll += (sender, e) =>
{
    if (e.Type == ScrollEventType.EndScroll)
        statusLabel.Text = "Showing from order " + (e.NewValue + 1);
};
Controls.Add(rowsBar);

See also

Members at a glance

Constructors
VerticalScrollBarInitialises a stand-alone vertical bar with its right-click menu enabled. Add it to a form or panel and set its range.
VerticalScrollBarInitialises a vertical bar owned by a host control, which it serves and docks into.
Properties
DefaultSizeGets the size a new bar starts at: 17 by 184 pixels. The width is then set from ScrollBarBase.VerticalScrollBarWidth.
HorizontalScrollBarHeightNot used by this orientation: returns ScrollBarBase.VerticalScrollBarWidth and ignores assignments. Hidden from the designer and from IntelliSense.
IsDefaultScrollContextMenuEnabledGets or sets whether right-clicking the bar opens its built-in menu of scroll commands.
ShouldUseExtendedMenuControlForContextMenuGets or sets whether the built-in right-click menu is built from the suite's extended menu items.
Methods
GetNavigatorControlRectReturns the bounds of one of the two arrow buttons: a square as thick as the bar, at the top or bottom.
GetThumbArtefactRectangleReturns the thumb's bounds: its length is the track's length times ScrollBarBase.LargeChange over the range, at least 6 pixels, and its offset maps ScrollBarBase.Position onto the track.
OnMouseDownRaises Control.MouseDown and, for the left button, acts on the part under the pointer: an arrow steps by ScrollBarBase.SmallChange, the track by ScrollBarBase.LargeChange (both repeating while held), and the thumb starts a drag.
OnMouseEnterRaises Control.MouseEnter and highlights the arrow or thumb under the pointer.
OnMouseLeaveRaises Control.MouseLeave and returns the arrows and the thumb to their idle look.
OnMouseMoveHighlights the arrow or thumb under the pointer and, during a drag, moves the thumb with it.
OnMouseUpRaises Control.MouseUp and, for the left button, ends a thumb drag: the final thumb event, then Scroll with ThumbPosition and EndScroll.
OnResizeRaises Control.Resize and repaints the bar at its new size.
OnSizeChangedRaises Control.SizeChanged and returns the arrow buttons to their idle look.
PaintScrollBarDraws the bar: the track, the two arrow buttons, the thumb, the gripper and the outer border. A disabled bar shows only its track and border.
PerformSizeRefreshLays the bar out. Self-positioning, it runs down the right edge of the served control's client area, inset by ScrollBarBase.PaddingGap and stopping short of a horizontal bar that shares the control; otherwise only its width is set, to ScrollBarBase.VerticalScrollBarWidth.
Events
LineDownOccurs when the down arrow moves the position down by ScrollBarBase.SmallChange: on the click, and on each repeat while it is held.
LineUpOccurs when the up arrow moves the position up by ScrollBarBase.SmallChange: on the click, and on each repeat while it is held.
PageDownOccurs when a click on the track below the thumb, or the Page Down menu command, moves the position down by ScrollBarBase.LargeChange; repeated while the track is held.
PageUpOccurs when a click on the track above the thumb, or the Page Up menu command, moves the position up by ScrollBarBase.LargeChange; repeated while the track is held.
ScrollOccurs as the user scrolls with the mouse, in the form of the framework's Scroll event.
ThumbDownOccurs when a drag moves the thumb down, for every step of the drag, the last one at release included.
ThumbUpOccurs when a drag moves the thumb up, for every step of the drag, the last one at release included.
VerticalScrollPositionChangedOccurs after a command on the bar's right-click menu has moved the position: Scroll Here, Top, Bottom, Scroll Up or Scroll Down.

Constructors

VerticalScrollBar

public VerticalScrollBar()

Initialises a stand-alone vertical bar with its right-click menu enabled. Add it to a form or panel and set its range.

VerticalScrollBar

public VerticalScrollBar(IScrollersDockHost parentInstanceUsingThisScrollerInstance) : base(parentInstanceUsingThisScrollerInstance)

Initialises a vertical bar owned by a host control, which it serves and docks into.

Parameters
parentInstanceUsingThisScrollerInstance
The host, usually the suite's scrolling panel or scrollable picture box. Must not be null.
Remarks

A bar created this way has no right-click menu until IsDefaultScrollContextMenuEnabled is set.

Properties

DefaultSize

protected override Size DefaultSize

Gets the size a new bar starts at: 17 by 184 pixels. The width is then set from ScrollBarBase.VerticalScrollBarWidth.

HorizontalScrollBarHeight

public override int HorizontalScrollBarHeight

Not used by this orientation: returns ScrollBarBase.VerticalScrollBarWidth and ignores assignments. Hidden from the designer and from IntelliSense.

IsDefaultScrollContextMenuEnabled

public bool IsDefaultScrollContextMenuEnabled

Gets or sets whether right-clicking the bar opens its built-in menu of scroll commands.

Value
true for a bar created with the parameterless constructor; false for one created by a host, unless the host turns it on.
Remarks

Setting true builds the menu (Scroll Here, Top, Bottom, Page Up, Page Down, Scroll Up, Scroll Down) and assigns it to the bar. Setting false does not take an assigned menu away: to remove it, also set the bar's context menu property to null.

The menu's commands move the position and raise VerticalScrollPositionChanged; Scroll Here scrolls to roughly the point that was right-clicked.

ShouldUseExtendedMenuControlForContextMenu

public bool ShouldUseExtendedMenuControlForContextMenu

Gets or sets whether the built-in right-click menu is built from the suite's extended menu items.

Value
The default is false.
Remarks

On .NET Framework 4.8 the extended setting draws the menu with the suite's owner-drawn menu items; on .NET 6 and later both settings build the same standard menu. Setting the property rebuilds the menu and assigns it to the bar, even while IsDefaultScrollContextMenuEnabled is false.

Methods

GetNavigatorControlRect

protected internal Rectangle GetNavigatorControlRect(bool isNavigatingUpwards)

Returns the bounds of one of the two arrow buttons: a square as thick as the bar, at the top or bottom.

Parameters
isNavigatingUpwards
true for the up button, false for the down one.
Returns

The button's bounds, in client coordinates.

GetThumbArtefactRectangle

protected override Rectangle GetThumbArtefactRectangle()

Returns the thumb's bounds: its length is the track's length times ScrollBarBase.LargeChange over the range, at least 6 pixels, and its offset maps ScrollBarBase.Position onto the track.

Returns

The thumb's bounds, in client coordinates.

OnMouseDown

protected override void OnMouseDown(MouseEventArgs e)

Raises Control.MouseDown and, for the left button, acts on the part under the pointer: an arrow steps by ScrollBarBase.SmallChange, the track by ScrollBarBase.LargeChange (both repeating while held), and the thumb starts a drag.

Parameters
e
The mouse data.
Remarks

While an arrow or the track is held, the call does not return until the button comes up: it runs its own message loop to repeat the step.

OnMouseEnter

protected override void OnMouseEnter(EventArgs e)

Raises Control.MouseEnter and highlights the arrow or thumb under the pointer.

Parameters
e
The event data.

OnMouseLeave

protected override void OnMouseLeave(EventArgs e)

Raises Control.MouseLeave and returns the arrows and the thumb to their idle look.

Parameters
e
The event data.

OnMouseMove

protected override void OnMouseMove(MouseEventArgs e)

Highlights the arrow or thumb under the pointer and, during a drag, moves the thumb with it.

Parameters
e
The mouse data.

OnMouseUp

protected override void OnMouseUp(MouseEventArgs e)

Raises Control.MouseUp and, for the left button, ends a thumb drag: the final thumb event, then Scroll with ThumbPosition and EndScroll.

Parameters
e
The mouse data.

OnResize

protected override void OnResize(EventArgs e)

Raises Control.Resize and repaints the bar at its new size.

Parameters
e
The event data.

OnSizeChanged

protected override void OnSizeChanged(EventArgs e)

Raises Control.SizeChanged and returns the arrow buttons to their idle look.

Parameters
e
The event data.

PaintScrollBar

protected override void PaintScrollBar(Graphics g)

Draws the bar: the track, the two arrow buttons, the thumb, the gripper and the outer border. A disabled bar shows only its track and border.

Parameters
g
The surface to draw on.

PerformSizeRefresh

protected override void PerformSizeRefresh()

Lays the bar out. Self-positioning, it runs down the right edge of the served control's client area, inset by ScrollBarBase.PaddingGap and stopping short of a horizontal bar that shares the control; otherwise only its width is set, to ScrollBarBase.VerticalScrollBarWidth.

Events

LineDown

public event EventHandler LineDown

Occurs when the down arrow moves the position down by ScrollBarBase.SmallChange: on the click, and on each repeat while it is held.

Remarks

Not raised when the position was already at the bottom, nor by the keyboard or the wheel.

LineUp

public event EventHandler LineUp

Occurs when the up arrow moves the position up by ScrollBarBase.SmallChange: on the click, and on each repeat while it is held.

Remarks

Not raised when the position was already at the top, nor by the keyboard or the wheel.

PageDown

public event EventHandler PageDown

Occurs when a click on the track below the thumb, or the Page Down menu command, moves the position down by ScrollBarBase.LargeChange; repeated while the track is held.

Remarks

Not raised when the position was already at the bottom, nor by the Page Down key.

PageUp

public event EventHandler PageUp

Occurs when a click on the track above the thumb, or the Page Up menu command, moves the position up by ScrollBarBase.LargeChange; repeated while the track is held.

Remarks

Not raised when the position was already at the top, nor by the Page Up key.

Scroll

public event ScrollEventHandler Scroll

Occurs as the user scrolls with the mouse, in the form of the framework's Scroll event.

Remarks

Type is SmallDecrement / SmallIncrement for the arrows, LargeDecrement / LargeIncrement for the track, ThumbTrack while the thumb is dragged, ThumbPosition then EndScroll when it is released, and EndScroll when a held arrow or track is released. First follows a move that reaches the start of the range. OldValue and NewValue are the positions, truncated to whole units.

Last follows a move that reaches the end of the range (ScrollBarBase.MaximumScrollRange minus ScrollBarBase.LargeChange, where the position stops).

The keyboard, the wheel and setting ScrollBarBase.Position in code do not raise it.

ThumbDown

public event EventHandler<ThumbEventArgs> ThumbDown

Occurs when a drag moves the thumb down, for every step of the drag, the last one at release included.

Remarks

ThumbEventArgs.ChangeDelta is the distance moved since the previous step, in whole range units.

ThumbUp

public event EventHandler<ThumbEventArgs> ThumbUp

Occurs when a drag moves the thumb up, for every step of the drag, the last one at release included.

Remarks

ThumbEventArgs.ChangeDelta is the distance moved since the previous step, in whole range units.

VerticalScrollPositionChanged

public event EventHandler<PositionChangedArgs> VerticalScrollPositionChanged

Occurs after a command on the bar's right-click menu has moved the position: Scroll Here, Top, Bottom, Scroll Up or Scroll Down.

Remarks

Raised by those menu commands only – the Page commands raise PageUp / PageDown instead. To follow every change of position, use ScrollBarBase.PositionChanged.