WinForms › Explorer Bar › BinaryExplorerBar

BinaryExplorerBar

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

A vertical bar of titled, collapsible panels – the task pane down the side of Windows XP Explorer – for grouping the commands, links and details that go with the main content of a window.

public partial class BinaryExplorerBar : Panel, IBinaryControlExtendedServices

Inherits from / implements: Panel, IBinaryControlExtendedServices

Remarks

What it is for

Use the bar where an application wants a side pane of related groups – "File and Folder Tasks", "Other Places", "Details" – each of which the user can open and close with a click on its title. The bar stacks the groups one under the other, scrolls when they do not fit, and animates them as they open and close.

Key concepts

Panels. Each group is a BinaryExplorerBarPanel: a real, scrolling container for your own controls. Add panels through Panels; the bar places them, one under another, in the order of the collection. Controls added directly to the bar rather than to a panel are removed when it next lays itself out.
Titles. The title bar above each panel is drawn by the bar, not by the panel. Clicking it expands or collapses that panel alone, after BinaryExplorerBarPanelTitleClicked has had the chance to refuse. Each panel opens and closes independently; any number can be open at once.
Defaults and overrides. The DefaultPanel... properties of the bar give every panel title its font, colours, border and shadow. A panel uses its own value instead wherever it has one set – an empty colour means "use the bar's".
Resizing. While IsPanelResizable is on, the user can drag the line under an expanded panel to make it taller or shorter.

How to use it

Create the panels, give each a BinaryExplorerBarPanel.PanelTitleText and an expanded height (BinaryExplorerBarPanel.CurrentHeight), put your controls on them, and add them to Panels. Open and close panels from code with BinaryExplorerBarPanel.CurrentExplorerBarPanelState, ResetThisPanelState or ResetAllPanelsState.

Appearance

Colour the bar yourself through GradientBeginColor, GradientEndColor, BackgroundStyle and the DefaultPanel... properties, or let it imitate one of the Windows XP colour schemes: set ThemeOrCustomColors to ThemeOrCustomColors.PreDefinedTheme and choose an XPTheme. ShadowDepth and DefaultPanelShadowDepth add soft shadows under the bar and under each panel. Margins and depths are in logical pixels (1/96 inch) and are scaled with the display.

Examples

An Explorer-style task pane with three groups, in the XP blue scheme.

using System.Drawing;
using System.Windows.Forms;
using Binarymission.WinForms.Controls.NavigationControls;

public class DocumentsForm : Form
{
    private readonly BinaryExplorerBarPanel detailsPanel;

    public DocumentsForm()
    {
        Text = "Documents";
        Size = new Size(820, 560);

        var bar = new BinaryExplorerBar
        {
            Dock = DockStyle.Left,
            Width = 230,
            ThemeOrCustomColors = ThemeOrCustomColors.PreDefinedTheme,
            DefaultPanelBorderColor = Color.SteelBlue,
            DefaultPanelShadowDepth = 3,
        };

        var fileTasks = new BinaryExplorerBarPanel { PanelTitleText = "File and Folder Tasks", CurrentHeight = 90 };
        AddLink(fileTasks, "Rename this file", 8);
        AddLink(fileTasks, "Move this file", 32);
        AddLink(fileTasks, "E-mail this file", 56);

        var otherPlaces = new BinaryExplorerBarPanel { PanelTitleText = "Other Places", CurrentHeight = 66 };
        AddLink(otherPlaces, "Shared Documents", 8);
        AddLink(otherPlaces, "Network Places", 32);

        detailsPanel = new BinaryExplorerBarPanel
        {
            PanelTitleText = "Details",
            CurrentHeight = 60,
            CurrentExplorerBarPanelState = BinaryExplorerBarPanelState.Collapsed,   // starts closed
        };
        detailsPanel.Controls.Add(new Label { Text = "Quarterly report.xlsx\r\n48 KB", Location = new Point(8, 8), AutoSize = true });

        bar.Panels.AddRange(new[] { fileTasks, otherPlaces, detailsPanel });
        bar.XPTheme = XPTheme.Blue;   // after ThemeOrCustomColors, and after the panels so they are themed too

        bar.BinaryExplorerBarPanelTitleClicked += (sender, panel) => true;   // return false to refuse a click
        Controls.Add(bar);
    }

    private static void AddLink(BinaryExplorerBarPanel panel, string text, int top)
    {
        panel.Controls.Add(new LinkLabel { Text = text, Location = new Point(8, top), AutoSize = true });
    }
}

