HypernovaDesktop Components · docs
Binarymission
WinForms › Scroll Bars › ScrollBarRenderingConfigurator

ScrollBarRenderingConfigurator

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

The look of a scroll bar – colours, gradients, images, gripper – and how fast it repeats while an arrow is held. Every ScrollBarBase has one, in its ScrollBarBase.ScrollBarRenderingConfigurator property.

public sealed class ScrollBarRenderingConfigurator

Remarks

Start from a theme

Setting ColorTheme fills in the colours of a built-in theme, overwriting the ones it covers; set it first and adjust individual colours afterwards. A new configurator starts with ColorTheme.GradientBrown.

Gradients win over solid colours

The track, the thumb and the arrow buttons are each drawn as a gradient when both colours of their gradient pair are set, and in a solid colour (TrackFillColor, ThumbFillColor, NavigationButtonsColor) when either is Color.Empty. Every built-in theme sets the gradient pairs, so to use the solid colours, set a gradient colour to Color.Empty.

Images

An image set for a part and state (an arrow, the thumb, the gripper) replaces the drawn version of that part in that state; a state without an image falls back to the colours.

Arrow and gripper images are drawn at their own pixel size, not scaled with the display; thumb images are stretched over the thumb.

Examples

var look = statementBar.ScrollBarRenderingConfigurator;
look.ColorTheme = ColorTheme.Custom;                 // the theme first
look.GradientStartThumbFillColor = Color.Empty;      // solid fills from here on
look.ThumbFillColor = Color.FromArgb(0, 120, 215);
look.ControlVisualStateHoverColor = Color.FromArgb(0, 99, 177);
look.ControlVisualStatePressedColor = Color.FromArgb(0, 69, 120);
look.TrackFillColor = Color.FromArgb(240, 240, 240);
look.GradientStartTrackFillColor = Color.Empty;
look.ShouldDrawGripperArtefact = false;
statementBar.Invalidate();

See also

Members at a glance

