BinaryHeaderControl

Initialises a new BinaryHeaderControl with the ColorScheme.Blue colour scheme, the caption across the top and the collapse button showing.

The caption and footer text are centred, on one line, and trimmed with an ellipsis when they do not fit. Both caption fonts follow the control's Control.Font until you set one.

Gets whether the client area scrolls; it never does.

To scroll the pane's content, add a BinaryScrollablePanel to the control and put the child controls on the panel. At run time the panel fills the client area and scrolls when its content is larger.

Gets or sets the direction in which the client area's background gradient runs.

Gets or sets the colour of the border drawn round the whole control.

While ColorScheme is anything other than ColorScheme.None, choosing a scheme and setting StartColorForHeaderRendering both overwrite this colour; set it after them.

Gets the standard Windows border style, which is always BorderStyle.None.

The control draws its own border; use BorderColor and BorderWidth to change it.

Gets or sets the thickness of the border drawn round the whole control.

The border is part of the frame, so a thicker border makes the client area smaller. Unlike the band heights, this width is not scaled with the display.

Gets or sets the built-in palette the caption, footer, background, border and context menu button are drawn in.

Choosing a scheme overwrites StartColorForHeaderRendering, EndColorForHeaderRendering, the background and footer gradient colours, BorderColor, ContextMenuEllipseColor and ContextMenuArrowColor. ColorScheme.None leaves them as they are: choose it when you set those colours yourself, and set it before them.

The scheme is passed on to every BinaryScrollablePanel the control hosts directly; other child controls are left as they are.

// A corporate palette of your own: switch the schemes off first, then set the colours.
ordersPane.ColorScheme = ColorScheme.None;
ordersPane.StartColorForHeaderRendering = Color.FromArgb(0, 84, 147);
ordersPane.EndColorForHeaderRendering = Color.FromArgb(96, 160, 214);
ordersPane.HeaderTextForeColor = Color.White;
ordersPane.BorderColor = Color.FromArgb(0, 84, 147);

Gets or sets the colour of the arrow inside the built-in context menu button.

Used while the built-in button is drawn: EnableHeaderContextMenu is on and no custom picture is in use (see UseCustomImageForContextMenuButton and ContextMenuImageType).

Gets or sets the colour of the round body of the built-in context menu button.

Used while the built-in button is drawn: EnableHeaderContextMenu is on and no custom picture is in use. Choosing a ColorScheme other than ColorScheme.None overwrites the colour.

Gets or sets which picture is drawn as the context menu button: the built-in round button, your icon or your bitmap.

Your own picture is used only while UseCustomImageForContextMenuButton is true.

Gets or sets which of the two menu properties the context menu button opens.

The two properties let an application keep two menus ready and switch between them, for example a short menu and a full one.

Gets or sets whether the control is expanded, as opposed to collapsed to its caption.

Reading the property tells you the current state, whether the user collapsed the control with the caption button or code called PerformCollapseExpand.

Setting it does not resize the control. It records the current height as the one an expand returns to, and redraws the collapse button for the new state. To collapse the control from code, call PerformCollapseExpand.

Gets or sets the colour in CustomImageForContextMenuButton that is made transparent, so that the caption shows through the picture's background.

The colour is applied to the bitmap itself, and only while UseCustomImageForContextMenuButton is true and a bitmap has been assigned. It has no effect on CustomIconForContextMenuButton.

Gets or sets the icon drawn as the context menu button when ContextMenuImageType is ContextMenuButtonImageType.Icon.

The icon is drawn 16 logical pixels square, and only while UseCustomImageForContextMenuButton is true.

Gets or sets the picture drawn as the context menu button when ContextMenuImageType is ContextMenuButtonImageType.Bitmap.

The picture is drawn 16 logical pixels square, and only while UseCustomImageForContextMenuButton is true.

When that property is already true, the pixels of CustomContextMenuButtonImageTransparencyColor are made transparent in the bitmap you assign – the bitmap itself is changed – so set UseCustomImageForContextMenuButton and the transparency colour first.

Gets the area available to the hosted controls, in client coordinates.

The caption, footer, border and shadow are all outside the client area, so docked and anchored children stop short of them with no margins of your own.

Gets or sets which bands – the caption, the footer, both or neither – have a border drawn just inside their edges.

The caption's border is drawn with HeaderBorderColor and HeaderBorderThickness, the footer's with FooterBorderColor and FooterBorderThickness. A footer border shows only while the footer is drawn.

