WinForms › Explorer Bar › BinaryExplorerBarPanel

BinaryExplorerBarPanel

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

One collapsible group in a BinaryExplorerBar: a scrolling container for your own controls, under a title the bar draws and the user clicks to open and close it.

public class BinaryExplorerBarPanel : Panel, IBinaryControlExtendedServices

Inherits from / implements: Panel, IBinaryControlExtendedServices

Remarks

What it is for

Put the controls of one group – a list of task links, a set of filter options, the details of the selected item – on a panel, give it a title, and add it to BinaryExplorerBar.Panels. The panel scrolls when its controls do not fit.

Key concepts

The title belongs to the bar. The bar draws the title above the panel and handles clicks on it; the panel's title properties tell it what to draw.
Heights. CurrentHeight, in logical pixels, is the height the panel has when expanded; a collapsed panel has no height and only its title shows. Set CurrentHeight rather than Control.Height before adding the panel.
Inherited look. Every title colour, the font, the border and the shadow default to the bar's DefaultPanel... settings: leave a colour empty to use the bar's, set it to give this panel its own.
Disabled panels. A disabled panel's title is greyed, and the panel neither opens nor closes – by click or by the bar's Reset... methods.

Examples

var filters = new BinaryExplorerBarPanel
{
    PanelTitleText = "Filter orders",
    CurrentHeight = 110,                       // expanded height, logical pixels
    PanelTitleForeColor = Color.Navy,
    PanelTitleGradientBeginColor = Color.White,
    PanelTitleGradientEndColor = Color.LightSteelBlue,
    PanelBorderColor = Color.SteelBlue,
};
filters.Controls.Add(new CheckBox { Text = "Unpaid only", Location = new Point(10, 10), AutoSize = true });
filters.Controls.Add(new CheckBox { Text = "Shipped this week", Location = new Point(10, 36), AutoSize = true });
filters.Controls.Add(new CheckBox { Text = "Over 1,000 GBP", Location = new Point(10, 62), AutoSize = true });

explorerBar.Panels.Add(filters);

Members at a glance

Constructors
`BinaryExplorerBarPanel`	Initialises a new, expanded `BinaryExplorerBarPanel` with scrolling switched on, a pale green body and an expanded height of 100 logical pixels.
Properties
`BackColor`	Gets or sets the colour of the panel's body, behind its controls.
`BackgroundPaintingStyleForControlTitle`	Gets or sets whether the title is filled with a gradient or a solid colour.
`CurrentExplorerBarPanelState`	Gets or sets whether the panel is expanded or collapsed to its title.
`CurrentHeight`	Gets or sets the height the panel has when it is expanded.
`DownArrowImage`	Gets or sets a picture of your own for the button at the right of the title while the panel is collapsed.
`DrawPanelTitleBackgroundImageWithTheDefaultHeight`	Gets or sets whether a title drawn from `PanelTitleBackgroundImage` keeps the standard title height rather than taking the image's height.
`DrawPanelTitleText`	Gets or sets whether the title text is drawn.
`OnHoverUpDownArrowColor`	Gets or sets the colour of the arrow and outline of the expand and collapse button while the pointer is over this panel's title.
`OnHoverUpDownArrowEllipseFillColor`	Gets or sets the fill of the expand and collapse button while the pointer is over this panel's title.
`OnNormalUpDownArrowColor`	Gets or sets the colour of the arrow and outline of this panel's expand and collapse button. The arrow points up while the panel is expanded and down while it is collapsed.
`OnNormalUpDownArrowEllipseFillColor`	Gets or sets the fill of the round expand and collapse button at the right of this panel's title.
`PanelBorderColor`	Gets or sets the colour of the one-pixel border drawn round this panel and its title.
`PanelShadowColor`	Gets or sets the colour of this panel's shadow.
`PanelShadowDepth`	Gets or sets how far the soft shadow under this panel reaches.
`PanelTitleBackColor`	Gets or sets the solid colour of the title, used when the title is not a gradient.
`PanelTitleBackStyle`	Gets or sets whether the title is drawn from a picture.
`PanelTitleBackgroundImage`	Gets or sets the picture drawn as the title, stretched across it, when `PanelTitleBackStyle` is `ControlBackgroundPaintingStyle.ImageStyle`.
`PanelTitleBackgroundImageTransparentColor`	Gets or sets the colour made transparent in `PanelTitleBackgroundImage`.
`PanelTitleFont`	Gets or sets the font of the title text.
`PanelTitleForeColor`	Gets or sets the colour of the title text.
`PanelTitleGradientBeginColor`	Gets or sets the colour at the left of the title's gradient.
`PanelTitleGradientEndColor`	Gets or sets the colour at the right of the title's gradient.
`PanelTitleHoverColor`	Gets or sets the colour of the title text while the pointer is over the title.
`PanelTitleImage`	Gets or sets the picture shown at the left of the title, before the text – the large icon of an Explorer task group.
`PanelTitleImageTransparentColor`	Gets or sets the colour made transparent in `PanelTitleImage`.
`PanelTitleText`	Gets or sets the text of the panel's title.
`ReflectCurrentXPTheme`	Gets or sets whether the panel is following the system's visual style along with its bar.
`ShouldPaintCornersAsRoundedRect`	Gets or sets whether the top corners of the title are drawn rounded.
`UpArrowImage`	Gets or sets a picture of your own for the button at the right of the title while the panel is expanded.
Methods
`OnEnabledChanged`	Raises the `Control.EnabledChanged` event, and has the bar redraw the panel's title greyed or in colour.
`OnSizeChanged`	Raises the `Control.SizeChanged` event, and – while the panel is expanded in a bar – records the new height as `CurrentHeight` and lays the bar out again.
`OnVisibleChanged`	Raises the `Control.VisibleChanged` event, and lays the bar out again: a hidden panel takes no room, title and all.

