ScrollBarBase

Initialises a stand-alone scroll bar with a range of 0 to 100, a small change of 10 and a large change of 20, sized from the system scroll bar metric.

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

Gets the position the bar held before its latest move.

Handy in a line, page or thumb event handler, which carries no positions of its own: Position - EarlierScrollPosition is how far the view has to move.

Gets or sets the thickness of a horizontal bar: its height, and the size of its square arrow buttons.

This is the one metric in the suite that is not in logical pixels. Until it is assigned, the bar reads the system metric for the display it is shown on, and reads it again when the window moves to a display at another scale. Once assigned, the value is used as given on every display, and the system metric is not consulted again.

The bar's own Control.Height is kept equal to this value. Assigning it raises HorizontalScrollBarHeightChanged.

On a VerticalScrollBar this property is hidden: it returns VerticalScrollBarWidth and ignores assignments.

Gets or sets whether the thumb was last drawn from one of the configurator's thumb images.

Gets or sets how much of the range is in view at once: one page step, and the thumb's share of the track.

A track click (or Page Up / Page Down on a vertical bar) moves Position by this much, the thumb is this fraction of the track long, and Position stops at MaximumScrollRange minus this value. For a viewport, set it to the viewport's size in range units.

A value below MinimumScrollRange or above MaximumScrollRange is stored as 1, so set MaximumScrollRange first.

Gets or sets the high end of the range: the total extent being scrolled, in the application's units.

For a viewport, set it to the content's full size and LargeChange to the visible part. Set it before LargeChange and SmallChange, which are checked against it.

A value below MinimumScrollRange is ignored.

Gets or sets the low end of the range.

The setter accepts a new value only while the current one is above zero, which the default is not, so in practice the range always starts at 0. Position is clamped at 0 in any case.

Gets or sets the gap left between a self-positioning bar and the edges of the control it serves.

Used only while ShouldAutomaticallyPositionScroller is true, and read when the bar is next laid out (when the served control is resized).

Gets or sets where the view is in the range: the first unit of the range in view.

A value below 0 is stored as 0, and a value at or beyond the top of the range as MaximumScrollRange minus LargeChange, so assigning MaximumScrollRange to it scrolls to the end.

A change raises PositionChanged and repaints the bar. Setting the position in code does not raise the line, page or Scroll events.

// Bring row 250 of the report to the top of the view, 18 pixels per row.
reportBar.Position = 250 * 18;

Gets or sets an object that draws the two arrow buttons, background and arrow, in place of the built-in look.

The renderer is handed each button's bounds, the way its arrow points and whether it is idle, hot or pressed. The bar's outer border is still drawn by the bar.

sealed class FlatArrowRenderer : IScrollBarNavigationButtonRenderer
{
    public void Draw(Graphics g, Rectangle bounds, ArrowDrawingArtefact arrow, ControlVisualState state)
    {
        var fill = state == ControlVisualState.Pressed ? Color.SteelBlue
                 : state == ControlVisualState.Hot ? Color.LightSteelBlue
                 : Color.Gainsboro;
        using (var brush = new SolidBrush(fill))
        {
            g.FillRectangle(brush, bounds);
        }
    }
}

statementBar.ScrollBarNavigationButtonRenderer = new FlatArrowRenderer();

Gets or sets the colours, images, theme and auto-repeat rate the bar is drawn and driven with.

Expandable in the property grid and serialised with the form. The bar reads it every time it paints, so a change shows at the next repaint; call Control.Invalidate to see it at once.

Two bars that should look alike need the same settings on both configurators, or the same configurator instance assigned to both.

var look = timelineBar.ScrollBarRenderingConfigurator;
look.ColorTheme = ColorTheme.OfficeSilver;        // first: a theme overwrites the colours below
look.GripperColor1 = Color.DimGray;               // the grip ridges
look.GripperColor2 = Color.WhiteSmoke;
look.AutoScrollInterval = 60;                     // faster repeat while an arrow is held
timelineBar.Invalidate();

Gets or sets an object that draws the grip marks on the thumb in place of the built-in ridges.

Called only when ScrollBarRenderingConfigurator.ShouldDrawGripperArtefact is true, the thumb is not drawn from an image, and the thumb is at least 12 logical pixels long. It is handed the thumb's bounds and its visual state.

Gets or sets an object that draws the thumb in place of the built-in fill, image and border.

The renderer is handed the thumb's bounds and whether it is idle, hot or pressed. The gripper is drawn over it afterwards unless ScrollBarRenderingConfigurator.ShouldDrawGripperArtefact is false.

Gets or sets an object that draws the track – the background behind the arrows and the thumb – in place of the built-in fill.

The renderer is handed the bar's whole client area; the arrows and the thumb are drawn over it.

Gets or sets the control the bar serves: the one it sizes itself against and, when its window is created, is placed inside.

The bar listens to this control's Control.SizeChanged to keep its own size in step, and reads the display scale from it for the system thickness.

Gets or sets whether the bar docks itself to the edge of the control it serves and sizes itself to it.

While on, the bar follows the size of ScrollServiceTargetControl: it is inset by PaddingGap, and when a vertical and a horizontal bar serve the same control each leaves room for the other. The suite's scrolling panel and scrollable picture box turn this on for the bars they host.

While off, the bar keeps its location and length and only its thickness is set, from VerticalScrollBarWidth or HorizontalScrollBarHeight.

Gets or sets how far one arrow click, arrow key or wheel notch moves Position.