Members at a glance

Constructors
`BinaryExplorerBar`	Initialises a new, empty `BinaryExplorerBar` with the green default colours, scrolling switched on and resizable panels.
Properties
`BackColor`	Gets or sets the colour of the bar behind its panels.
`BackgroundStyle`	Gets or sets whether the bar's background is a gradient or plain `BackColor`.
`CollapseExpandAnimationInterval`	Gets or sets the pause between the steps of the open and close animation – the larger it is, the slower panels open and close.
`DefaultPanelBorderColor`	Gets or sets the colour of the one-pixel border drawn round each panel and its title, for every panel that has no `BinaryExplorerBarPanel.PanelBorderColor` of its own.
`DefaultPanelBottomMargin`	Gets or sets the space left under the last panel.
`DefaultPanelLeftMargin`	Gets or sets the space between the left edge of the bar and the panels.
`DefaultPanelRightMargin`	Gets or sets the space between the panels and the right edge of the bar.
`DefaultPanelShadowColor`	Gets or sets the colour of the shadow under each panel, for every panel that has no `BinaryExplorerBarPanel.PanelShadowColor` of its own.
`DefaultPanelShadowDepth`	Gets or sets how far the soft shadow under each panel reaches, for every panel whose `BinaryExplorerBarPanel.PanelShadowDepth` is -1.
`DefaultPanelTitleBackColor`	Gets or sets the solid colour of the panel titles, for every panel that has no `BinaryExplorerBarPanel.PanelTitleBackColor` of its own.
`DefaultPanelTitleBackgroundImage`	Gets or sets the picture drawn as the title of every panel that has `ControlBackgroundPaintingStyle.ImageStyle` as its `BinaryExplorerBarPanel.PanelTitleBackStyle` but no `BinaryExplorerBarPanel.PanelTitleBackgroundImage` of its own.
`DefaultPanelTitleBackgroundImageTransparentColor`	Gets or sets the colour made transparent in `DefaultPanelTitleBackgroundImage`.
`DefaultPanelTitleFont`	Gets or sets the font of the panel titles, for every panel that has no `BinaryExplorerBarPanel.PanelTitleFont` of its own.
`DefaultPanelTitleForeColor`	Gets or sets the colour of the title text, for every panel that has no `BinaryExplorerBarPanel.PanelTitleForeColor` of its own.
`DefaultPanelTitleGradientBeginColor`	Gets or sets the colour at the left of each panel title's gradient, for every panel that has no `BinaryExplorerBarPanel.PanelTitleGradientBeginColor` of its own.
`DefaultPanelTitleGradientEndColor`	Gets or sets the colour at the right of each panel title's gradient, for every panel that has no `BinaryExplorerBarPanel.PanelTitleGradientEndColor` of its own.
`DefaultPanelTitleHoverColor`	Gets or sets the colour of the title text while the pointer is over a title, for every panel that has no `BinaryExplorerBarPanel.PanelTitleHoverColor` of its own.
`DefaultPanelTopMargin`	Gets or sets the space above each panel's title – between the top of the bar and the first panel, and between one panel and the next.
`GradientBeginColor`	Gets or sets the colour at the left edge of the bar's background gradient.
`GradientEndColor`	Gets or sets the colour at the right edge of the bar's background gradient.
`IsPanelResizable`	Gets or sets whether the user can drag the line under an expanded panel to change its height.
`OnHoverUpDownArrowColor`	Gets or sets the bar-level setting for the colour of the arrow and outline of the expand and collapse button while the pointer is over the panel's title.
`OnHoverUpDownArrowEllipseFillColor`	Gets or sets the bar-level setting for the fill of the expand and collapse button while the pointer is over the panel's title.
`OnNormalUpDownArrowColor`	Gets or sets the bar-level setting for the colour of the arrow and outline of the expand and collapse button.
`OnNormalUpDownArrowEllipseFillColor`	Gets or sets the bar-level setting for the fill of the round expand and collapse button at the right of a panel's title.
`Panels`	Gets the panels the bar shows, in order from top to bottom.
`PerformAnimation`	Gets or sets whether a panel opens and closes gradually when the user clicks its title, rather than all at once.
`ReflectCurrentXPTheme`	Gets or sets whether the bar follows the colour scheme of the current Windows visual style, as Windows XP Explorer does.
`ShadowColor`	Gets or sets the colour of the bar's own drop shadow.
`ShadowDepth`	Gets or sets how far the soft shadow along the bar's own right and bottom edges reaches.
`ShouldPaintPanelItemCornersAsRoundedRect`	Gets or sets whether the top corners of every panel's title are drawn rounded, and sets the same choice on each panel.
`ThemeOrCustomColors`	Gets or sets whether the bar takes its colours from a predefined Windows XP colour scheme (`XPTheme`) or from its own colour properties.
`XPTheme`	Gets or sets the Windows XP colour scheme the bar and its panels imitate.
Methods
`EmulateThisXPTheme`	Applies the colours of a Windows XP colour scheme to the bar and its panels, while the bar is following the system's visual style.
`OnControlRemoved`	Removes a `BinaryExplorerBarPanel` from `Panels` when it is removed from the bar's `Control.Controls`, then raises the `Control.ControlRemoved` event.
`OnHandleCreated`	Raises the `Control.HandleCreated` event, and applies the system's colour scheme when `ReflectCurrentXPTheme` is on.
`OnMouseDown`	Raises the `Control.MouseDown` event, and starts a resize when the left button goes down on the line under a panel.
`OnMouseEnter`	Raises the `Control.MouseEnter` event, and highlights the title the pointer enters on.
`OnMouseLeave`	Raises the `Control.MouseLeave` event, and removes the hover highlight from the titles.
`OnMouseMove`	Raises the `Control.MouseMove` event, then highlights the title under the pointer, shows the hand or sizing cursor, and resizes a panel while the user drags the line under it.
`OnMouseUp`	Raises the `Control.MouseUp` event, then ends a resize, or – on a left click on a title – raises `BinaryExplorerBarPanelTitleClicked` and expands or collapses the panel.
`OnMouseWheel`	Raises the `Control.MouseWheel` event, which scrolls the bar, and repaints it.
`OnPaint`	Raises the `Control.Paint` event, then paints the background gradient and every panel's title, border and shadow over it.
`OnParentBackColorChanged`	Raises the `Control.ParentBackColorChanged` event, and repaints the shadow band, which is filled with the colour behind the bar.
`OnScroll`	Raises the `ScrollableControl.Scroll` event and repaints the whole bar.
`OnSizeChanged`	Raises the `Control.SizeChanged` event, then lays the panels out for the new size and repaints the shadow band.
`OnSystemColorsChanged`	Raises the `Control.SystemColorsChanged` event, and applies the system's colour scheme again when `ReflectCurrentXPTheme` is on.
`OnVisibleChanged`	Raises the `Control.VisibleChanged` event, and lays the panels out again when the bar is shown.
`ResetAllPanelsState`	Expands or collapses every enabled panel at once.
`ResetThisPanelState`	Expands or collapses one panel, chosen by its position in `Panels`.
`WndProc`	Processes the window messages, keeping a band along the right and bottom edges for the bar's own drop shadow and painting the shadow into it.
Events
`BinaryExplorerBarPanelTitleClicked`	Occurs when the user clicks a panel's title, before the panel expands or collapses; the handler's return value decides whether it does.