Constructors
ScrollBarRenderingConfiguratorInitialises a configurator with the ColorTheme.GradientBrown theme, arrows on, and an auto-repeat interval of 100 milliseconds.
Properties
AutoScrollIntervalGets or sets how often the position steps while an arrow button or the track is held down.
BorderColorGets or sets the colour of the line around the bar, the arrow buttons and the thumb.
BuiltInNavigationButtonImageDimensionGets or sets the size of the drawn arrow on the arrow buttons.
ColorThemeGets or sets the built-in theme, and fills in its colours.
ControlOnHoverBorderHighlightColorGets or sets the outline of an arrow button or thumb while the pointer is over it.
ControlVisualStateHoverColorGets or sets the fill of an arrow button or thumb while the pointer is over it.
ControlVisualStatePressedColorGets or sets the fill of an arrow button while it is pressed, and of the thumb while it is dragged.
GradientEndNavigationButtonBackgroundColorGets or sets the right-hand colour of the gradient that fills an idle arrow button.
GradientEndThumbFillColorGets or sets the second colour of the thumb's gradient, which runs across the bar.
GradientEndTrackFillColorGets or sets the second colour of the track's gradient, which runs across the bar.
GradientStartNavigationButtonBackgroundColorGets or sets the left-hand colour of the gradient that fills an idle arrow button.
GradientStartThumbFillColorGets or sets the first colour of the thumb's gradient, which runs across the bar.
GradientStartTrackFillColorGets or sets the first colour of the track's gradient, which runs across the bar.
GripperColor1Gets or sets the colour of the first, third, fifth and seventh of the eight grip ridges on the thumb.
GripperColor2Gets or sets the colour of the second, fourth, sixth and eighth of the eight grip ridges on the thumb.
HorizontalGripperImageGets or sets an image drawn at the centre of a horizontal bar's thumb in place of the grip ridges.
HorizontalScrollButtonImageLeftHotGets or sets the image drawn on the left arrow button of a horizontal bar while the pointer is over it.
HorizontalScrollButtonImageLeftNormalGets or sets the image drawn on the left arrow button of a horizontal bar while it is idle.
HorizontalScrollButtonImageLeftPressedGets or sets the image drawn on the left arrow button of a horizontal bar while it is pressed.
HorizontalScrollButtonImageRightHotGets or sets the image drawn on the right arrow button of a horizontal bar while the pointer is over it.
HorizontalScrollButtonImageRightNormalGets or sets the image drawn on the right arrow button of a horizontal bar while it is idle.
HorizontalScrollButtonImageRightPressedGets or sets the image drawn on the right arrow button of a horizontal bar while it is pressed.
HorizontalThumbBoxImageHotGets or sets the image a horizontal bar's thumb is drawn with while the pointer is over it.
HorizontalThumbBoxImageNormalGets or sets the image a horizontal bar's thumb is drawn with while it is idle.
HorizontalThumbBoxImagePressedGets or sets the image a horizontal bar's thumb is drawn with while it is being dragged.
IsDrawingNavigationButtonArrowsEnabledGets or sets whether arrows, drawn or from images, appear on the arrow buttons.
NavigationButtonArrowColorGets or sets the colour of the arrows drawn on the arrow buttons.
NavigationButtonsColorGets or sets the solid fill of an idle arrow button, used when either button gradient colour is Color.Empty.
ShouldDrawBorderOnThumbWhenDrawingThumbAsCustomImageGets or sets whether the thumb's border is drawn around a thumb image.
ShouldDrawCustomNavigationButtonArrowImageUnscaledGets or sets whether an arrow button image larger than its button is drawn at its own size instead of being stretched to the button.
ShouldDrawGripperArtefactGets or sets whether grip ridges, or VerticalGripperImage / HorizontalGripperImage, are drawn across the middle of the thumb.
ThumbFillColorGets or sets the solid colour of an idle thumb, used when either thumb gradient colour is Color.Empty.
ThumbGripperMajorColorGets or sets a gripper colour that the themes set but the built-in drawing does not use.
ThumbGripperMinorColorGets or sets a gripper colour that the themes set but the built-in drawing does not use.
TrackFillColorGets or sets the solid colour of the track, used when either track gradient colour is Color.Empty.
VerticalGripperImageGets or sets an image drawn at the centre of a vertical bar's thumb in place of the grip ridges.
VerticalScrollButtonImageDownHotGets or sets the image drawn on the down arrow button of a vertical bar while the pointer is over it.
VerticalScrollButtonImageDownNormalGets or sets the image drawn on the down arrow button of a vertical bar while it is idle.
VerticalScrollButtonImageDownPressedGets or sets the image drawn on the down arrow button of a vertical bar while it is pressed.
VerticalScrollButtonImageUpHotGets or sets the image drawn on the up arrow button of a vertical bar while the pointer is over it.
VerticalScrollButtonImageUpNormalGets or sets the image drawn on the up arrow button of a vertical bar while it is idle.
VerticalScrollButtonImageUpPressedGets or sets the image drawn on the up arrow button of a vertical bar while it is pressed.
VerticalThumbBoxImageHotGets or sets the image a vertical bar's thumb is drawn with while the pointer is over it.
VerticalThumbBoxImageNormalGets or sets the image a vertical bar's thumb is drawn with while it is idle.
VerticalThumbBoxImagePressedGets or sets the image a vertical bar's thumb is drawn with while it is being dragged.

Constructors

ScrollBarRenderingConfigurator

public ScrollBarRenderingConfigurator()

Initialises a configurator with the ColorTheme.GradientBrown theme, arrows on, and an auto-repeat interval of 100 milliseconds.

Properties

AutoScrollInterval

public int AutoScrollInterval

Gets or sets how often the position steps while an arrow button or the track is held down.

Value
In milliseconds. The default is 100.
Default
100
Remarks

The first repeat comes after two intervals, so a quick click is a single step.

BorderColor

public Color BorderColor

Gets or sets the colour of the line around the bar, the arrow buttons and the thumb.

Value
Set by ColorTheme: white for ColorTheme.GradientBrown.
Remarks