Gets or sets whether a footer band is drawn along the edge opposite the caption.

The footer is part of the frame, so turning it on makes the client area smaller. No footer is drawn when HeaderLocation is HeaderLocation.Bottom.

FooterText ignores new text while this property is false, so turn the footer on first.

Gets or sets the colour of the drop shadow.

Used only while ShouldDrawDropShadow is true.

Gets or sets how far the drop shadow reaches beyond the frame.

The depth is scaled with the display. A depth of 0 draws no shadow and gives the band back to the client area. Used only while ShouldDrawDropShadow is true.

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

Used only while ShouldDrawDropShadow is true.

Gets or sets whether the caption shows a round button that collapses the control to its caption and expands it again.

The collapse button and the context menu button share one place at the end of the caption, so setting this property also sets EnableHeaderContextMenu to the opposite value.

Clicking the button sets the control's height to the caption's height (plus the drop shadow, when one is drawn) and clicking it again restores the height it had. The control does not collapse in the designer. The button is drawn, and answers clicks, only when HeaderLocation is HeaderLocation.Top; its colours are ExpandCollapseCircleFillColor and ExpandCollapseUpDownArrowsFillColor.

Gets or sets whether the caption shows a round button that opens a menu of commands for the pane.

The context menu button and the collapse button share one place at the end of the caption, so setting this property also sets EnableCollapseExpandButton to the opposite value.

Clicking the button raises HeaderContextMenuAboutToBeDisplayed and then, unless a handler cancels it, opens the menu chosen by ContextMenuType at the point clicked. The caption text is shortened to leave room for the button.

var contactsMenu = new ContextMenuStrip();
contactsMenu.Items.Add("New contact", null, (s, e) => CreateContact());
contactsMenu.Items.Add("Import from CSV...", null, (s, e) => ImportContacts());

contactsPane.EnableHeaderContextMenu = true;
contactsPane.HeaderContextMenuStrip = contactsMenu;

Gets or sets the colour the client area's background gradient ends with.

Gets or sets the colour the footer band's gradient ends with.

Gets or sets the colour the caption band's gradient ends with.

Choosing a ColorScheme other than ColorScheme.None overwrites this colour.

Gets or sets the colour of the round body of the collapse button.

ColorScheme does not change this colour.

Gets or sets the colour of the double arrow on the collapse button, which points up while the control is expanded and down while it is collapsed.

ColorScheme does not change this colour.

Gets or sets the colour of the border drawn inside the footer band.

Used only while DrawBorderAround includes the footer.

Gets or sets the thickness of the border drawn inside the footer band.

Used only while DrawBorderAround includes the footer.

Gets or sets the font of the footer text.

The footer is made deep enough for one line of this font whatever FooterCaptionHeight says.

Gets or sets the depth of the footer band – its height along the bottom or top, its width down the left or right.

The value is scaled with the display, and the band is never drawn shallower than one line of FooterCaptionFont plus a small margin. The client area is re-measured for a new depth the next time the control is resized.

Gets or sets the direction in which the footer band's gradient runs.

As with the caption, the direction is taken as if the band lay along the top or bottom, and it is not used in the HeaderFooterDrawingStyle.OfficeStyle drawing style.

Gets or sets the text shown in the footer band – a status line such as a count of items.

New text is ignored while DrawFooter is false: turn the footer on before setting its text.

The text is drawn on one line in FooterCaptionFont and FooterTextForeColor, laid out by FooterTextStringFormat.

tasksPane.DrawFooter = true;
tasksPane.FooterText = $"{openTasks.Count} open, {overdueTasks.Count} overdue";

Gets or sets the colour of the footer text.

Gets or sets how the footer text is aligned, wrapped and trimmed.

This property is not shown in the Properties window and is not saved by the designer; set it in code.

Gets or sets the colour in HeaderImage that is made transparent, so that the caption's gradient shows through the picture's background.

The colour is applied to the bitmap itself, when it is assigned and again when this colour changes, so set the colour first. Pixels made transparent stay transparent.

Gets or sets the colour of the border drawn inside the caption band.

Used only while DrawBorderAround includes the caption. A light colour on a darker gradient gives the band a raised look.

Gets or sets the thickness of the border drawn inside the caption band.

Used only while DrawBorderAround includes the caption.

Gets or sets the font of the caption text.

The caption band is made deep enough for one line of this font whatever HeaderCaptionHeight says.

Gets or sets the depth of the caption band – its height when it runs along the top or bottom, its width when it runs down the left or right.

