BinaryPanelBar

Initialises a new, empty BinaryPanelBar with the olive XP theme, a thin border and one large button shown.

Gets or sets whether the bar's chevron menu has a "Navigation Pane Options..." item, which opens a dialog for reordering the buttons and choosing which are available.

Gets or sets the texts of the bar's chevron menu, so that the menu can be translated.

Assigning a provider renames the items of the menu at once. Changing a text on the provider already assigned takes effect when the menu is next rebuilt, for example when a button is added; assign the provider again to apply it straight away.

navigation.AddShowNavigationOptionsMenuResourceProviderInstance = new PanelBarAddShowNavigationOptionsMenuResourceProvider
{
    ShowMoreButtonsText = "Mehr Schaltflächen anzeigen",
    ShowFewerButtonsText = "Weniger Schaltflächen anzeigen",
    NavigationPaneOptionsText = "Navigationsbereichsoptionen...",
    AddOrRemoveButtonsText = "Schaltflächen hinzufügen oder entfernen",
};

Gets the standard Windows border, which is always BorderStyle.None; assigned values are ignored.

Use ControlBorderStyle for the bar's border.

Gets or sets the border drawn round each button, and sets it on every button on the bar.

ControlBorderStyle sets the buttons' borders too; whichever is set last wins.

Gets or sets the colour at the bottom of the gradient on a button under the pointer.

Applies to every button on the bar at the time, and to buttons added later with AddBinaryPanelBarButton. Each button can also be given its own colour.

Gets or sets the other end of the gradient on the selected button while it is under the pointer.

Applies to every button on the bar at the time, and to buttons added later with AddBinaryPanelBarButton. Each button can also be given its own colour.

Gets or sets one end of the gradient on the selected button while it is under the pointer.

Applies to every button on the bar at the time, and to buttons added later with AddBinaryPanelBarButton. Each button can also be given its own colour.

Gets or sets the colour at the top of the gradient on a button under the pointer.

Applies to every button on the bar at the time, and to buttons added later with AddBinaryPanelBarButton. Each button can also be given its own colour.

Gets or sets the colour at the bottom of the gradient on the selected button.

Applies to every button on the bar at the time, and to buttons added later with AddBinaryPanelBarButton. Each button can also be given its own colour.

Gets or sets the colour at the top of the gradient on the selected button.

Applies to every button on the bar at the time, and to buttons added later with AddBinaryPanelBarButton. Each button can also be given its own colour.

Gets or sets the colour of the collapse and expand arrow in the header strip.

Gets or sets the colour of the built-in chevron on the button that opens the bar's menu.

Setting the colour redraws the built-in chevron and puts it on the button, replacing a CustomChevronImage.

Gets or sets the border drawn round the whole bar, and sets the same border on every button.

Gets or sets whether the bar is collapsed to a narrow rail at its docked edge.

Collapsed, the bar keeps its height and shrinks to a rail showing the selected button's text, reading upwards. Clicking the rail opens the selected button's panel in a flyout beside it; expanding puts the bar back to the width it had when it collapsed.

Has no effect unless RenderInOutlookStyleExpandCollapseMode is true, which is also what puts the collapse button in the header. A request to collapse while that is off is ignored and this stays false. Nor does it collapse a bar whose Control.Dock is DockStyle.Fill: the header button refuses one, since a bar that fills its container has nowhere to give the width back to.

Setting it does not raise AboutToCollapseOrExpand or CollapseExpandButtonClicked; those report the user's click on the header button. This is runtime state, so the designer neither shows nor serialises it.

Gets the button most recently selected – by the user, from code, or automatically when the bar loads.

Unlike SelectedButton, this keeps its value when the button is deselected with DeSelectBinaryPanelBarButton().

Gets or sets a picture of your own for the chevron button at the right of the icon strip, which opens the bar's menu.

Gets or sets the colour made transparent in CustomChevronImage.

The colour is applied to the bitmap itself when this property is set, and only when a CustomChevronImage has already been assigned – so set the image first.

Gets or sets the colour of the drop shadow.

Gets or sets how far the drop shadow reaches.

The depth is scaled with the display. Used only while ShouldDrawDropShadow is true.

Gets or sets how dark the drop shadow is where it is strongest, next to the bar.

Gets or sets the colour at the bottom of the header strip's gradient and, while XPThemeToEmulate is XPTheme.None, of every button's.

Gets or sets the colour of the gripper band above the stack of buttons, which the user drags to show more or fewer buttons.

Used only while XPThemeToEmulate is XPTheme.None; each XP theme has a gripper colour of its own.

