HypernovaDesktop Components · docs
Binarymission
WinForms › Scrollable Panel › ScrollerPanel

ScrollerPanel

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

A container that scrolls content larger than itself with the suite's themeable scroll bars, inside an optional border and drop shadow.

public class ScrollerPanel : Control, IScrollersDockHost, IScrollerPanel

Inherits from / implements: Control, IScrollersDockHost, IScrollerPanel

Remarks

What it is for

Use it where a form needs a scrolling region – a long order form, a dashboard of cards, a wide diagram – and the scroll bars should match the application's theme rather than the system's.

How it works

Build the content on an ordinary Panel at its full size and assign it to ContentHostingPanel. The scroller panel shows its VerticalScrollBar when the content is taller than the visible area and its HorizontalScrollBar when it is wider, and scrolls by moving the content panel. The controls on the content panel need know nothing about the scrolling.

The bars' ranges are the content's size in pixels: one arrow click, arrow key or wheel notch moves by ScrollSize, a page by the visible size. Whenever the content or the scroller panel is resized the bars are recalculated and their thumbs return to the start; the content keeps the offset it had.

Keyboard and mouse

With the focus, Up / Down / Left / Right scroll by ScrollSize and Page Up / Page Down by a page; the wheel scrolls vertically, and horizontally with Shift. The bars also offer their right-click menus.

Appearance

The frame – BorderStyle, BorderSize, BorderColor and the optional drop shadow – is drawn outside the client area. Theme the bars through VerticalScrollBar and HorizontalScrollBar; their thickness is in device pixels and follows the system scroll bar size (see ScrollBarBase).

Examples

using Binarymission.WinForms.Controls.Containers;
using Binarymission.WinForms.Controls.ScrollBars;

// An order form far larger than the space it is shown in.
var orderForm = new Panel { Size = new Size(820, 1400), BackColor = Color.White };
orderForm.Controls.Add(new Label { Text = "Sales order SO-10482", Location = new Point(16, 16), AutoSize = true });
orderForm.Controls.Add(new DataGridView { Location = new Point(16, 48), Size = new Size(780, 600) });

var orderViewer = new ScrollerPanel
{
    Location = new Point(12, 12),
    Size = new Size(480, 360),
    BorderColor = Color.SteelBlue,
    ShouldDrawDropShadow = true,
    ScrollSize = new Size(16, 24),
    ContentHostingPanel = orderForm,
};

foreach (ScrollBarBase bar in new ScrollBarBase[] { orderViewer.VerticalScrollBar, orderViewer.HorizontalScrollBar })
{
    bar.ScrollBarRenderingConfigurator.ColorTheme = ColorTheme.OfficeBlue;
}

Controls.Add(orderViewer);

See also

Members at a glance

Constructors
ScrollerPanelInitialises an empty scroller panel with a one-pixel solid black border, no drop shadow and a scroll step of 8 pixels.
Properties
BorderColorGets or sets the colour of the border around the panel.
BorderSizeGets or sets the width of the border around the panel.
BorderStyleGets or sets the line style of the border around the panel.
ContentHostingPanelGets or sets the panel that holds the content to scroll.
DefaultSizeGets the size a new panel starts at: 150 by 150 pixels.
DockHostGets the control the scroll bars dock into: the panel itself.
DropShadowColorGets or sets the colour of the drop shadow.
DropShadowDepthGets or sets how far the drop shadow reaches beyond the border.
DropShadowOpacityGets or sets how dark the drop shadow is at its strongest, next to the border.
HorizontalScrollBarGets the panel's horizontal scroll bar, to theme it or follow its events.
ScrollBarsOpaqueCornerColorGets or sets the colour of the square that fills the corner where the two scroll bars meet.
ScrollControlsCompositeSizeMetadataGets the size of the corner square last reported to the scroll bars: the vertical bar's width by the horizontal bar's height.
ScrollSizeGets or sets how far one arrow click, arrow key or wheel notch scrolls the content.
ShouldDrawDropShadowGets or sets whether a soft drop shadow is drawn along the panel's bottom and right edges.
ShouldNotPerformDockHostHorizontalSizePaintingGets whether the horizontal bar should stop short of the vertical bar – true while both are showing.
ShouldNotPerformDockHostVerticalSizePaintingGets whether the vertical bar should stop short of the horizontal bar – true while both are showing.
ShouldProvideExtendedRenderingArtefactsGets whether the panel asks its scroll bars to fill the corner square between them.
VerticalScrollBarGets the panel's vertical scroll bar, to theme it or follow its events.
Methods
IsInputKeyClaims the arrow keys and Page Up / Page Down, so they scroll the panel rather than move the focus.
OnHandleCreatedRaises Control.HandleCreated and adds the two scroll bars to the panel.
OnKeyDownRaises Control.KeyDown, then scrolls the content: Up, Down, Left and Right by one ScrollSize step, Page Up and Page Down by a page (the visible height).
OnKeyUpRaises Control.KeyUp. The panel does nothing more on a key release.
OnMouseWheelRaises Control.MouseWheel, then scrolls the content by one ScrollSize step: vertically, or horizontally while Shift is held.
OnPaintFills the client area in the system control colour and raises Control.Paint.
OnParentBackColorChangedRaises Control.ParentBackColorChanged and repaints the shadow band, which is filled with the colour behind the panel.
OnParentChangedRaises Control.ParentChanged and starts following the new parent's size, to keep the corner square between the two bars in place.
OnSizeChangedRaises Control.SizeChanged, recalculates the scroll bars for the new size (their thumbs return to the start) and repaints the frame.
OnTabStopChangedRaises Control.TabStopChanged and makes the panel focusable, or not, to match Control.TabStop.
OnVisibleChangedRaises Control.VisibleChanged and, when the panel is shown, recalculates the scroll bars.
WndProcProcesses the panel's window messages: it reserves room for the border and the drop shadow outside the client area, and draws them there.
Events
ScrollerPanelUpdatedOccurs when both scroll bars are showing and the size of the corner square between them needs updating.