Constructors

BinaryExplorerBar

public BinaryExplorerBar()

Initialises a new, empty BinaryExplorerBar with the green default colours, scrolling switched on and resizable panels.

Properties

BackColor

public override Color BackColor

Gets or sets the colour of the bar behind its panels.

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

Remarks

In the ControlBackgroundPaintingStyle.GradientColorStyle background style (the default) a gradient is painted over this colour, and shows through only where GradientEndColor is transparent. The colour is also used for the part of the shadow band the shadow does not cover when the bar's parent is transparent. Choosing an XPTheme replaces it.

BackgroundStyle

public ControlBackgroundPaintingStyle BackgroundStyle

Gets or sets whether the bar's background is a gradient or plain BackColor.

Value: The default is ControlBackgroundPaintingStyle.GradientColorStyle: a gradient from GradientBeginColor at the left to GradientEndColor at the right.
Default: GradientStyle
Designer category: Styles

Remarks

With ControlBackgroundPaintingStyle.SolidBrushColorStyle or ControlBackgroundPaintingStyle.ImageStyle the bar shows its ordinary BackColor and Control.BackgroundImage.

Setting the property does not repaint the bar; call Control.Invalidate afterwards. The choice also decides which colours an XPTheme sets.

CollapseExpandAnimationInterval

public int CollapseExpandAnimationInterval

