HypernovaDesktop Components · docs
Binarymission
WinForms › Scroll Bars › HorizontalScrollBar

HorizontalScrollBar

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

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

public class HorizontalScrollBar : ScrollBarBase

Inherits from / implements: ScrollBarBase

Remarks

Using it

Place it under the view it scrolls, set ScrollBarBase.MaximumScrollRange to the content's width and ScrollBarBase.LargeChange to the visible width (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 either side of 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; Shift with the wheel, and Left / Right, also scroll while the bar has the focus.
  • Right-click opens Scroll Here, Left Edge, Right Edge, Page Left, Page Right, Scroll Left and Scroll Right (see IsDefaultScrollContextMenuEnabled).

Events

Mouse actions raise LineLeft / LineRight, PageLeft / PageRight, ThumbLeft / ThumbRight and Scroll. Every change of position, from any source, raises ScrollBarBase.PositionChanged.

Examples

using Binarymission.WinForms.Controls.ScrollBars;

// A floor plan wider than its 600 pixel viewport, panned by a themed bar.
var viewport = new Panel { Location = new Point(12, 12), Size = new Size(600, 260) };
var floorPlan = new PictureBox
{
    Image = Image.FromFile("warehouse-floor.png"),
    SizeMode = PictureBoxSizeMode.AutoSize,
};
viewport.Controls.Add(floorPlan);

var panBar = new HorizontalScrollBar
{
    Location = new Point(12, viewport.Bottom),
    Width = viewport.Width,
    MaximumScrollRange = floorPlan.Width,
    LargeChange = viewport.Width,
    SmallChange = 24,
};
panBar.ScrollBarRenderingConfigurator.ColorTheme = ColorTheme.OfficeSilver;
panBar.PositionChanged += (sender, e) => floorPlan.Left = -(int)e.NewPosition;

Controls.Add(viewport);
Controls.Add(panBar);

See also

Members at a glance

Constructors
HorizontalScrollBarInitialises a stand-alone horizontal bar with its right-click menu enabled. Add it to a form or panel and set its range.
HorizontalScrollBarInitialises a horizontal bar owned by a host control, which it serves and docks into.
Properties
DefaultSizeGets the size a new bar starts at: 184 by 17 pixels. The height is then set from ScrollBarBase.HorizontalScrollBarHeight.
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.
VerticalScrollBarWidthNot used by this orientation: returns ScrollBarBase.HorizontalScrollBarHeight and ignores assignments. Hidden from the designer and from IntelliSense.
Methods
GetNavigatorControlRectReturns the bounds of one of the two arrow buttons: a square as thick as the bar, at the left or right end.
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.
HitTestReturns the part of the bar at a point: an arrow, the track either side of the thumb, or the thumb.
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.
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 along the bottom of the served control's client area, inset by ScrollBarBase.PaddingGap and stopping short of a vertical bar that shares the control; otherwise only its height is set, to ScrollBarBase.HorizontalScrollBarHeight.
Events
HorizontalScrollPositionChangedOccurs after a command on the bar's right-click menu has moved the position: Scroll Here, Left Edge, Right Edge, Scroll Left or Scroll Right.
LineLeftOccurs when the left arrow moves the position left by ScrollBarBase.SmallChange: on the click, and on each repeat while it is held.
LineRightOccurs when the right arrow moves the position right by ScrollBarBase.SmallChange: on the click, and on each repeat while it is held.
PageLeftOccurs when a click on the track left of the thumb, or the Page Left menu command, moves the position left by ScrollBarBase.LargeChange; repeated while the track is held.
PageRightOccurs when a click on the track right of the thumb, or the Page Right menu command, moves the position right 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.
ThumbLeftOccurs when a drag moves the thumb left, for every step of the drag, the last one at release included.
ThumbRightOccurs when a drag moves the thumb right, for every step of the drag, the last one at release included.

Constructors

HorizontalScrollBar

public HorizontalScrollBar()

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

HorizontalScrollBar

public HorizontalScrollBar(IScrollersDockHost parent) : base(parent)

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

Parameters
parent
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: 184 by 17 pixels. The height is then set from ScrollBarBase.HorizontalScrollBarHeight.

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, Left Edge, Right Edge, Page Left, Page Right, Scroll Left, Scroll Right) 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 HorizontalScrollPositionChanged; 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.

VerticalScrollBarWidth

public override int VerticalScrollBarWidth

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

Methods

GetNavigatorControlRect

protected internal Rectangle GetNavigatorControlRect(bool isNavigatingLeft)

Returns the bounds of one of the two arrow buttons: a square as thick as the bar, at the left or right end.

Parameters
isNavigatingLeft
true for the left button, false for the right 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.

HitTest

public ScrollBarInteractionTarget HitTest(Point point)

Returns the part of the bar at a point: an arrow, the track either side of the thumb, or the thumb.

Parameters
point
The point, in the bar's client coordinates.
Returns

ScrollBarInteractionTarget.LeftArrow, ScrollBarInteractionTarget.RightArrow, ScrollBarInteractionTarget.PageLeft, ScrollBarInteractionTarget.PageRight or ScrollBarInteractionTarget.Thumb; ScrollBarInteractionTarget.None for any other point.

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.

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 along the bottom of the served control's client area, inset by ScrollBarBase.PaddingGap and stopping short of a vertical bar that shares the control; otherwise only its height is set, to ScrollBarBase.HorizontalScrollBarHeight.

Events

HorizontalScrollPositionChanged

public event EventHandler<PositionChangedArgs> HorizontalScrollPositionChanged

Occurs after a command on the bar's right-click menu has moved the position: Scroll Here, Left Edge, Right Edge, Scroll Left or Scroll Right.

Remarks

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

LineLeft

public event EventHandler LineLeft

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

Remarks

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

LineRight

public event EventHandler LineRight

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

Remarks

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

PageLeft

public event EventHandler PageLeft

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

PageRight

public event EventHandler PageRight

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

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.

ThumbLeft

public event EventHandler<ThumbEventArgs> ThumbLeft

Occurs when a drag moves the thumb left, 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.

ThumbRight

public event EventHandler<ThumbEventArgs> ThumbRight

Occurs when a drag moves the thumb right, 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.