A value below MinimumScrollRange or above MaximumScrollRange is stored as 1, so set MaximumScrollRange first.

Gets or sets the thickness of a vertical bar: its width, and the size of its square arrow buttons.

This is the one metric in the suite that is not in logical pixels. Until it is assigned, the bar reads the system metric for the display it is shown on, and reads it again when the window moves to a display at another scale. Once assigned, the value is used as given on every display, and the system metric is not consulted again – so a width persisted by the designer stays that many device pixels at any scale.

The bar's own Control.Width is kept equal to this value. Assigning it raises VerticalScrollBarWidthChanged.

On a HorizontalScrollBar this property is hidden: it returns HorizontalScrollBarHeight and ignores assignments.

Releases the bar: it stops listening to the control it serves and to its host, and disposes the corner square it placed in the host.

Draws one arrow button: through ScrollBarNavigationButtonRenderer when one is set, otherwise with the configurator's button colours and its arrow image or drawn arrow for the state.

Draws the thumb at GetThumbArtefactRectangle: through ScrollBarThumbRenderer when one is set, otherwise from the configurator's thumb image for the state, its thumb gradient, or its solid thumb colour.

Returns the thumb's bounds, in client coordinates. The base returns Rectangle.Empty; each orientation overrides it.

The thumb's bounds.

The same rectangle is used for drawing and for hit testing, so an override moves both.

Claims the arrow keys and Page Up / Page Down, so they reach the bar rather than moving the focus.

true for Up, Down, Left, Right, Page Up and Page Down; otherwise the base answer.

Raises DpiChangedAfterParent and, unless the thickness was set in code, re-reads the system scroll bar size for the new display and lays the bar out again.

Raises Control.HandleCreated, places the bar's window inside ScrollServiceTargetControl, reads the system thickness for that display and lays the bar out.

Raises Control.KeyDown, then moves the position: Up and Down (vertical bar) and Left and Right (horizontal bar) by SmallChange, Page Up and Page Down (vertical bar) by LargeChange.

The move raises PositionChanged, not the line, page or Scroll events.

Raises Control.KeyUp. The bar does nothing more on a key release.

Raises Control.MouseWheel, then moves the position by SmallChange for the notch: on a vertical bar always, on a horizontal bar only while Shift is held.

The notch is marked handled, so a form or panel that also scrolls on the wheel does not move as well. The move raises PositionChanged, not the line or Scroll events.

Raises Control.Paint and then draws the bar through PaintScrollBar.

Raises Control.ParentChanged and attaches the bar to its new parent. A stand-alone bar takes the parent as its ScrollServiceTargetControl; a bar created by a host stays with the host.

Raises Control.TabStopChanged and makes the bar focusable, or not, to match Control.TabStop.

Draws the track over the whole client area: through ScrollBarTrackRenderer when one is set, otherwise as the configurator's track gradient, or TrackFillColor when either gradient colour is Color.Empty.

Draws the whole bar. The base does nothing; each orientation overrides it and calls the drawing helpers in its own order.

Override in a derived bar to draw over the finished bar – the marker scroll bars draw their marks this way, after calling the base.

Lays the bar out again against ScrollServiceTargetControl. The base does nothing; each orientation overrides it.

Called when the served control is resized, when the thickness changes and when the window is created.

Raises PositionChanged.

Processes the bar's window messages, ending any auto-repeat when the left button comes up. Messages for a window that no longer exists are dropped.

Occurs when HorizontalScrollBarHeight is set in code.

Raised on every assignment, before the new height is applied – read the value you assigned, not the property, in the handler. Not raised when the height follows the system metric.

Occurs when Position changes, whatever moved it: the arrows, the track, the thumb, the keyboard, the wheel or code.

Raised once per actual change, after the new position is stored; setting the current value again raises nothing. While the thumb is dragged it is raised for every step, so keep the handler quick.

It runs inside the bar's mouse handling – while an arrow is held, inside its auto-repeat loop – so do not show a dialog box from it.

timelineBar.PositionChanged += (sender, e) =>
{
    timelineView.FirstVisibleDay = startDate.AddDays(e.NewPosition);
    timelineView.Invalidate();
};

Occurs when VerticalScrollBarWidth is set in code.

Raised on every assignment, before the new width is applied – read the value you assigned, not the property, in the handler. Not raised when the width follows the system metric.

The backing field of EarlierScrollPosition: the position before the latest move.

Set while the thumb's geometry pulls Position back inside the range, so that the correction is reported through the line events.

The extent, in device pixels, of the grip ridges drawn across a horizontal thumb: the bar's height less a small margin. For derived scroll bars that draw their own gripper.

The extent, in device pixels, of the grip ridges drawn across a vertical thumb: the bar's width less a small margin. For derived scroll bars that draw their own gripper.

The backing field of LargeChange.

The backing field of MaximumScrollRange.

The backing field of MinimumScrollRange.

The host control passed to the constructor through IScrollersDockHost.DockHost, or null for a stand-alone bar.

Set when a vertical and a horizontal bar serve the same control, so that each leaves room for the other and for the corner square between them.

The backing field of Position. A double, so that a long range still moves smoothly over a short track.

The control the bar sizes and docks itself against – the backing field of ScrollServiceTargetControl.

Set to end the auto-repeat loop that runs while an arrow or the track is held down; the bar sets it when the left button comes up.

The backing field of SmallChange.

Not used by the library. Kept because it is part of the protected surface.