HypernovaDesktop Components · docs
Binarymission
WinForms › Scrollable Picture › ScrollablePicture

ScrollablePicture

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

A picture box for images larger than itself – plans, scans, maps, charts – that scrolls the image at full size with the suite's themeable scroll bars.

public class ScrollablePicture : Control, IScrollersDockHost

Inherits from / implements: Control, IScrollersDockHost

Remarks

What it is for

Use it to show an image at its own pixel size when it does not fit: a scanned delivery note, a site plan, a large chart. Assign Image; the control shows its VerticalScrollBar when the image is taller than the control and its HorizontalScrollBar when it is wider.

How it scrolls

The image is drawn from its top-left corner, unscaled. Scrolling shifts the pixels already on screen and draws only the strip that comes into view, so a large image scrolls smoothly. One arrow click, arrow key or wheel notch moves by ScrollSize, a page by the visible size. Whenever the image or the control is resized the bars are recalculated and their thumbs return to the start.

Keyboard and mouse

A click gives the control the focus. 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.

Appearance

The area the image does not cover is filled in the system control colour. Theme the bars through VerticalScrollBar and HorizontalScrollBar; their thickness is in device pixels and follows the system scroll bar size (see ScrollBarBase). The bars have no right-click menu unless you turn it on.

Examples

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

var sitePlan = new ScrollablePicture
{
    Dock = DockStyle.Fill,
    ScrollSize = new Size(32, 32),
    Image = new Bitmap(@"C:\Plans\Warehouse-Level2.png"),
};

sitePlan.VerticalScrollBar.ScrollBarRenderingConfigurator.ColorTheme = ColorTheme.OfficeSilver;
sitePlan.HorizontalScrollBar.ScrollBarRenderingConfigurator.ColorTheme = ColorTheme.OfficeSilver;
sitePlan.VerticalScrollBar.IsDefaultScrollContextMenuEnabled = true;

Controls.Add(sitePlan);

See also

Members at a glance

Constructors
ScrollablePictureInitialises an empty scrollable picture with a scroll step of 8 pixels.
Properties
DefaultSizeGets the size a new control starts at: 150 by 150 pixels.
DockHostGets the control the scroll bars dock into: the picture control itself.
HorizontalScrollBarGets the control's horizontal scroll bar, to theme it or follow its events.
ImageGets or sets the image to show, at its own pixel size.
ScrollSizeGets or sets how far one arrow click, arrow key or wheel notch scrolls the image.
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.
VerticalScrollBarGets the control's vertical scroll bar, to theme it or follow its events.
Methods
DisposeReleases the control, including its GDI copy of Image. The Bitmap itself is not disposed.
IsInputKeyClaims the arrow keys and Page Up / Page Down, so they scroll the image rather than move the focus.
OnHandleCreatedRaises Control.HandleCreated and adds the two scroll bars to the control.
OnKeyDownRaises Control.KeyDown, then scrolls the image: Up, Down, Left and Right by one ScrollSize step, Page Up and Page Down by a page (the visible height).
OnKeyUpRaises Control.KeyUp. The control does nothing more on a key release.
OnMouseClickRaises Control.MouseClick and gives the control the focus, so the keyboard scrolls it.
OnMouseWheelRaises Control.MouseWheel, then scrolls the image by one ScrollSize step: vertically, or horizontally while Shift is held.
OnPaintRaises Control.Paint, fills the client area in the system control colour, and draws the visible part of the image at the current scroll offset, leaving out the area under the bars.
OnSizeChangedRaises Control.SizeChanged and recalculates the scroll bars for the new size; their thumbs return to the start.
OnTabStopChangedRaises Control.TabStopChanged and makes the control focusable, or not, to match Control.TabStop.
OnVisibleChangedRaises Control.VisibleChanged and, when the control is shown, recalculates the scroll bars.

Constructors

ScrollablePicture

public ScrollablePicture()

Initialises an empty scrollable picture with a scroll step of 8 pixels.

Properties

DefaultSize

protected override Size DefaultSize

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

DockHost

public Control DockHost

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

HorizontalScrollBar

public HorizontalScrollBar HorizontalScrollBar

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

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

The control shows and hides the bar and sets its range, steps and position itself; set its appearance, not its range.

Image

public Bitmap Image

Gets or sets the image to show, at its own pixel size.

Value
The image, or null (the default) for none.
Default
null
Remarks

Assigning an image shows the scroll bars it needs and returns them to the start. The control keeps a GDI copy of the bitmap, taken when it is assigned, and repaints from it: to show a changed image, assign a new Bitmap – assigning the same instance again does nothing.

The control does not dispose the Bitmap you assign; dispose it once it is no longer shown.

Example
var previous = scanViewer.Image;
scanViewer.Image = new Bitmap(openFileDialog.FileName);
previous?.Dispose();

ScrollSize

public Size ScrollSize

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

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

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

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 control'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 control's contract with the bars it hosts (IScrollersDockHost).

VerticalScrollBar

public VerticalScrollBar VerticalScrollBar

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

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

The control shows and hides the bar and sets its range, steps and position itself; set its appearance, not its range.

Methods

Dispose

protected override void Dispose(bool disposing)

Releases the control, including its GDI copy of Image. The Bitmap itself is not disposed.

Parameters
disposing
true to release managed and unmanaged resources; false to release only unmanaged resources.

IsInputKey

protected override bool IsInputKey(Keys keyData)

Claims the arrow keys and Page Up / Page Down, so they scroll the image 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 control.

Parameters
e
The event data.

OnKeyDown

protected override void OnKeyDown(KeyEventArgs e)

Raises Control.KeyDown, then scrolls the image: 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 control does nothing more on a key release.

Parameters
e
The key data.

OnMouseClick

protected override void OnMouseClick(MouseEventArgs e)

Raises Control.MouseClick and gives the control the focus, so the keyboard scrolls it.

Parameters
e
The mouse data.

OnMouseWheel

protected override void OnMouseWheel(MouseEventArgs e)

Raises Control.MouseWheel, then scrolls the image 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 pe)

Raises Control.Paint, fills the client area in the system control colour, and draws the visible part of the image at the current scroll offset, leaving out the area under the bars.

Parameters
pe
The paint data.

OnSizeChanged

protected override void OnSizeChanged(EventArgs e)

Raises Control.SizeChanged and recalculates the scroll bars for the new size; their thumbs return to the start.

Parameters
e
The event data.

OnTabStopChanged

protected override void OnTabStopChanged(EventArgs e)

Raises Control.TabStopChanged and makes the control 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 control is shown, recalculates the scroll bars.

Parameters
e
The event data.