Constructors

BinaryExplorerBarPanel

public BinaryExplorerBarPanel()

Initialises a new, expanded BinaryExplorerBarPanel with scrolling switched on, a pale green body and an expanded height of 100 logical pixels.

Properties

BackColor

public override Color BackColor

Gets or sets the colour of the panel's body, behind its controls.

Value: The default is RGB(214, 248, 219), a pale green.
Designer category: General Control properties

Remarks

Choosing an BinaryExplorerBar.XPTheme replaces it.

BackgroundPaintingStyleForControlTitle

public ControlBackgroundPaintingStyle BackgroundPaintingStyleForControlTitle

Gets or sets whether the title is filled with a gradient or a solid colour.

Value: The default is ControlBackgroundPaintingStyle.GradientColorStyle: a left-to-right gradient from PanelTitleGradientBeginColor to PanelTitleGradientEndColor. Any other value fills the title with PanelTitleBackColor.
Default: GradientColorStyle
Designer category: General Control properties

Remarks

A picture set through PanelTitleBackStyle is drawn instead of either fill.

CurrentExplorerBarPanelState

public BinaryExplorerBarPanelState CurrentExplorerBarPanelState

Gets or sets whether the panel is expanded or collapsed to its title.

Value: The default is BinaryExplorerBarPanelState.Expanded.
Default: Expanded
Designer category: General Control properties

Remarks

Setting the property from code opens or closes the panel at once, without animation, and the bar lays itself out again. Expanding gives the panel its CurrentHeight. A panel added to the bar in the collapsed state starts collapsed.

The user changes it by clicking the title, which animates when BinaryExplorerBar.PerformAnimation is on.

Example

// Show the details group as soon as something is selected.
detailsPanel.CurrentExplorerBarPanelState = filesList.SelectedItems.Count > 0
    ? BinaryExplorerBarPanelState.Expanded
    : BinaryExplorerBarPanelState.Collapsed;

CurrentHeight

public int CurrentHeight

Gets or sets the height the panel has when it is expanded.

Value: The height in logical pixels (1/96 inch), scaled with the display. The default is 100.
Default: 100

Remarks

Set this before adding the panel to the bar: the panel is given this height as it is added or expanded. Setting it while the panel is already expanded takes effect the next time the panel is expanded.

The value follows the panel: when the user drags the panel taller or shorter, or code changes the Control.Height of an expanded panel in a bar, the new height is recorded here.