A part under the pointer is outlined in ControlOnHoverBorderHighlightColor instead; a disabled bar is outlined in the system's light control colour.

BuiltInNavigationButtonImageDimension

public Size BuiltInNavigationButtonImageDimension

Gets or sets the size of the drawn arrow on the arrow buttons.

Value
Width by height in pixels, for an arrow pointing up or down (the two are swapped for left and right), not scaled with the display. The default, Size.Empty, draws a 7 by 4 arrow. A size larger than the button is cut to the button.

ColorTheme

public ColorTheme ColorTheme

Gets or sets the built-in theme, and fills in its colours.

Value
The default is ColorTheme.GradientBrown.
Remarks

Setting it overwrites the gradient, border, arrow, hover, pressed and gripper colours and ShouldDrawGripperArtefact, and turns the arrows back on, so set it before adjusting any of them. It does not touch the images, ThumbFillColor, NavigationButtonsColor or AutoScrollInterval, and only ColorTheme.Custom sets TrackFillColor.

ColorTheme.Custom sets a plain black-on-white starting point and leaves BorderColor and the hover and pressed colours as they were.

Example
foreach (var bar in new ScrollBarBase[] { reportPanel.VerticalScrollBar, reportPanel.HorizontalScrollBar })
{
    bar.ScrollBarRenderingConfigurator.ColorTheme = ColorTheme.OfficeBlack;
    bar.Invalidate();
}

ControlOnHoverBorderHighlightColor

public Color ControlOnHoverBorderHighlightColor

Gets or sets the outline of an arrow button or thumb while the pointer is over it.

Value
Set by ColorTheme. Color.Empty uses the system highlight colour.
Remarks

The thumb is also outlined in this colour, when idle or dragged, if BorderColor is Color.Empty.

ControlVisualStateHoverColor

public Color ControlVisualStateHoverColor

Gets or sets the fill of an arrow button or thumb while the pointer is over it.

Value
Set by ColorTheme: orange-brown for ColorTheme.GradientBrown.
Remarks

A gradient thumb keeps its gradient and starts it from this colour.

See also

ControlVisualStatePressedColor

public Color ControlVisualStatePressedColor

Gets or sets the fill of an arrow button while it is pressed, and of the thumb while it is dragged.

Value
Set by ColorTheme.
Remarks

A gradient thumb keeps its gradient and starts it from this colour.

See also

GradientEndNavigationButtonBackgroundColor

public Color GradientEndNavigationButtonBackgroundColor

Gets or sets the right-hand colour of the gradient that fills an idle arrow button.

Value
Set by ColorTheme. Color.Empty fills idle buttons with NavigationButtonsColor instead.

GradientEndThumbFillColor

public Color GradientEndThumbFillColor

Gets or sets the second colour of the thumb's gradient, which runs across the bar.

Value
Set by ColorTheme. Color.Empty fills the thumb with ThumbFillColor instead.
See also

GradientEndTrackFillColor

public Color GradientEndTrackFillColor

Gets or sets the second colour of the track's gradient, which runs across the bar.

Value
Set by ColorTheme. Color.Empty fills the track with TrackFillColor instead.
See also

GradientStartNavigationButtonBackgroundColor

public Color GradientStartNavigationButtonBackgroundColor

Gets or sets the left-hand colour of the gradient that fills an idle arrow button.

Value
Set by ColorTheme. Color.Empty fills idle buttons with NavigationButtonsColor instead.
Remarks

A button under the pointer or pressed is filled with ControlVisualStateHoverColor or ControlVisualStatePressedColor.

GradientStartThumbFillColor

public Color GradientStartThumbFillColor

Gets or sets the first colour of the thumb's gradient, which runs across the bar.

Value
Set by ColorTheme. Color.Empty fills the thumb with ThumbFillColor instead.
Remarks

Under the pointer or while dragged, the gradient starts from ControlVisualStateHoverColor or ControlVisualStatePressedColor instead.

See also

GradientStartTrackFillColor

public Color GradientStartTrackFillColor

Gets or sets the first colour of the track's gradient, which runs across the bar.