Gets or sets the pause between the steps of the open and close animation – the larger it is, the slower panels open and close.

Value: The pause in milliseconds. The default is 5.
Default: 5
Designer category: Animation Properties

Remarks

The panel grows or shrinks by 10 pixels per step, so a panel 100 pixels high takes about ten steps. The animation runs to completion before the click returns.

DefaultPanelBorderColor

public Color DefaultPanelBorderColor

Gets or sets the colour of the one-pixel border drawn round each panel and its title, for every panel that has no BinaryExplorerBarPanel.PanelBorderColor of its own.

Value: The default is Color.Empty: no border.
Designer category: Default Child panel properties

Remarks

The border encloses the title and the panel's body together – just the title while the panel is collapsed – and is drawn one pixel outside the panel, in the bar's left and right margins.

DefaultPanelBottomMargin

public int DefaultPanelBottomMargin

Gets or sets the space left under the last panel.

Value: The space in logical pixels (1/96 inch). The default is 15. Negative values are ignored.
Default: 15
Designer category: Drawing margins

Remarks

The space keeps the last panel from looking cut off and leaves room for its shadow. It is part of the scrollable area, so it appears at the end of the scroll rather than being taken from the panels.

DefaultPanelLeftMargin

public int DefaultPanelLeftMargin

Gets or sets the space between the left edge of the bar and the panels.

Value: The space in logical pixels (1/96 inch). The default is 12.
Default: 12
Designer category: Drawing margins

Remarks

Panel borders and shadows are drawn in this margin and the right one, so keep the margins at least as wide as DefaultPanelShadowDepth.

DefaultPanelRightMargin

public int DefaultPanelRightMargin

Gets or sets the space between the panels and the right edge of the bar.

Value: The space in logical pixels (1/96 inch). The default is 12.
Default: 12
Designer category: Drawing margins

Remarks

The panels are made a few pixels narrower again while the vertical scroll bar is showing.

DefaultPanelShadowColor

public Color DefaultPanelShadowColor

Gets or sets the colour of the shadow under each panel, for every panel that has no BinaryExplorerBarPanel.PanelShadowColor of its own.

Value: The default is Color.Empty, which draws a soft black shadow.
Designer category: Default Child panel properties

Remarks

The colour's alpha sets how dark the shadow is, as for ShadowColor.

DefaultPanelShadowDepth

public int DefaultPanelShadowDepth

Gets or sets how far the soft shadow under each panel reaches, for every panel whose BinaryExplorerBarPanel.PanelShadowDepth is -1.

Value: The depth in logical pixels (1/96 inch). The default is 0: no shadow. Negative values are ignored.
Default: 0
Designer category: Default Child panel properties

Remarks

The shadow is drawn in the bar's margins round the panel, where its border is, so keep DefaultPanelLeftMargin and DefaultPanelRightMargin at least as wide as the shadow is deep – they are 12 logical pixels by default.

DefaultPanelTitleBackColor

public Color DefaultPanelTitleBackColor

Gets or sets the solid colour of the panel titles, for every panel that has no BinaryExplorerBarPanel.PanelTitleBackColor of its own.

Value: The default is Color.RoyalBlue.
Designer category: Default Child panel properties

Remarks

Used only for panels whose BinaryExplorerBarPanel.BackgroundPaintingStyleForControlTitle is not ControlBackgroundPaintingStyle.GradientColorStyle. Setting it does not repaint the titles.

DefaultPanelTitleBackgroundImage

public Bitmap DefaultPanelTitleBackgroundImage

Gets or sets the picture drawn as the title of every panel that has ControlBackgroundPaintingStyle.ImageStyle as its BinaryExplorerBarPanel.PanelTitleBackStyle but no BinaryExplorerBarPanel.PanelTitleBackgroundImage of its own.

Value: The default is null.
Default: null
Designer category: Default Child panel properties

Remarks

The picture is stretched to fill the title. When DefaultPanelTitleBackgroundImageTransparentColor is already set, the pixels of that colour are made transparent in the bitmap you assign – the bitmap itself is changed.

DefaultPanelTitleBackgroundImageTransparentColor

public Color DefaultPanelTitleBackgroundImageTransparentColor

Gets or sets the colour made transparent in DefaultPanelTitleBackgroundImage.

Value: The default is Color.Empty: no colour is made transparent.
Designer category: Default Child panel 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.

DefaultPanelTitleFont

public Font DefaultPanelTitleFont

