Scroll Bars

What it is for

Use a VerticalScrollBar or a HorizontalScrollBar wherever a form needs a scroll bar that matches its theme – beside a custom-drawn view, a long preview, a timeline – or let a host such as the suite's scrolling panel and scrollable picture box create and dock them for you. This class cannot be created directly; it holds everything the two orientations share.

The range model

The range runs from MinimumScrollRange (0) to MaximumScrollRange, in whatever units the application scrolls in – pixels of a picture, rows of a report. LargeChange is how much of that range is in view at once: it sets the thumb's length (the track length times LargeChange over the range, never less than 6 pixels) and one page step. Position is the first unit in view, so it runs from 0 to MaximumScrollRange minus LargeChange; values outside are clamped. SmallChange is one arrow click, arrow key or wheel notch.

Knowing when it scrolled

• PositionChanged – every change of Position, whatever caused it. The one to use for keeping a view in step.
• The orientation's own line, page and thumb events (LineUp, PageDown, ThumbLeft ...) – raised for mouse actions on the arrows, the track and the thumb.
• The orientation's Scroll event – the same mouse actions in the framework's ScrollEventArgs form, for code written against the standard scroll bar.

The keyboard (arrow keys, and Page Up / Page Down on the vertical bar) and the mouse wheel change Position directly, so they raise PositionChanged only.

Appearance

Colours, images and the auto-repeat rate live on ScrollBarRenderingConfigurator; pick a ColorTheme there and adjust individual colours after it. To draw a part entirely yourself, assign ScrollBarTrackRenderer, ScrollBarThumbRenderer, ScrollBarThumbGripperRenderer or ScrollBarNavigationButtonRenderer.

Thickness is in device pixels

Unlike the suite's other metrics, VerticalScrollBarWidth and HorizontalScrollBarHeight are device pixels. Left alone, they follow the system scroll bar size for the display the bar is on (17 at 96 DPI) and follow the window to a display at another scale; a value you assign is used as given, on every display.

A themed vertical bar scrolling a tall invoice page inside a fixed viewport.

using Binarymission.WinForms.Controls.ScrollBars;

var viewport = new Panel { Location = new Point(12, 12), Size = new Size(420, 300) };
var invoicePage = new Panel { Size = new Size(420, 1200), BackColor = Color.White };
viewport.Controls.Add(invoicePage);

var pageBar = new VerticalScrollBar
{
    Location = new Point(436, 12),
    Height = 300,
    MaximumScrollRange = 1200,   // the page's height, in pixels
    LargeChange = 300,           // the part of it the viewport shows
    SmallChange = 40,
};
pageBar.ScrollBarRenderingConfigurator.ColorTheme = ColorTheme.OfficeBlue;

// One handler covers arrows, track, thumb, keyboard and wheel.
pageBar.PositionChanged += (sender, e) => invoicePage.Top = -(int)e.NewPosition;

Controls.Add(viewport);
Controls.Add(pageBar);