DownArrowImage

public Bitmap DownArrowImage

Gets or sets a picture of your own for the button at the right of the title while the panel is collapsed.

Value: The default is null: the built-in round button with a down arrow.
Default: null
Designer category: Title properties

Remarks

Set UpArrowImage as well: with only one of the two set, a built-in picture is shown in place of yours in at least one state.

DrawPanelTitleBackgroundImageWithTheDefaultHeight

public bool DrawPanelTitleBackgroundImageWithTheDefaultHeight

Gets or sets whether a title drawn from PanelTitleBackgroundImage keeps the standard title height rather than taking the image's height.

Value: true to keep the standard height of 24 logical pixels, stretching the image to it. The default is false: the title is as tall as the image.

Remarks

Applies only while PanelTitleBackgroundImage is set and the title is drawn from an image (PanelTitleBackStyle is ControlBackgroundPaintingStyle.ImageStyle).

DrawPanelTitleText

public bool DrawPanelTitleText

Gets or sets whether the title text is drawn.

Value: true to draw PanelTitleText. The default is true.

Remarks

Turn the text off when the title's background image already carries the words; the title still opens and closes the panel.

OnHoverUpDownArrowColor

public Color OnHoverUpDownArrowColor

Gets or sets the colour of the arrow and outline of the expand and collapse button while the pointer is over this panel's title.

Value: The default is Color.Blue.
Designer category: Colors

Remarks

The colour is used by the built-in button, which is drawn while DownArrowImage is not set. Choosing an BinaryExplorerBar.XPTheme replaces it.

OnHoverUpDownArrowEllipseFillColor

public Color OnHoverUpDownArrowEllipseFillColor

Gets or sets the fill of the expand and collapse button while the pointer is over this panel's title.

Value: The default is Color.Yellow.
Designer category: Colors

Remarks

The colour is used by the built-in button, which is drawn while DownArrowImage is not set. Choosing an BinaryExplorerBar.XPTheme replaces it.

OnNormalUpDownArrowColor

public Color OnNormalUpDownArrowColor

Gets or sets the colour of the arrow and outline of this panel's expand and collapse button. The arrow points up while the panel is expanded and down while it is collapsed.

Value: The default is Color.Green.
Designer category: Colors

Remarks

The colour is used by the built-in button, which is drawn while DownArrowImage is not set. Choosing an BinaryExplorerBar.XPTheme replaces it.

OnNormalUpDownArrowEllipseFillColor

public Color OnNormalUpDownArrowEllipseFillColor

Gets or sets the fill of the round expand and collapse button at the right of this panel's title.

Value: The default is RGB(214, 248, 219), a pale green.
Designer category: Colors

Remarks

The colour is used by the built-in button, which is drawn while DownArrowImage is not set. Choosing an BinaryExplorerBar.XPTheme replaces it.

PanelBorderColor

public Color PanelBorderColor

Gets or sets the colour of the one-pixel border drawn round this panel and its title.

Value: The default is Color.Empty: the bar's BinaryExplorerBar.DefaultPanelBorderColor. When that is empty too, no border is drawn.
Designer category: Title properties

Remarks

The bar draws the border one pixel outside the panel, in its margins.

PanelShadowColor

public Color PanelShadowColor

Gets or sets the colour of this panel's shadow.

Value: The default is Color.Empty: the bar's BinaryExplorerBar.DefaultPanelShadowColor, or a soft black when that is empty too.
Designer category: Title properties

Remarks

The colour's alpha sets how dark the shadow is at its strongest.

PanelShadowDepth

public int PanelShadowDepth

Gets or sets how far the soft shadow under this panel reaches.

Value: The depth in logical pixels (1/96 inch); 0 draws no shadow. The default is -1: the bar's BinaryExplorerBar.DefaultPanelShadowDepth. Values below -1 are ignored.
Default: -1
Designer category: Title properties

Remarks

The bar draws the shadow in its margins round the panel, where the border is.

PanelTitleBackColor

public Color PanelTitleBackColor

Gets or sets the solid colour of the title, used when the title is not a gradient.