Gets or sets the font of the panel titles, for every panel that has no BinaryExplorerBarPanel.PanelTitleFont of its own.

Value: The default is the bar's Control.Font.
Default: null
Designer category: Default Child panel properties

Remarks

Setting a new font does not repaint the titles; call Control.Invalidate afterwards when the bar is already showing.

DefaultPanelTitleForeColor

public Color DefaultPanelTitleForeColor

Gets or sets the colour of the title text, for every panel that has no BinaryExplorerBarPanel.PanelTitleForeColor of its own.

Value: The default is Color.Green.
Designer category: Default Child panel properties

Remarks

A disabled panel's title is always drawn in SystemColors.GrayText. Setting the colour does not repaint the titles.

DefaultPanelTitleGradientBeginColor

public Color DefaultPanelTitleGradientBeginColor

Gets or sets the colour at the left of each panel title's gradient, for every panel that has no BinaryExplorerBarPanel.PanelTitleGradientBeginColor of its own.

Value: The default is Color.White.
Designer category: Default Child panel properties

Remarks

Used for panels whose BinaryExplorerBarPanel.BackgroundPaintingStyleForControlTitle is ControlBackgroundPaintingStyle.GradientColorStyle, the default. Setting it does not repaint the titles.

DefaultPanelTitleGradientEndColor

public Color DefaultPanelTitleGradientEndColor

Gets or sets the colour at the right of each panel title's gradient, for every panel that has no BinaryExplorerBarPanel.PanelTitleGradientEndColor of its own.

Value: The default is RGB(115, 210, 134), a mid green.
Designer category: Default Child panel properties

Remarks

Setting it does not repaint the titles.

DefaultPanelTitleHoverColor

public Color DefaultPanelTitleHoverColor

Gets or sets the colour of the title text while the pointer is over a title, for every panel that has no BinaryExplorerBarPanel.PanelTitleHoverColor of its own.

Value: The default is Color.Empty: a lighter shade of the title's text colour.
Designer category: Default Child panel properties

DefaultPanelTopMargin

public int DefaultPanelTopMargin

Gets or sets the space above each panel's title – between the top of the bar and the first panel, and between one panel and the next.

Value: The space in logical pixels (1/96 inch). The default is 15.
Default: 15
Designer category: Drawing margins

Remarks

While IsPanelResizable is on, two more pixels are left under each panel for the line the user drags.

GradientBeginColor

public Color GradientBeginColor

Gets or sets the colour at the left edge of the bar's background gradient.

Value: The default is RGB(115, 210, 134), a mid green.
Designer category: Colors

Remarks

Used while BackgroundStyle is ControlBackgroundPaintingStyle.GradientColorStyle. Choosing an XPTheme replaces it.

GradientEndColor

public Color GradientEndColor

Gets or sets the colour at the right edge of the bar's background gradient.

Value: The default is Color.Transparent, so the gradient fades into BackColor.
Designer category: Colors

Remarks

Used while BackgroundStyle is ControlBackgroundPaintingStyle.GradientColorStyle. Choosing an XPTheme replaces it.

IsPanelResizable

public bool IsPanelResizable

Gets or sets whether the user can drag the line under an expanded panel to change its height.

Value: true to allow resizing. The default is true.
Default: true
Designer category: General flags

Remarks

The pointer becomes a sizing cursor over the two pixels just under an expanded panel. Dragging makes that panel taller or shorter – no shorter than 10 logical pixels – and the expanded panel below it gives up or gains the same height. The new height is kept as the panel's BinaryExplorerBarPanel.CurrentHeight.

While resizing is allowed, two pixels more are left between panels for the line.

OnHoverUpDownArrowColor

public Color OnHoverUpDownArrowColor

Gets or sets the bar-level setting for the colour of the arrow and outline of the expand and collapse button while the pointer is over the panel's title.

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

Remarks

Each panel draws its expand and collapse button with its own colours – the panel's BinaryExplorerBarPanel.OnNormalUpDownArrowColor, BinaryExplorerBarPanel.OnHoverUpDownArrowColor, BinaryExplorerBarPanel.OnNormalUpDownArrowEllipseFillColor and BinaryExplorerBarPanel.OnHoverUpDownArrowEllipseFillColor. The bar's property of the same name is not used to draw them: set the panels' properties to change the buttons. The XP themes set both.

OnHoverUpDownArrowEllipseFillColor