The value is scaled with the display, and the band is never drawn shallower than one line of HeaderCaptionFont plus a small margin, so a large caption font makes the band deeper whatever this property says.

The caption is part of the frame: a deeper caption makes the client area smaller and moves the docked children.

Gets or sets the menu the context menu button opens when ContextMenuType is ContextMenuType.ContextMenu.

With the default ContextMenuType, the button opens HeaderContextMenuStrip instead; most applications need only that one.

Gets or sets the menu the context menu button opens when ContextMenuType is ContextMenuType.ContextMenu.

With the default ContextMenuType, the button opens HeaderContextMenuStrip instead; most applications need only that one.

Gets or sets the menu the context menu button opens.

The menu is used while ContextMenuType is ContextMenuType.ContextMenuStrip, the default, and the button shows only while EnableHeaderContextMenu is true.

Gets or sets how the caption and footer bands are filled: a plain gradient, or an Office-style two-tone band.

Both styles use the bands' start and end colours; the Office style blends them into a lighter upper half and a deeper lower half and ignores the gradient directions.

Gets or sets the direction in which the caption band's gradient runs.

A band down the left or right is drawn as if it lay along the top and is then turned on its side, gradient and all, so that its top edge faces outwards. The direction is not used in the HeaderFooterDrawingStyle.OfficeStyle drawing style.

Gets or sets the icon drawn at the start of the caption, before the text.

Setting this property also sets HeaderImageType to HeaderImageType.Icon. The icon is drawn at its own size, reduced to the caption's depth when it is larger, and the text starts after it.

Gets or sets the picture drawn at the start of the caption, before the text, when an icon will not do.

Setting this property also sets HeaderImageType to HeaderImageType.Bitmap. The picture is drawn at its own size, reduced to the caption's depth when it is larger.

The bitmap you assign is changed in place: the pixels of HeaderBitmapTransparencyColor are made transparent in it. Assign a copy if the original is used elsewhere. The caption is not redrawn by this setter; it shows the picture at its next repaint.

var picture = new Bitmap("Images\\calendar-16.bmp");
calendarPane.HeaderBitmapTransparencyColor = Color.Magenta;   // the bitmap's background colour
calendarPane.HeaderImage = picture;
calendarPane.HeaderText = "Calendar";

Gets or sets which picture, if any, is drawn at the start of the caption.

Setting HeaderIcon or HeaderImage sets this property to match, so set it yourself only to switch between the two, or to HeaderImageType.None to hide the picture without discarding it. Nothing is drawn when the chosen picture is null.

Gets or sets which edge of the control the caption band runs along.

The footer, when DrawFooter is on, runs along the opposite edge. On the left and right the caption and the footer are drawn turned on their side.

With HeaderLocation.Bottom no footer is drawn, and the collapse button is drawn only with HeaderLocation.Top.

Gets or sets the title shown in the caption band.

The text is drawn on one line in HeaderCaptionFont and HeaderTextForeColor, centred by default and trimmed with an ellipsis when it is too long (see HeaderTextStringFormat). Room is left for the icon and for the context menu button.

Use an empty string for a caption with no title; null stops the caption from being drawn properly.

Gets or sets the colour of the caption text.

ColorScheme does not change this colour, so pick one that reads well on the scheme's caption gradient.

Gets or sets how the caption text is aligned, wrapped and trimmed.

This property is not shown in the Properties window and is not saved by the designer; set it in code. You can also change the existing object, for example its StringFormat.Alignment, and then call Control.Refresh.

// Left-align the caption, Outlook style.
ordersPane.HeaderTextStringFormat.Alignment = StringAlignment.Near;
ordersPane.Refresh();

Gets or sets whether a soft shadow is drawn along the control's bottom and right edges, lifting the pane off the form.

A control cannot paint outside its own bounds, so the shadow is drawn inside them: a band DropShadowDepth deep along the bottom and right is given to the shadow, and the frame, caption and client area shrink by that much. Turning the shadow on therefore moves anything docked or anchored to those edges. The part of the band the shadow does not cover is painted in the nearest opaque parent's Control.BackColor.

notesPane.ShouldDrawDropShadow = true;
notesPane.DropShadowDepth = 6;
notesPane.DropShadowOpacity = 120;
notesPane.DropShadowColor = Color.FromArgb(40, 40, 60);

Gets or sets the size of the control, including its caption, footer, border and drop shadow.