Gets or sets the height of the gripper band above the stack of buttons.

Gets or sets how many buttons are shown as large buttons in the stack; the others appear as small icons in the strip under it.

Setting the property shows the first value buttons in Items and hides the rest, counting unavailable buttons too. The user changes the number with the gripper or the chevron menu without changing this property.

Gets or sets how the buttons and the header are filled: a plain gradient, an Office-style two-tone finish, or the system's colours.

Setting the property sets the same style on every button on the bar. PanelBarItemColorRenderingStyle.WindowsOSThemeSettings also sets XPThemeToEmulate to XPTheme.None and takes the colours from the system, using the highlight colour under high contrast.

Gets a new list of the section buttons on the bar.

The positions the index-based methods take are positions in this list.

Gets or sets the space between the left edge of the header strip and its text.

Gets or sets the height of the header strip at the top of the bar.

Gets or sets the colour of the text in the header strip.

With PanelBarItemColorRenderingStyle.WindowsOSThemeSettings under high contrast the text is always SystemColors.WindowText.

Gets or sets the font of the text in the header strip.

Unless MainHeaderHeight is set, the strip's height follows the font.

Gets or sets a border colour for the checked buttons listed under the chevron menu's "Add or Remove Buttons".

The menu is drawn by Windows Forms' own renderer, which does not use this colour. Setting it rebuilds the menu and applies XPThemeToEmulate again, which raises XpThemeChanging and XpThemeChanged.

Gets or sets a highlight colour for the items of the bar's chevron menu.

The menu is drawn by Windows Forms' own renderer, which does not use this colour. Setting it rebuilds the menu and applies XPThemeToEmulate again, which raises XpThemeChanging and XpThemeChanged.

Gets a new list of every BinaryPanelBarButton among the bar's child controls.

The list includes the button that forms the bar's own icon strip. For only the section buttons you added, use Items.

Gets or sets the background of the collapsed rail while the flyout showing the selected page is open.

Gets or sets the background of the collapsed rail while the flyout is closed.

Takes effect the next time the rail is drawn.

Gets or sets the colour of the text written up the collapsed rail.

Takes effect the next time the rail is drawn.

Gets or sets the text in the bar's header strip.

Selecting a button replaces the text with that button's, so set this property to show a different title only until the next selection. The text is drawn in MainHeaderTextFont and MainHeaderTextColor, on one line, trimmed with an ellipsis; it is hidden while the bar is collapsed.

Gets or sets the font of the selected button's text written up the collapsed rail.

Takes effect the next time the rail is drawn.

Gets or sets the text shown up the collapsed rail while the user drags the gripper.

Gets or sets whether the bar chooses its XPThemeToEmulate from the Windows visual style when its window is created.

Not applied while XPThemeToEmulate is XPTheme.None. The mapping is the one UpdateWhenSystemColorsChanges describes: outside Windows XP's Olive Green and Silver styles the bar is drawn XPTheme.Blue.

Gets or sets whether the header strip has an arrow that collapses the bar to a narrow rail, as Outlook's navigation pane does.

Clicking the arrow collapses or expands the bar (ControlInCollapsedMode). The arrow is not shown while the bar's Control.Dock is DockStyle.Fill. Turning the property off while the bar is collapsed expands it first.

navigation.Dock = DockStyle.Left;
navigation.RenderInOutlookStyleExpandCollapseMode = true;
navigation.CollapseExpandButtonColor = Color.Navy;
navigation.AboutToCollapseOrExpand += (s, e) =>
    e.ShouldCancel = !e.IsAboutToExpand && composeWindowIsDocked;   // keep the pane open

Gets the selected button – the one whose page the bar is showing.

Gets or sets whether the bar takes the keyboard focus back when the flyout opened from the collapsed rail closes.

Useful when the bar is on a tool window, which otherwise loses the focus when the flyout closes.

Gets or sets whether a soft shadow is drawn along the bar's bottom and right edges.

A control cannot paint outside its own bounds, so the shadow is drawn in a band DropShadowDepth deep inside the bar's bottom and right edges, and the header, buttons and pages shrink by that much. The part of the band the shadow does not cover is painted in the nearest opaque parent's Control.BackColor.

Gets or sets the size of the bar, keeping the collapsed state consistent with it.

A new width is remembered as the width to expand to, except a rail-wide width set while the bar is collapsed. Assigning Control.Width or Size through a Control reference bypasses this.

Gets or sets the colour at the top of the header strip's gradient and, while XPThemeToEmulate is XPTheme.None, of every button's.