Value: The default is Color.Empty: the bar's BinaryExplorerBar.DefaultPanelTitleBackColor.
Designer category: Title properties

Remarks

Used while BackgroundPaintingStyleForControlTitle is not ControlBackgroundPaintingStyle.GradientColorStyle.

PanelTitleBackStyle

public ControlBackgroundPaintingStyle PanelTitleBackStyle

Gets or sets whether the title is drawn from a picture.

Value: The default is ControlBackgroundPaintingStyle.GradientColorStyle.
Default: ControlBackgroundPaintingStyle.GradientColorStyle
Designer category: Title properties

Remarks

With ControlBackgroundPaintingStyle.ImageStyle the title is PanelTitleBackgroundImage stretched across it, or the bar's BinaryExplorerBar.DefaultPanelTitleBackgroundImage when the panel has none. With either other value – or when there is no picture – the title is filled as BackgroundPaintingStyleForControlTitle says.

PanelTitleBackgroundImage

public Bitmap PanelTitleBackgroundImage

Gets or sets the picture drawn as the title, stretched across it, when PanelTitleBackStyle is ControlBackgroundPaintingStyle.ImageStyle.

Value: The default is null: the bar's BinaryExplorerBar.DefaultPanelTitleBackgroundImage, if any.
Default: null
Designer category: Title properties

Remarks

The title takes the picture's height unless DrawPanelTitleBackgroundImageWithTheDefaultHeight is on. When PanelTitleBackgroundImageTransparentColor is already set, that colour is made transparent in the bitmap you assign.

PanelTitleBackgroundImageTransparentColor

public Color PanelTitleBackgroundImageTransparentColor

Gets or sets the colour made transparent in PanelTitleBackgroundImage.

Value: The default is Color.Empty: no colour is made transparent.
Designer category: Title properties

Remarks

The colour is made transparent in the bitmap itself, when the image is assigned and when this colour changes. A colour made transparent earlier stays transparent.

PanelTitleFont

public Font PanelTitleFont

Gets or sets the font of the title text.

Value: The default is null: the bar's BinaryExplorerBar.DefaultPanelTitleFont.
Default: null
Designer category: Title properties

PanelTitleForeColor

public Color PanelTitleForeColor

Gets or sets the colour of the title text.

Value: The default is Color.Empty: the bar's BinaryExplorerBar.DefaultPanelTitleForeColor.
Designer category: Title properties

Remarks

A disabled panel's title is drawn in SystemColors.GrayText whatever this colour is.

PanelTitleGradientBeginColor

public Color PanelTitleGradientBeginColor

Gets or sets the colour at the left of the title's gradient.

Value: The default is Color.Empty: the bar's BinaryExplorerBar.DefaultPanelTitleGradientBeginColor.
Designer category: Title properties

Remarks

Used while BackgroundPaintingStyleForControlTitle is ControlBackgroundPaintingStyle.GradientColorStyle, the default.

PanelTitleGradientEndColor

public Color PanelTitleGradientEndColor

Gets or sets the colour at the right of the title's gradient.

Value: The default is Color.Empty: the bar's BinaryExplorerBar.DefaultPanelTitleGradientEndColor.
Designer category: Title properties

PanelTitleHoverColor

public Color PanelTitleHoverColor

Gets or sets the colour of the title text while the pointer is over the title.

Value: The default is Color.Empty: the bar's BinaryExplorerBar.DefaultPanelTitleHoverColor, or a lighter shade of the text colour when that is empty too.
Designer category: Title properties

PanelTitleImage

public Bitmap PanelTitleImage

Gets or sets the picture shown at the left of the title, before the text – the large icon of an Explorer task group.

Value: The default is null: no picture.
Default: null
Designer category: Title properties

Remarks

The picture is drawn at its own size, standing on the bottom of the title, so a picture taller than the title rises above it into the margin, as in Windows XP. A disabled panel shows it greyed.

The pixels of PanelTitleImageTransparentColor are made transparent in the bitmap you assign. Assign null to remove the picture.

PanelTitleImageTransparentColor

public Color PanelTitleImageTransparentColor

Gets or sets the colour made transparent in PanelTitleImage.

