HypernovaDesktop Components · docs
Binarymission
WinForms › Scroll Bar Marker › MarkerHorizontalScrollBar

MarkerHorizontalScrollBar

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

A horizontal scroll bar that shows marks on its track – events on a timeline, bookmarks, selected ranges – at the positions they belong to, so the user can see where they are and click to go there.

public class MarkerHorizontalScrollBar : HorizontalScrollBar

Inherits from / implements: HorizontalScrollBar

Remarks

It is a HorizontalScrollBar in every other respect, and draws the objects in ScrollBarMarks on top: shape marks centred on their value, range marks as a band from ScrollBarMarkBase.Value to ScrollBarRangeMark.EndValue, and image marks. ScrollBarMarkBase.Alignment puts a mark at the top, middle or bottom of the bar.

Turn on ShouldEnableMarkerDrawing – it is off by default – add marks to ScrollBarMarks, and call Invalidate() after changing the list. Marks are hit tested where they were last drawn. MarkerVerticalScrollBar describes the marks in more detail.

Examples

Marking the incidents on a 24-hour timeline, one minute per unit.

using Binarymission.WinForms.Controls.MarkerScrollBar;

var dayBar = new MarkerHorizontalScrollBar
{
    Location = new Point(12, 300),
    Width = 720,
    MaximumScrollRange = 24 * 60,
    LargeChange = 120,                 // two hours in view
    SmallChange = 15,
    ShouldEnableMarkerDrawing = true,
};

// The maintenance window, 02:00 to 03:30, as a band along the bottom.
dayBar.ScrollBarMarks.Add(new ScrollBarRangeMark
{
    Value = 120,
    EndValue = 210,
    Size = new SizeF(0, 4),
    Alignment = ScrollBarMarkAlignment.Bottom,
    StartColor = Color.SteelBlue,
    ToolTipInfo = "Maintenance window, 02:00 - 03:30",
});

// An outage at 14:05, as a red dot.
dayBar.ScrollBarMarks.Add(new ScrollBarShapeMark
{
    Value = 14 * 60 + 5,
    Size = new SizeF(6, 6),
    Shape = ScrollBarShapedMarkShape.Oval,
    Alignment = ScrollBarMarkAlignment.Center,
    StartColor = Color.Red,
    ToolTipTitle = "Outage",
    ToolTipInfo = "Payment gateway unreachable for 7 minutes",
    ToolTipIcon = ToolTipIcon.Warning,
});

dayBar.PositionChanged += (sender, e) => timelineLabel.Text = TimeSpan.FromMinutes(e.NewPosition).ToString(@"hh\:mm");
Controls.Add(dayBar);

See also

Members at a glance

Constructors
MarkerHorizontalScrollBarInitialises a bar with an empty mark list, marker drawing off, click-to-scroll and tool tips on.
Properties
ScrollBarMarksGets the marks drawn on the bar.
ShouldDisplayToolTipInfoOnBookmarkGets or sets whether hovering over a mark shows its tool tip.
ShouldEnableMarkerDrawingGets or sets whether the marks in ScrollBarMarks are drawn.
ShouldScrollUponBookmarkClickGets or sets whether clicking a mark scrolls to it.
Methods
OnMouseDownScrolls to the mark under the pointer when ShouldScrollUponBookmarkClick is on; otherwise, or away from any mark, handles the press as an ordinary scroll bar does.
OnMouseHoverRaises MouseHover and shows the tool tip of the mark under the pointer, with its title, icon and balloon setting, unless a mouse button is down.
OnMouseMoveHides the tool tip once the pointer leaves the mark it belongs to, then does the scroll bar's own pointer tracking.
OnMouseUpRaises MouseUp and ends any drag, as an ordinary scroll bar does.
PaintScrollBarDraws the scroll bar, then each mark in ScrollBarMarks over its track while ShouldEnableMarkerDrawing is on.

Constructors

MarkerHorizontalScrollBar

public MarkerHorizontalScrollBar() : base()

Initialises a bar with an empty mark list, marker drawing off, click-to-scroll and tool tips on.

Properties

ScrollBarMarks

public IList<ScrollBarMarkBase> ScrollBarMarks

Gets the marks drawn on the bar.

Value
A list, empty to begin with, of ScrollBarShapeMark, ScrollBarRangeMark and ScrollBarImageMark objects. Never null.
Remarks

Marks are drawn in list order, so a later mark covers an earlier one where they overlap, and the first mark under the pointer is the one clicked or hovered.

The bar does not watch the list: call Invalidate() after adding, removing or changing marks. Nothing is drawn until ShouldEnableMarkerDrawing is true.

ShouldDisplayToolTipInfoOnBookmark

public bool ShouldDisplayToolTipInfoOnBookmark

Gets or sets whether hovering over a mark shows its tool tip.

Value
The default is true.
Remarks

The bar does not read this property: a mark with ScrollBarMarkBase.ToolTipInfo shows its tool tip on hover whatever it is set to. To have no tool tip, leave ScrollBarMarkBase.ToolTipInfo empty.

ShouldEnableMarkerDrawing

public bool ShouldEnableMarkerDrawing

Gets or sets whether the marks in ScrollBarMarks are drawn.

Value
true to draw them; the default is false, so a new bar shows no marks until this is turned on.
Remarks

Setting it repaints the bar at once. Marks are still hit tested where they were last drawn while it is off – at the bar's top-left corner if they never were.

ShouldScrollUponBookmarkClick

public bool ShouldScrollUponBookmarkClick

Gets or sets whether clicking a mark scrolls to it.

Value
true (the default) to set ScrollBarBase.Position to the clicked mark's ScrollBarMarkBase.Value.
Remarks

A press of any mouse button on a mark scrolls, and replaces the bar's own handling of that press: no arrow, track or thumb action, and no MouseDown event. The move raises ScrollBarBase.PositionChanged. While this is false, a press on a mark acts on the part of the bar beneath it.

Methods

OnMouseDown

protected override void OnMouseDown(MouseEventArgs e)

Scrolls to the mark under the pointer when ShouldScrollUponBookmarkClick is on; otherwise, or away from any mark, handles the press as an ordinary scroll bar does.

Parameters
e
The mouse data.

OnMouseHover

protected override void OnMouseHover(EventArgs e)

Raises MouseHover and shows the tool tip of the mark under the pointer, with its title, icon and balloon setting, unless a mouse button is down.

Parameters
e
The event data.

OnMouseMove

protected override void OnMouseMove(MouseEventArgs e)

Hides the tool tip once the pointer leaves the mark it belongs to, then does the scroll bar's own pointer tracking.

Parameters
e
The mouse data.

OnMouseUp

protected override void OnMouseUp(MouseEventArgs e)

Raises MouseUp and ends any drag, as an ordinary scroll bar does.

Parameters
e
The mouse data.

PaintScrollBar

protected override void PaintScrollBar(Graphics g)

Draws the scroll bar, then each mark in ScrollBarMarks over its track while ShouldEnableMarkerDrawing is on.

Parameters
g
The surface to draw on.
Remarks

Each mark's drawn bounds are remembered for hit testing and tool tips.