public Color OnHoverUpDownArrowEllipseFillColor

Gets or sets the bar-level setting for the fill of the expand and collapse button while the pointer is over the panel's title.

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

Remarks

OnNormalUpDownArrowColor

public Color OnNormalUpDownArrowColor

Gets or sets the bar-level setting for the colour of the arrow and outline of the expand and collapse button.

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

Remarks

OnNormalUpDownArrowEllipseFillColor

public Color OnNormalUpDownArrowEllipseFillColor

Gets or sets the bar-level setting for the fill of the round expand and collapse button at the right of a panel's title.

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

Remarks

Panels

public BinaryExplorerBarPanelCollection Panels

Gets the panels the bar shows, in order from top to bottom.

Value: The bar's BinaryExplorerBarPanelCollection. It starts empty.
Designer category: Collection Items

Remarks

Adding a panel to the collection adds it to the bar, lays the bar out again and applies the current XPTheme to it; removing a panel takes it off the bar. Use the collection's Add, AddRange, Insert, Remove and Clear methods, or the indexer to put one panel in place of another.

Assigning a collection replaces the bar's panels with the panels in it. The bar keeps its own collection, so later changes go through this property, not through the collection assigned.

Example

var shortcuts = new BinaryExplorerBarPanel { PanelTitleText = "Shortcuts", CurrentHeight = 120 };
shortcuts.Controls.Add(shortcutsList);
explorerBar.Panels.Insert(0, shortcuts);    // the new first group

PerformAnimation

public bool PerformAnimation

Gets or sets whether a panel opens and closes gradually when the user clicks its title, rather than all at once.

Value: true to animate. The default is true.
Default: true
Designer category: Animation Properties

Remarks

Only clicks on a title are animated; panels opened or closed from code change at once. The speed is set by CollapseExpandAnimationInterval.

ReflectCurrentXPTheme

public bool ReflectCurrentXPTheme

Gets or sets whether the bar follows the colour scheme of the current Windows visual style, as Windows XP Explorer does.

Value: true to follow the system. The default is false.

Remarks

While this is on, the bar applies the matching XPTheme colour scheme when it is set, when its handle is created, when a panel is added and when the system colours change: the XP Olive Green style gives XPTheme.OliveGreen, the XP Silver style gives XPTheme.Silver, and every other visual style – including those of later Windows versions – gives XPTheme.Blue.

The setting is passed on to every panel in Panels. While it is on, XPTheme cannot be set.

ShadowColor

public Color ShadowColor

Gets or sets the colour of the bar's own drop shadow.

Value: The default is Color.Empty, which draws a soft black shadow.
Designer category: General Control properties

Remarks

The colour's alpha sets how dark the shadow is: it is drawn at 60 per cent of the alpha next to the edge and fades to nothing. Used only while ShadowDepth is above 0.

ShadowDepth

public int ShadowDepth

Gets or sets how far the soft shadow along the bar's own right and bottom edges reaches.

Value: The depth in logical pixels (1/96 inch). The default is 0: no shadow. Negative values are ignored.
Default: 0
Designer category: General Control properties

Remarks

A control cannot paint outside its own bounds, so the shadow is drawn in a band along the bar's right and bottom edges, outside the scroll bars. The band is filled with the colour behind the bar – its nearest parent with a colour – and the bar's surface and its panels stop short of it. Leave the bar a few pixels of room in its parent's layout.

Example

explorerBar.ShadowDepth = 6;
explorerBar.ShadowColor = Color.FromArgb(160, 0, 0, 40);   // alpha sets the strength

ShouldPaintPanelItemCornersAsRoundedRect

public bool ShouldPaintPanelItemCornersAsRoundedRect

Gets or sets whether the top corners of every panel's title are drawn rounded, and sets the same choice on each panel.

Value: true for rounded corners. The default is false.
Default: false

Remarks

Setting this property sets BinaryExplorerBarPanel.ShouldPaintCornersAsRoundedRect on every panel in Panels at that moment; panels added later keep their own setting, which is rounded by default. Until the property is set, each panel's own setting applies.

ThemeOrCustomColors

public ThemeOrCustomColors ThemeOrCustomColors

Gets or sets whether the bar takes its colours from a predefined Windows XP colour scheme (XPTheme) or from its own colour properties.

Value: The default is ThemeOrCustomColors.CustomColors.

Remarks