Value
Set by ColorTheme. Color.Empty fills the track with TrackFillColor instead.
See also

GripperColor1

public Color GripperColor1

Gets or sets the colour of the first, third, fifth and seventh of the eight grip ridges on the thumb.

Value
Set by ColorTheme: dark red for ColorTheme.GradientBrown.
See also

GripperColor2

public Color GripperColor2

Gets or sets the colour of the second, fourth, sixth and eighth of the eight grip ridges on the thumb.

Value
Set by ColorTheme: white for most themes.
See also

HorizontalGripperImage

public Bitmap HorizontalGripperImage

Gets or sets an image drawn at the centre of a horizontal bar's thumb in place of the grip ridges.

Value
null (the default) for the drawn ridges.
Remarks

Drawn only while ShouldDrawGripperArtefact is true.

HorizontalScrollButtonImageLeftHot

public Bitmap HorizontalScrollButtonImageLeftHot

Gets or sets the image drawn on the left arrow button of a horizontal bar while the pointer is over it.

Value
null (the default) to draw the arrow in NavigationButtonArrowColor.
Remarks

Drawn only while IsDrawingNavigationButtonArrowsEnabled is true, over the button's background. See ShouldDrawCustomNavigationButtonArrowImageUnscaled for an image larger than the button.

HorizontalScrollButtonImageLeftNormal

public Bitmap HorizontalScrollButtonImageLeftNormal

Gets or sets the image drawn on the left arrow button of a horizontal bar while it is idle.

Value
null (the default) to draw the arrow in NavigationButtonArrowColor.
Remarks

Drawn only while IsDrawingNavigationButtonArrowsEnabled is true, over the button's background. See ShouldDrawCustomNavigationButtonArrowImageUnscaled for an image larger than the button.

HorizontalScrollButtonImageLeftPressed

public Bitmap HorizontalScrollButtonImageLeftPressed

Gets or sets the image drawn on the left arrow button of a horizontal bar while it is pressed.

Value
null (the default) to draw the arrow in NavigationButtonArrowColor.
Remarks

Drawn only while IsDrawingNavigationButtonArrowsEnabled is true, over the button's background. See ShouldDrawCustomNavigationButtonArrowImageUnscaled for an image larger than the button.

HorizontalScrollButtonImageRightHot

public Bitmap HorizontalScrollButtonImageRightHot

Gets or sets the image drawn on the right arrow button of a horizontal bar while the pointer is over it.

Value
null (the default) to draw the arrow in NavigationButtonArrowColor.
Remarks

Drawn only while IsDrawingNavigationButtonArrowsEnabled is true, over the button's background. See ShouldDrawCustomNavigationButtonArrowImageUnscaled for an image larger than the button.

HorizontalScrollButtonImageRightNormal

public Bitmap HorizontalScrollButtonImageRightNormal

Gets or sets the image drawn on the right arrow button of a horizontal bar while it is idle.

Value
null (the default) to draw the arrow in NavigationButtonArrowColor.
Remarks

Drawn only while IsDrawingNavigationButtonArrowsEnabled is true, over the button's background. See ShouldDrawCustomNavigationButtonArrowImageUnscaled for an image larger than the button.

HorizontalScrollButtonImageRightPressed

public Bitmap HorizontalScrollButtonImageRightPressed

Gets or sets the image drawn on the right arrow button of a horizontal bar while it is pressed.

Value
null (the default) to draw the arrow in NavigationButtonArrowColor.
Remarks

Drawn only while IsDrawingNavigationButtonArrowsEnabled is true, over the button's background. See ShouldDrawCustomNavigationButtonArrowImageUnscaled for an image larger than the button.

HorizontalThumbBoxImageHot

public Bitmap HorizontalThumbBoxImageHot

Gets or sets the image a horizontal bar's thumb is drawn with while the pointer is over it.

Value
null (the default) to draw the thumb in colour in that state.
Remarks

Stretched over the whole thumb. While a thumb image is in use the gripper is not drawn, and the border only when ShouldDrawBorderOnThumbWhenDrawingThumbAsCustomImage is true.