Constructors

ScrollerPanel

public ScrollerPanel()

Initialises an empty scroller panel with a one-pixel solid black border, no drop shadow and a scroll step of 8 pixels.

Properties

BorderColor

public Color BorderColor

Gets or sets the colour of the border around the panel.

Value
The default is Color.Black.

BorderSize

public int BorderSize

Gets or sets the width of the border around the panel.

Value
In pixels, not scaled with the display. The default is 1; 0 removes the border.
Remarks

The border is drawn outside the client area, so a wider border makes the area for the content and the bars smaller.

BorderStyle

public ButtonBorderStyle BorderStyle

Gets or sets the line style of the border around the panel.

Value
The default is Solid. None draws no line but still reserves BorderSize.
See also

ContentHostingPanel

public Panel ContentHostingPanel

Gets or sets the panel that holds the content to scroll.

Value
The content panel, or null (the default) for none.
Remarks

Assigning a panel moves it into the scroller panel at its top-left corner (inset by Control.Padding), taking it from the scroller panel's parent if it was there, turns its own ScrollableControl.AutoScroll off and its Control.AutoSize on, and shows the scroll bars it needs. Give it its full size before or after assigning it; it grows with what is added to it.

Assigning also sets the scroller panel's Control.BackColor to white, which a content panel without a colour of its own inherits.

Assigning null removes the panel and hands it back to the scroller panel's parent, if there is one.

Example
var dashboard = new Panel { Size = new Size(1600, 900), BackColor = Color.WhiteSmoke };
foreach (var card in salesCards)   // your own card controls
{
    dashboard.Controls.Add(card);
}
dashboardViewer.ContentHostingPanel = dashboard;

DefaultSize

protected override Size DefaultSize

Gets the size a new panel starts at: 150 by 150 pixels.

DockHost

public Control DockHost

Gets the control the scroll bars dock into: the panel itself.

DropShadowColor

public Color DropShadowColor

Gets or sets the colour of the drop shadow.

Value
The default is Color.Black. The colour's alpha is ignored; DropShadowOpacity sets the strength.
Designer category
Appearance

DropShadowDepth

public int DropShadowDepth

Gets or sets how far the drop shadow reaches beyond the border.

Value
In logical pixels (scaled with the display), from 0 to 16; values outside are clamped. The default is 4.
Default
DropShadowPainter.DefaultDepth
Designer category
Appearance

DropShadowOpacity

public int DropShadowOpacity

Gets or sets how dark the drop shadow is at its strongest, next to the border.

Value
From 0 (invisible) to 255 (solid DropShadowColor); values outside are clamped. The default is 96.
Default
DropShadowPainter.DefaultOpacity
Designer category
Appearance

HorizontalScrollBar

public HorizontalScrollBar HorizontalScrollBar

Gets the panel's horizontal scroll bar, to theme it or follow its events.

Value
The bar the panel created; never null. Its settings are saved with the form.
Remarks

The panel shows and hides the bar and sets its range, steps and position itself, whenever the content or the panel is resized; set its appearance, not its range.

ScrollBarsOpaqueCornerColor

public Color ScrollBarsOpaqueCornerColor

Gets or sets the colour of the square that fills the corner where the two scroll bars meet.

Value
The default is SystemColors.Control.
Remarks

Read when the square is placed – when both bars appear or the panel's layout changes – so a new colour shows from the next such change.

ScrollControlsCompositeSizeMetadata

public Size ScrollControlsCompositeSizeMetadata

Gets the size of the corner square last reported to the scroll bars: the vertical bar's width by the horizontal bar's height.

Value
In device pixels. Size.Empty until both bars have shown together.

ScrollSize

public Size ScrollSize

Gets or sets how far one arrow click, arrow key or wheel notch scrolls the content.