XPTheme is ignored while this property is ThemeOrCustomColors.CustomColors, so set this property to ThemeOrCustomColors.PreDefinedTheme first and choose the theme after it. Setting this property to ThemeOrCustomColors.PreDefinedTheme resets XPTheme to XPTheme.None.

Neither applies while ReflectCurrentXPTheme is true.

XPTheme

public XPTheme XPTheme

Gets or sets the Windows XP colour scheme the bar and its panels imitate.

Value: The default is XPTheme.None: the bar's own colours.

Remarks

A theme is applied only while ThemeOrCustomColors is ThemeOrCustomColors.PreDefinedTheme and ReflectCurrentXPTheme is false; otherwise setting this property has no effect.

Choosing a theme sets the colours of the bar – BackColor, the gradient and the expand and collapse button colours – and of every panel: the title colours, the body colour and the button colours. Adding a panel applies the theme again, to every panel, so colours you set on a panel after choosing a theme last only until the next panel is added. The colours are close to Windows XP's but not identical.

Setting XPTheme.None keeps the colours the last theme set.

Example

explorerBar.ThemeOrCustomColors = ThemeOrCustomColors.PreDefinedTheme;
explorerBar.XPTheme = XPTheme.Silver;

Methods

EmulateThisXPTheme

public void EmulateThisXPTheme(XPTheme theTheme)

Applies the colours of a Windows XP colour scheme to the bar and its panels, while the bar is following the system's visual style.

Parameters

theTheme: The scheme to apply. XPTheme.None changes nothing.

Remarks

The method does nothing unless ReflectCurrentXPTheme is true. It lets an application apply a scheme other than the one the system reports; the bar applies the system's own scheme again when the system colours change. To choose a scheme of your own permanently, use ThemeOrCustomColors and XPTheme instead.

OnControlRemoved

protected override void OnControlRemoved(ControlEventArgs e)

Removes a BinaryExplorerBarPanel from Panels when it is removed from the bar's Control.Controls, then raises the Control.ControlRemoved event.

Parameters

e: The data for the event.

OnHandleCreated

protected override void OnHandleCreated(EventArgs e)

Raises the Control.HandleCreated event, and applies the system's colour scheme when ReflectCurrentXPTheme is on.

Parameters

e: The data for the event.

OnMouseDown

protected override void OnMouseDown(MouseEventArgs e)

Raises the Control.MouseDown event, and starts a resize when the left button goes down on the line under a panel.

Parameters

e: The data for the event.

OnMouseEnter

protected override void OnMouseEnter(EventArgs e)

Raises the Control.MouseEnter event, and highlights the title the pointer enters on.

Parameters

e: The data for the event.

OnMouseLeave

protected override void OnMouseLeave(EventArgs e)

Raises the Control.MouseLeave event, and removes the hover highlight from the titles.

Parameters

e: The data for the event.

OnMouseMove

protected override void OnMouseMove(MouseEventArgs e)

Raises the Control.MouseMove event, then highlights the title under the pointer, shows the hand or sizing cursor, and resizes a panel while the user drags the line under it.

Parameters

e: The data for the event.

Remarks

An override must call the base method, or the hover highlight and panel resizing stop working.

OnMouseUp

protected override void OnMouseUp(MouseEventArgs e)

Raises the Control.MouseUp event, then ends a resize, or – on a left click on a title – raises BinaryExplorerBarPanelTitleClicked and expands or collapses the panel.

Parameters

e: The data for the event.

OnMouseWheel

protected override void OnMouseWheel(MouseEventArgs e)

Raises the Control.MouseWheel event, which scrolls the bar, and repaints it.

Parameters

e: The data for the event.

Remarks

The wheel scrolls without raising ScrollableControl.Scroll, so it needs the same full repaint as OnScroll.

OnPaint

protected override void OnPaint(PaintEventArgs pe)

Raises the Control.Paint event, then paints the background gradient and every panel's title, border and shadow over it.

Parameters

pe: The data for the event.

Remarks

In the gradient BackgroundStyle the bar's own painting covers anything a Control.Paint handler draws.

OnParentBackColorChanged

protected override void OnParentBackColorChanged(EventArgs e)

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

Parameters

e: The data for the event.

OnScroll

protected override void OnScroll(ScrollEventArgs se)

Raises the ScrollableControl.Scroll event and repaints the whole bar.

Parameters

se: The data for the event.

Remarks

The panel borders and shadows are drawn in the margins round the panels and do not move with the scrolled content, so the bar is repainted in full on every scroll. The bar is double buffered, so this does not flicker.