HorizontalThumbBoxImageNormal

public Bitmap HorizontalThumbBoxImageNormal

Gets or sets the image a horizontal bar's thumb is drawn with while it is idle.

Value
null (the default) to draw the thumb in colour in that state.
Remarks

Stretched over the whole thumb. While a thumb image is in use the gripper is not drawn, and the border only when ShouldDrawBorderOnThumbWhenDrawingThumbAsCustomImage is true.

HorizontalThumbBoxImagePressed

public Bitmap HorizontalThumbBoxImagePressed

Gets or sets the image a horizontal bar's thumb is drawn with while it is being dragged.

Value
null (the default) to draw the thumb in colour in that state.
Remarks

Stretched over the whole thumb. While a thumb image is in use the gripper is not drawn, and the border only when ShouldDrawBorderOnThumbWhenDrawingThumbAsCustomImage is true.

IsDrawingNavigationButtonArrowsEnabled

public bool IsDrawingNavigationButtonArrowsEnabled

Gets or sets whether arrows, drawn or from images, appear on the arrow buttons.

Value
true by default and for every theme; false leaves plain buttons.

NavigationButtonArrowColor

public Color NavigationButtonArrowColor

Gets or sets the colour of the arrows drawn on the arrow buttons.

Value
Set by ColorTheme: maroon for ColorTheme.GradientBrown, black for most others.
Remarks

Not used for a button state that has an arrow image.

NavigationButtonsColor

public Color NavigationButtonsColor

Gets or sets the solid fill of an idle arrow button, used when either button gradient colour is Color.Empty.

Value
No theme sets it; a new configurator starts with Color.Empty.
See also

ShouldDrawBorderOnThumbWhenDrawingThumbAsCustomImage

public bool ShouldDrawBorderOnThumbWhenDrawingThumbAsCustomImage

Gets or sets whether the thumb's border is drawn around a thumb image.

Value
true to outline the image in BorderColor; the default is false.
Default
false
See also

ShouldDrawCustomNavigationButtonArrowImageUnscaled

public bool ShouldDrawCustomNavigationButtonArrowImageUnscaled

Gets or sets whether an arrow button image larger than its button is drawn at its own size instead of being stretched to the button.

Value
true to draw the image at its own size from the button's top-left corner, where it can spill past the button; false (the default) to stretch an image that does not fit over the whole button. An image that fits is always drawn at its own size, centred.
Default
false

ShouldDrawGripperArtefact

public bool ShouldDrawGripperArtefact

Gets or sets whether grip ridges, or VerticalGripperImage / HorizontalGripperImage, are drawn across the middle of the thumb.

Value
Set by ColorTheme: true for every theme except ColorTheme.Win8.
Remarks

The gripper is left out on a thumb shorter than 12 logical pixels and on a thumb drawn from an image.

ThumbFillColor

public Color ThumbFillColor

Gets or sets the solid colour of an idle thumb, used when either thumb gradient colour is Color.Empty.

Value
No theme sets it; a new configurator starts with Color.Empty.
See also

ThumbGripperMajorColor

public Color ThumbGripperMajorColor

Gets or sets a gripper colour that the themes set but the built-in drawing does not use.

Value
Set by ColorTheme.
Remarks

The grip ridges are drawn in GripperColor1 and GripperColor2.

ThumbGripperMinorColor

public Color ThumbGripperMinorColor

Gets or sets a gripper colour that the themes set but the built-in drawing does not use.

Value
Set by ColorTheme.
Remarks

The grip ridges are drawn in GripperColor1 and GripperColor2.

TrackFillColor

public Color TrackFillColor

Gets or sets the solid colour of the track, used when either track gradient colour is Color.Empty.

Value
White for ColorTheme.Custom; the other themes leave it as it was, and a new configurator starts with Color.Empty.
See also

VerticalGripperImage

public Bitmap VerticalGripperImage

Gets or sets an image drawn at the centre of a vertical bar's thumb in place of the grip ridges.

Value
null (the default) for the drawn ridges.
Remarks

Drawn only while ShouldDrawGripperArtefact is true.