The first size assigned through this property while the control is expanded is recorded as the height an expand returns to. Assigning it through a Control reference sets the size without recording it.

Gets or sets the colour the client area's background gradient starts with – the area behind the hosted controls.

The gradient runs to EndColorForBackgroundRendering in the direction BackgroundGradientDrawingDirection gives. The control paints this gradient instead of Control.BackColor. Choosing a ColorScheme other than ColorScheme.None overwrites the colour.

Gets or sets the colour the footer band's gradient starts with.

The gradient runs to EndColorForFooterRendering in the direction FooterGradientDrawingDirection gives. Choosing a ColorScheme other than ColorScheme.None overwrites the colour.

Gets or sets the colour the caption band's gradient starts with.

The gradient runs from this colour to EndColorForHeaderRendering in the direction HeaderGradientDrawingDirection gives. In the HeaderFooterDrawingStyle.OfficeStyle drawing style both colours are blended into a two-tone band instead, and this colour also outlines it.

While ColorScheme is anything other than ColorScheme.None, setting this colour also sets BorderColor to it, and choosing a scheme later overwrites it.

Gets or sets whether the caption text is drawn with plain anti-aliasing rather than grid-fitted anti-aliasing.

Plain anti-aliasing gives softer, slightly wider text that some prefer for large or bold caption fonts. The setting applies to the caption only; the footer text uses the system's default rendering.

Gets or sets whether the context menu button is drawn with a picture of your own instead of the built-in round button.

The picture is CustomIconForContextMenuButton or CustomImageForContextMenuButton, as ContextMenuImageType chooses, drawn 16 logical pixels square. The built-in button is drawn while this property is false, while ContextMenuImageType is ContextMenuButtonImageType.Default, or while both pictures are null.

filtersPane.EnableHeaderContextMenu = true;
filtersPane.UseCustomImageForContextMenuButton = true;
filtersPane.ContextMenuImageType = ContextMenuButtonImageType.Icon;
filtersPane.CustomIconForContextMenuButton = new Icon("Images\\filter.ico");

Raises the Control.FontChanged event, and passes the new font on to any caption font that has not been set explicitly.

The caption and footer fonts follow Control.Font – whether it is set in code, in the designer or inherited from the parent – until HeaderCaptionFont or FooterCaptionFont is set. Set either to null to make it follow the control's font again. The bands grow when needed to fit one line of the new font.

An override should call the base method so that the caption keeps following the font.

Paints the client area's background gradient, raises the Control.Paint event, and redraws the caption, footer and border.

The background runs from StartColorForBackgroundRendering to EndColorForBackgroundRendering. A Control.Paint handler draws on top of it. Nothing is painted while the control has no width or height.

Does nothing: the whole client area is painted in OnPaint, which avoids flicker.

Raises the Control.Resize event after redrawing the caption, footer and border for the new size.

An override should call the base method, or the bands are not redrawn when the control is resized.

Collapses the control to its caption, as clicking the collapse button does.

Collapsing records the current height and sets the height to the caption's depth (plus the drop shadow, when one is drawn). Expanding – from code or by a click on the collapse button – restores the recorded height. Asking for the state the control is already in changes nothing.

The method works whether or not EnableCollapseExpandButton is on, and also in the designer. Collapsing suits a caption along the top: the control always shrinks upwards from the bottom edge.

// Keep the search pane folded away until it is needed.
searchPane.PerformCollapseExpand(true);

// ... later, open it again at the height it had.
searchPane.PerformCollapseExpand(false);

Processes the window messages that size, paint and hit test the caption and footer, and turns clicks on them into HeaderClicked, FooterClicked, a collapse or the context menu.

An override must call the base method for every message, or the caption, the footer and their clicks stop working.

Occurs when the footer band is clicked.

The event is raised when the left mouse button is released over the footer. A footer is drawn only while DrawFooter is true and HeaderLocation is not HeaderLocation.Bottom.

Occurs when the caption band is clicked.

The event is raised when the left mouse button is released over the caption, anywhere except on its collapse or context menu button: a click on that button collapses the control or opens the menu instead.

tasksPane.HeaderClicked += (sender, e) => tasksPane.PerformCollapseExpand(true);

Occurs when the context menu button in the caption is clicked, just before the menu opens.

Set the handler's cancel argument to true to keep the menu closed. The event is raised whenever EnableHeaderContextMenu is on and the button is clicked, even when no menu has been assigned.

The menu opens at the point that was clicked. Which menu opens depends on ContextMenuType.