Value: The default is Color.Empty.
Default: Empty
Designer category: Title properties

Remarks

The colour is applied to the bitmap itself, when the image is assigned and when this colour changes. A colour made transparent earlier stays transparent.

PanelTitleText

public string PanelTitleText

Gets or sets the text of the panel's title.

Value: The default is empty, which shows the panel's Control.Name.
Designer category: Title properties

Remarks

The text is drawn on one line at the left of the title, after PanelTitleImage, vertically centred, and trimmed at a word with an ellipsis when it does not fit. When the property is read while empty, it takes the value of Control.Name.

ReflectCurrentXPTheme

public bool ReflectCurrentXPTheme

Gets or sets whether the panel is following the system's visual style along with its bar.

Value: The default is false.

Remarks

The bar sets this property on its panels from BinaryExplorerBar.ReflectCurrentXPTheme, and does the work of applying the colours itself; setting it on a panel directly only repaints the panel.

ShouldPaintCornersAsRoundedRect

public bool ShouldPaintCornersAsRoundedRect

Gets or sets whether the top corners of the title are drawn rounded.

Value: true for rounded corners. The default is true.
Default: true
Designer category: Title properties

Remarks

The bar's BinaryExplorerBar.ShouldPaintPanelItemCornersAsRoundedRect sets this property on every panel it holds.

UpArrowImage

public Bitmap UpArrowImage

Gets or sets a picture of your own for the button at the right of the title while the panel is expanded.

Value: The default is null: the built-in round button with an up arrow.
Default: null
Designer category: Title properties

Remarks

Set DownArrowImage as well: with only one of the two set, a built-in picture is shown in place of yours in at least one state. A disabled panel shows the picture greyed.

Example

panel.UpArrowImage = new Bitmap("Images\\chevron-up.png");
panel.DownArrowImage = new Bitmap("Images\\chevron-down.png");

Methods

OnEnabledChanged

protected override void OnEnabledChanged(EventArgs e)

Raises the Control.EnabledChanged event, and has the bar redraw the panel's title greyed or in colour.

Parameters

e: The data for the event.

OnSizeChanged

protected override void OnSizeChanged(EventArgs e)

Raises the Control.SizeChanged event, and – while the panel is expanded in a bar – records the new height as CurrentHeight and lays the bar out again.

Parameters

e: The data for the event.

OnVisibleChanged

protected override void OnVisibleChanged(EventArgs e)

Raises the Control.VisibleChanged event, and lays the bar out again: a hidden panel takes no room, title and all.

Parameters

e: The data for the event.

BinaryExplorerBarPanel

Remarks

What it is for

Key concepts

Examples

See also

Members at a glance

Constructors

BinaryExplorerBarPanel

Properties

BackColor

Remarks

BackgroundPaintingStyleForControlTitle

Remarks

CurrentExplorerBarPanelState

Remarks

Example

See also

CurrentHeight

Remarks

DownArrowImage

Remarks

See also

DrawPanelTitleBackgroundImageWithTheDefaultHeight

Remarks

DrawPanelTitleText

Remarks

OnHoverUpDownArrowColor

Remarks

OnHoverUpDownArrowEllipseFillColor

Remarks

OnNormalUpDownArrowColor

Remarks

See also

OnNormalUpDownArrowEllipseFillColor

Remarks

See also

PanelBorderColor

Remarks

PanelShadowColor

Remarks

PanelShadowDepth

Remarks

See also

PanelTitleBackColor

Remarks

PanelTitleBackStyle

Remarks

See also

PanelTitleBackgroundImage

Remarks

PanelTitleBackgroundImageTransparentColor

Remarks

PanelTitleFont

PanelTitleForeColor

Remarks

See also

PanelTitleGradientBeginColor

Remarks

See also

PanelTitleGradientEndColor

See also

PanelTitleHoverColor

PanelTitleImage

Remarks

PanelTitleImageTransparentColor

Remarks

PanelTitleText

Remarks

See also

ReflectCurrentXPTheme

Remarks

ShouldPaintCornersAsRoundedRect

Remarks

UpArrowImage

Remarks

Example

See also

Methods

OnEnabledChanged