Value
Width for horizontal steps and height for vertical ones, in pixels of the content. The default is 8 by 8.
Remarks

Becomes the bars' SmallChange. Changing either dimension recalculates the bars, which returns the content to the top-left corner.

ShouldDrawDropShadow

public bool ShouldDrawDropShadow

Gets or sets whether a soft drop shadow is drawn along the panel's bottom and right edges.

Value
The default is false.
Default
false
Designer category
Appearance
Remarks

A child control cannot paint outside its own window, so the shadow is drawn inside the panel's bounds, outside its border: the area for the content and the bars shrinks by DropShadowDepth on those two edges. The rest of the shadow band is painted in the colour of the nearest parent with an opaque background.

See also

ShouldNotPerformDockHostHorizontalSizePainting

public bool ShouldNotPerformDockHostHorizontalSizePainting

Gets whether the horizontal bar should stop short of the vertical bar – true while both are showing.

Remarks

Part of the panel's contract with the bars it hosts (IScrollersDockHost).

ShouldNotPerformDockHostVerticalSizePainting

public bool ShouldNotPerformDockHostVerticalSizePainting

Gets whether the vertical bar should stop short of the horizontal bar – true while both are showing.

Remarks

Part of the panel's contract with the bars it hosts (IScrollersDockHost).

ShouldProvideExtendedRenderingArtefacts

public bool ShouldProvideExtendedRenderingArtefacts

Gets whether the panel asks its scroll bars to fill the corner square between them.

Value
Always true.

VerticalScrollBar

public VerticalScrollBar VerticalScrollBar

Gets the panel's vertical scroll bar, to theme it or follow its events.

Value
The bar the panel created; never null. Its settings are saved with the form.
Remarks

The panel shows and hides the bar and sets its range, steps and position itself, whenever the content or the panel is resized; set its appearance, not its range.

Example
orderViewer.VerticalScrollBar.ScrollBarRenderingConfigurator.ColorTheme = ColorTheme.OfficeSilver;
orderViewer.VerticalScrollBar.ScrollBarRenderingConfigurator.AutoScrollInterval = 50;

Methods

IsInputKey

protected override bool IsInputKey(Keys keyData)

Claims the arrow keys and Page Up / Page Down, so they scroll the panel rather than move the focus.

Parameters
keyData
The key being tested.
Returns

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

OnHandleCreated

protected override void OnHandleCreated(EventArgs e)

Raises Control.HandleCreated and adds the two scroll bars to the panel.

Parameters
e
The event data.

OnKeyDown

protected override void OnKeyDown(KeyEventArgs e)

Raises Control.KeyDown, then scrolls the content: Up, Down, Left and Right by one ScrollSize step, Page Up and Page Down by a page (the visible height).

Parameters
e
The key data.

OnKeyUp

protected override void OnKeyUp(KeyEventArgs e)

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

Parameters
e
The key data.

OnMouseWheel

protected override void OnMouseWheel(MouseEventArgs e)

Raises Control.MouseWheel, then scrolls the content by one ScrollSize step: vertically, or horizontally while Shift is held.

Parameters
e
The wheel data.
Remarks

The notch is marked handled, so a form that also scrolls on the wheel does not move as well.

OnPaint

protected override void OnPaint(PaintEventArgs e)

Fills the client area in the system control colour and raises Control.Paint.

Parameters
e
The paint data.
Remarks

The part of the client area the content panel does not cover shows this colour, whatever Control.BackColor is.

OnParentBackColorChanged

protected override void OnParentBackColorChanged(EventArgs e)

Raises Control.ParentBackColorChanged and repaints the shadow band, which is filled with the colour behind the panel.

Parameters
e
The event data.

OnParentChanged

protected override void OnParentChanged(EventArgs e)

Raises Control.ParentChanged and starts following the new parent's size, to keep the corner square between the two bars in place.

Parameters
e
The event data.

OnSizeChanged

protected override void OnSizeChanged(EventArgs e)

Raises Control.SizeChanged, recalculates the scroll bars for the new size (their thumbs return to the start) and repaints the frame.

Parameters
e
The event data.

OnTabStopChanged

protected override void OnTabStopChanged(EventArgs e)

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

Parameters
e
The event data.

OnVisibleChanged

protected override void OnVisibleChanged(EventArgs e)

Raises Control.VisibleChanged and, when the panel is shown, recalculates the scroll bars.

Parameters
e
The event data.

WndProc

protected override void WndProc(ref Message m)

Processes the panel's window messages: it reserves room for the border and the drop shadow outside the client area, and draws them there.

Parameters
m
The message.

Events

ScrollerPanelUpdated

public event EventHandler<ScrollerPanelEventArgs> ScrollerPanelUpdated

Occurs when both scroll bars are showing and the size of the corner square between them needs updating.

Remarks

Part of the panel's contract with the scroll bars it hosts (IScrollerPanel), which place the corner square from it. An application does not normally need it.