OnSizeChanged

protected override void OnSizeChanged(EventArgs e)

Raises the Control.SizeChanged event, then lays the panels out for the new size and repaints the shadow band.

Parameters

e: The data for the event.

OnSystemColorsChanged

protected override void OnSystemColorsChanged(EventArgs e)

Raises the Control.SystemColorsChanged event, and applies the system's colour scheme again when ReflectCurrentXPTheme is on.

Parameters

e: The data for the event.

OnVisibleChanged

protected override void OnVisibleChanged(EventArgs e)

Raises the Control.VisibleChanged event, and lays the panels out again when the bar is shown.

Parameters

e: The data for the event.

ResetAllPanelsState

public void ResetAllPanelsState(BinaryExplorerBarPanelState state)

Expands or collapses every enabled panel at once.

Parameters

state: BinaryExplorerBarPanelState.Expanded to open the panels, BinaryExplorerBarPanelState.Collapsed to close them.

Remarks

The change is immediate, without animation, and does not raise BinaryExplorerBarPanelTitleClicked. Disabled panels are left as they are.

Example

// "Collapse all" and "Expand all" buttons above the task pane.
collapseAllButton.Click += (s, e) => explorerBar.ResetAllPanelsState(BinaryExplorerBarPanelState.Collapsed);
expandAllButton.Click += (s, e) => explorerBar.ResetAllPanelsState(BinaryExplorerBarPanelState.Expanded);

ResetThisPanelState

public void ResetThisPanelState(BinaryExplorerBarPanelState state, int panelIndex)

Expands or collapses one panel, chosen by its position in Panels.

Parameters

state: BinaryExplorerBarPanelState.Expanded to open the panel, BinaryExplorerBarPanelState.Collapsed to close it.
panelIndex: The zero-based index of the panel in Panels. An index outside the collection is ignored.

Remarks

The change is immediate, without animation, and does not raise BinaryExplorerBarPanelTitleClicked. A disabled panel is left as it is. Setting the panel's BinaryExplorerBarPanel.CurrentExplorerBarPanelState does the same.

WndProc

protected override void WndProc(ref Message m)

Processes the window messages, keeping a band along the right and bottom edges for the bar's own drop shadow and painting the shadow into it.

Parameters

m: The window message to process.

Remarks

An override must call the base method for every message, or the shadow is lost.

Events

BinaryExplorerBarPanelTitleClicked

public event BinaryExplorerBarPanelTitleClickedHandler BinaryExplorerBarPanelTitleClicked

Occurs when the user clicks a panel's title, before the panel expands or collapses; the handler's return value decides whether it does.

Remarks

The event is raised when the left mouse button is released over the title of an enabled panel, and not while a panel is still animating. Return false from the handler to leave the panel as it is. Panels opened or closed from code do not raise it.

With more than one handler attached, the value returned by the last one decides.

BinaryExplorerBar

Remarks

What it is for

Key concepts

How to use it

Appearance

Examples

See also

Members at a glance

Constructors

BinaryExplorerBar

Properties

BackColor

Remarks

See also

BackgroundStyle

Remarks

CollapseExpandAnimationInterval

Remarks

See also

DefaultPanelBorderColor

Remarks

See also

DefaultPanelBottomMargin

Remarks

See also

DefaultPanelLeftMargin

Remarks

See also

DefaultPanelRightMargin

Remarks

See also

DefaultPanelShadowColor

Remarks

DefaultPanelShadowDepth

Remarks

See also

DefaultPanelTitleBackColor

Remarks

DefaultPanelTitleBackgroundImage

Remarks

DefaultPanelTitleBackgroundImageTransparentColor

Remarks

DefaultPanelTitleFont

Remarks

DefaultPanelTitleForeColor

Remarks

See also

DefaultPanelTitleGradientBeginColor

Remarks

See also

DefaultPanelTitleGradientEndColor

Remarks

See also

DefaultPanelTitleHoverColor

See also

DefaultPanelTopMargin

Remarks

See also

GradientBeginColor

Remarks

See also

GradientEndColor

Remarks

See also

IsPanelResizable

Remarks

OnHoverUpDownArrowColor

Remarks

OnHoverUpDownArrowEllipseFillColor

Remarks

OnNormalUpDownArrowColor

Remarks

OnNormalUpDownArrowEllipseFillColor

Remarks

Panels

Remarks

Example

PerformAnimation

Remarks