Setting the colour sets it on every button on the bar and redraws them. Assign it after XPThemeToEmulate, which replaces it.

Gets or sets the space between the top edge of the header strip and its text area.

The text is centred vertically in the area below the margin.

Gets or sets whether the bar follows the Windows visual style, choosing its XPThemeToEmulate from it now and whenever the system colours change.

The XP Olive Green style gives XPTheme.Olive, the XP Silver style XPTheme.Silver, and every other style – including those of later Windows versions – XPTheme.Blue. Turning this on applies the theme at once, replacing XPTheme.None and colours of your own.

Gets or sets whether the buttons are filled with one flat colour, StartColor, rather than a gradient.

Setting it to true works only while XPThemeToEmulate is XPTheme.None, and does it by copying StartColor into EndColor. Setting it to false puts back the EndColor remembered then – white, if it was never set to true.

Gets or sets whether clicking a button's small icon in the strip under the stack also raises the button's own Control.Click event, as clicking the large button does.

Setting this property sets BinaryPanelBarButton.WirePanelBarButtonClickEventToBaseBarButton on every button on the bar at that moment. Clicking the icon selects the button either way.

Gets or sets the Windows XP palette the bar and its buttons are drawn in.

Assigning a theme raises XpThemeChanging, which can cancel it, applies the theme to every button, the icon strip and the gripper, sets StartColor and EndColor to the theme's pair of colours, and raises XpThemeChanged.

XPTheme.None draws the buttons with StartColor and EndColor instead. Choosing it leaves those two as they are, so set them after it.

// Corporate colours rather than an XP palette.
navigation.XPThemeToEmulate = XPTheme.None;
navigation.StartColor = Color.FromArgb(0, 84, 147);
navigation.EndColor = Color.FromArgb(214, 230, 245);
navigation.GripperColor = Color.FromArgb(0, 84, 147);

Adds a section button to the bar, giving it the bar's theme, rendering style and button colours.

The button joins the stack as a large button while fewer than HowManyPanelButtonsToShow are showing, and otherwise as an icon in the strip. Adding a button selects the bar's first button again.

Adding the button through Control.Controls also works, but does not give it the bar's rendering style and button colours.

var tasks = new BinaryPanelBarButton(navigation)
{
    ButtonText = "Tasks",
    ButtonImage = new Bitmap("Images\\tasks-24.png"),
    ContainedPanel = tasksPage,
};
navigation.AddBinaryPanelBarButton(tasks);

Draws a button as not selected.

No other button is selected in its place, the page shown does not change and no event is raised.

Draws the button at a position in Items as not selected.

Releases the resources the bar uses.

Returns the button in the stack at a point.

The visible button whose bounds contain the point, or null when there is none there. Buttons shown only as icons in the strip under the stack are not returned.

Returns the section button at a position in Items.

The button, or null when index is outside the list.

Makes every button on the bar available.

Makes the given buttons available and every other button unavailable, for example to match the sections a user's role allows.

Each change goes through BinaryPanelBarButton.NotAvailableForUse, so BinaryPanelBarButtonNotAvailableForUseChanging can refuse it.

if (!currentUser.IsManager)
    navigation.MakeAvailableForUseOnlyTheSpecifiedBinaryPanelBarButtons(
        new ArrayList { mailButton, calendarButton });

Makes every button on the bar unavailable, hiding them all from the stack and the icon strip.

Moves a button one place later among the bar's child controls, which sets the order the buttons are stacked and listed in.

The index counts the bar's child controls, which include the bar's own header, gripper and icon strip and the buttons' pages as well as the buttons, so a move that lands next to one of those does not change the order of the buttons on screen. Errors, such as a button not on the bar, are ignored.

Moves a button one place earlier among the bar's child controls, which sets the order the buttons are stacked and listed in.

The index counts the bar's child controls, which include the bar's own header, gripper and icon strip and the buttons' pages as well as the buttons, so a move that lands next to one of those does not change the order of the buttons on screen. Errors, such as a button not on the bar, are ignored.

Raises the Control.DockChanged event, and removes the header's collapse arrow while the bar fills a form: a bar docked to fill has no width to give back.

Raises the Control.HandleCreated event, then sizes the header and the icon strip for the display, and applies the system's theme when ReflectCurrentXPThemeColorOnLoad is on.

Raises the Control.MouseDown event. In the designer, a click on a button selects that button for editing first.

Raises the Control.Paint event, then draws the border that ControlBorderStyle chooses.

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

Raises the Control.Resize event, then redraws the header, the gripper, the icon strip and the buttons for the new size, keeping the selected button selected.