VerticalScrollButtonImageDownHot

public Bitmap VerticalScrollButtonImageDownHot

Gets or sets the image drawn on the down arrow button of a vertical bar while the pointer is over it.

Value
null (the default) to draw the arrow in NavigationButtonArrowColor.
Remarks

Drawn only while IsDrawingNavigationButtonArrowsEnabled is true, over the button's background. See ShouldDrawCustomNavigationButtonArrowImageUnscaled for an image larger than the button.

VerticalScrollButtonImageDownNormal

public Bitmap VerticalScrollButtonImageDownNormal

Gets or sets the image drawn on the down arrow button of a vertical bar while it is idle.

Value
null (the default) to draw the arrow in NavigationButtonArrowColor.
Remarks

Drawn only while IsDrawingNavigationButtonArrowsEnabled is true, over the button's background. See ShouldDrawCustomNavigationButtonArrowImageUnscaled for an image larger than the button.

VerticalScrollButtonImageDownPressed

public Bitmap VerticalScrollButtonImageDownPressed

Gets or sets the image drawn on the down arrow button of a vertical bar while it is pressed.

Value
null (the default) to draw the arrow in NavigationButtonArrowColor.
Remarks

Drawn only while IsDrawingNavigationButtonArrowsEnabled is true, over the button's background. See ShouldDrawCustomNavigationButtonArrowImageUnscaled for an image larger than the button.

VerticalScrollButtonImageUpHot

public Bitmap VerticalScrollButtonImageUpHot

Gets or sets the image drawn on the up arrow button of a vertical bar while the pointer is over it.

Value
null (the default) to draw the arrow in NavigationButtonArrowColor.
Remarks

Drawn only while IsDrawingNavigationButtonArrowsEnabled is true, over the button's background. See ShouldDrawCustomNavigationButtonArrowImageUnscaled for an image larger than the button.

VerticalScrollButtonImageUpNormal

public Bitmap VerticalScrollButtonImageUpNormal

Gets or sets the image drawn on the up arrow button of a vertical bar while it is idle.

Value
null (the default) to draw the arrow in NavigationButtonArrowColor.
Remarks

Drawn only while IsDrawingNavigationButtonArrowsEnabled is true, over the button's background. See ShouldDrawCustomNavigationButtonArrowImageUnscaled for an image larger than the button.

VerticalScrollButtonImageUpPressed

public Bitmap VerticalScrollButtonImageUpPressed

Gets or sets the image drawn on the up arrow button of a vertical bar while it is pressed.

Value
null (the default) to draw the arrow in NavigationButtonArrowColor.
Remarks

Drawn only while IsDrawingNavigationButtonArrowsEnabled is true, over the button's background. See ShouldDrawCustomNavigationButtonArrowImageUnscaled for an image larger than the button.

VerticalThumbBoxImageHot

public Bitmap VerticalThumbBoxImageHot

Gets or sets the image a vertical bar's thumb is drawn with while the pointer is over it.

Value
null (the default) to draw the thumb in colour in that state.
Remarks

Stretched over the whole thumb. While a thumb image is in use the gripper is not drawn, and the border only when ShouldDrawBorderOnThumbWhenDrawingThumbAsCustomImage is true.

VerticalThumbBoxImageNormal

public Bitmap VerticalThumbBoxImageNormal

Gets or sets the image a vertical bar's thumb is drawn with while it is idle.

Value
null (the default) to draw the thumb in colour in that state.
Remarks

Stretched over the whole thumb. While a thumb image is in use the gripper is not drawn, and the border only when ShouldDrawBorderOnThumbWhenDrawingThumbAsCustomImage is true.

VerticalThumbBoxImagePressed

public Bitmap VerticalThumbBoxImagePressed

Gets or sets the image a vertical bar's thumb is drawn with while it is being dragged.

Value
null (the default) to draw the thumb in colour in that state.
Remarks

Stretched over the whole thumb. While a thumb image is in use the gripper is not drawn, and the border only when ShouldDrawBorderOnThumbWhenDrawingThumbAsCustomImage is true.