Raises the Control.SizeChanged event, and lays out the icon strip and the shadow for the new size.

Raises the Control.SystemColorsChanged event, and applies the system's theme again when UpdateWhenSystemColorsChanges is on.

Removes a section button from the bar.

The button is not disposed, and its page stays among the bar's child controls; remove or dispose them yourself when they are no longer needed.

Removes the section button at a position in Items.

The button is not disposed.

Makes one button available or unavailable.

Does the same as setting the button's BinaryPanelBarButton.NotAvailableForUse.

Moves a button to a given position among the bar's child controls.

The index counts the bar's child controls, which include the bar's own header, gripper and icon strip and the buttons' pages as well as the buttons, so a move that lands next to one of those does not change the order of the buttons on screen. Errors, such as a button not on the bar, are ignored.

Selects the button at a position in Items, as a click on it would.

The button's page is shown, its text goes into the header, and the button's Control.Click event and the bar's BinaryPanelBarButtonClicked are raised.

Selects a button, as a click on it would.

The button's page is shown, its text goes into the header, and the button's Control.Click event and the bar's BinaryPanelBarButtonClicked are raised.

// Open the Calendar section when a reminder is clicked.
reminderLink.Click += (s, e) => navigation.SelectBinaryPanelBarButton(calendarButton);

Shows the given buttons as large buttons in the stack and moves every other button to the icon strip.

HowManyPanelButtonsToShow is not changed.

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

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

Occurs when the header strip is clicked while collapsing is on, before the bar collapses or expands; the handler can cancel it.

PanelBarAboutToCollapseOrExpandEventArgs.IsAboutToExpand says which way the bar would go; set PanelBarAboutToCollapseOrExpandEventArgs.ShouldCancel to leave it as it is.

The event is raised for a click anywhere on the header, before the bar checks whether the click was on the arrow, so it can occur without the bar then changing. Setting ControlInCollapsedMode from code does not raise it.

Occurs when a button becomes the selected one – clicked in the stack, clicked as an icon in the strip, or selected from code.

The sender is the BinaryPanelBarButton. By the time the event is raised, the button's page is showing and its text is in the header.

navigation.BinaryPanelBarButtonClicked += (sender, e) =>
{
    var section = (BinaryPanelBarButton)sender;
    Text = "Mail - " + section.ButtonText;
};

Occurs when a page is given to a button already on the bar, through BinaryPanelBarButton.ContainedPanel.

The sender is the button.

Occurs when a button's BinaryPanelBarButton.ButtonImage or BinaryPanelBarButton.ButtonSmallImage changes.

The sender is the button; the EventArgs argument is EventArgs.Empty.

Occurs after a button has been made available or unavailable.

The sender is the BinaryPanelBarButton.

Occurs before a button is made available or unavailable, whether by code, the "Add or Remove Buttons" menu or the options dialog; the handler can refuse the change.

The sender is the BinaryPanelBarButton.

Occurs when a button's BinaryPanelBarButton.ButtonText changes.

The sender is the button; the EventArgs argument is EventArgs.Empty.

Occurs when a button moves between the stack and the icon strip, or is hidden – when its Control.Visible changes.

The sender is the button.

Occurs after the user has collapsed or expanded the bar with the arrow in the header strip.

PanelBarCollapseExpandEventArgs.IsExpanded gives the new state. Setting ControlInCollapsedMode from code does not raise the event.

Occurs when the user chooses "Navigation Pane Options..." from the chevron menu, before the built-in dialog opens.

The menu item is there only while AddShowNavigationOptionsMenuItem is on. Set PanelBarNavigationOptions.CancelTheEvent to show your own dialog instead; the built-in one lets the user reorder the buttons and choose which are available.

Occurs repeatedly while the user drags the gripper above the stack, before each step that shows or hides a button; the handler can cancel the step.

Dragging down hides the lowest-placed large button; dragging up shows a hidden one.

Occurs when the user chooses "Show Fewer Buttons" from the chevron menu, before a button moves from the stack to the icon strip; the handler can cancel it.

Occurs when the user chooses "Show More Buttons" from the chevron menu, before a button moves from the icon strip to the stack; the handler can cancel it.

Occurs after XPThemeToEmulate has been applied.

The handler receives the theme in use before the assignment and the theme just applied.

Occurs before XPThemeToEmulate is applied; the handler can keep the current theme.

Raised on every assignment, even of the theme already in use – which includes setting MenuItemSelectionBackgroundColor or MenuItemAvailableButtonCheckedStateBorderColor, which apply the theme again.