WinForms › Extended Group Box › AdvancedGroupBox

AdvancedGroupBox

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

A group box with a styled frame: a gradient or solid body, a solid, dotted or rounded border, and a header band with its own background, border and font – a drop-in replacement for GroupBox.

public partial class AdvancedGroupBox : GroupBox

Inherits from / implements: GroupBox

Remarks

What it is for

Use it wherever a form groups related fields – "Delivery address", "Payment", "Account settings" – and the stock group box looks too plain. It is a GroupBox, so it keeps the container behaviour, the tab order and the designer support; only the drawing is replaced.

The parts of the frame

Body – filled from half-way down the header to the bottom, with a gradient from BackgroundBrushColor1 to BackgroundBrushColor2 at LinearGradientBrushGradientAngle, or with Control.BackColor when IsBackgroundDrawingUsingLinerGradientBrush is false.
Border – BorderColor at BorderThickness, drawn as a line or as dashes (ControlBorderStyle), optionally with rounded corners (ShouldDrawRoundedCorners, RoundedCornerTargets, RoundedCornersAngle).
Header – the control's Control.Text in HeaderFont and HeaderForeColor, on a band with its own gradient or solid background and border, placed by HeaderAlignment.

Good to know

While the body is a gradient, a child control added with the group box's own Control.BackColor is given a transparent background, so labels and check boxes do not paint solid bands across the gradient. A child whose back colour was set to something else is left alone.
Metrics – margins, thicknesses, dash lengths, corner size – are in logical pixels and are scaled for the display the control is on.
The header and the body read HeaderFont, not Control.Font; Control.Font is still the font children inherit.

Examples

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

public class CheckoutForm : Form
{
    public CheckoutForm()
    {
        Text = "Checkout";
        ClientSize = new Size(380, 220);

        var deliveryGroup = new AdvancedGroupBox
        {
            Text = "Delivery address",
            Location = new Point(12, 12),
            Size = new Size(356, 150),
            HeaderFont = new Font("Segoe UI", 9.75f, FontStyle.Bold),
            HeaderForeColor = Color.White,
            HeaderBackgroundColor1 = Color.SteelBlue,
            HeaderBackgroundColor2 = Color.MidnightBlue,
            HeaderBorderColor = Color.MidnightBlue,
            BackgroundBrushColor1 = Color.White,
            BackgroundBrushColor2 = Color.AliceBlue,
            BorderColor = Color.SteelBlue,
            ShouldDrawRoundedCorners = true,
            RoundedCornerTargets = GroupBoxCornerTargets.BottomLeft | GroupBoxCornerTargets.BottomRight,
            RoundedCornersAngle = 16
        };

        deliveryGroup.Controls.Add(new Label { Text = "Postcode", Location = new Point(16, 40), AutoSize = true });
        deliveryGroup.Controls.Add(new TextBox { Location = new Point(100, 36), Width = 120 });
        deliveryGroup.Controls.Add(new CheckBox { Text = "Same as billing address", Location = new Point(16, 76), AutoSize = true });

        Controls.Add(deliveryGroup);
    }
}

Members at a glance

Constructors
`AdvancedGroupBox`	Initialises a group box with a top-left header on a white-to-dark-grey gradient band with a black border, a dark grey one-pixel frame, and a body shaded from `SystemColors.Control` to `SystemColors.ControlDark`.
Properties
`BackgroundBrushColor1`	Gets or sets the colour the body gradient starts with – the top, at the default angle.
`BackgroundBrushColor2`	Gets or sets the colour the body gradient ends with – the bottom, at the default angle.
`BorderColor`	Gets or sets the colour of the frame round the body.
`BorderThickness`	Gets or sets the width of the frame round the body.
`ControlBorderStyle`	Gets or sets whether the frame is drawn as a continuous line or as dashes.
`DottedBorderDepth`	Gets or sets the length of each dash in a dotted frame.
`DottedBorderGap`	Gets or sets the space between the dashes of a dotted frame.
`HeaderAlignment`	Gets or sets where along the top edge the header sits.
`HeaderBackgroundColor1`	Gets or sets the colour the header band's gradient starts with.
`HeaderBackgroundColor2`	Gets or sets the colour the header band's gradient ends with.
`HeaderBackgroundLeftMargin`	Gets or sets extra space added to the header band on the left of the text, on top of `TextLeftMargin`.
`HeaderBackgroundLinearGradientBrushGradientAngle`	Gets or sets the direction of the header band's gradient.
`HeaderBackgroundRightMargin`	Gets or sets extra space added to the header band on the right of the text, on top of `TextRightMargin`.
`HeaderBorderColor`	Gets or sets the colour of the border round the header band.
`HeaderBorderThickness`	Gets or sets the width of the border round the header band.
`HeaderExtraHeightFactor`	Gets or sets how much taller than its text the header band is.
`HeaderFont`	Gets or sets the font of the header text.
`HeaderForeColor`	Gets or sets the colour of the header text.
`HeaderSolidBrushBackgroundColor`	Gets or sets the colour of the header band when it is filled with a solid colour.
`IsBackgroundDrawingUsingLinerGradientBrush`	Gets or sets whether the body is filled with a gradient rather than a solid colour.
`IsHeaderBackgroundDrawingEnabled`	Gets or sets whether the header band has a background of its own.
`IsHeaderBackgroundGradient`	Gets or sets whether the header band is filled with a gradient rather than a solid colour.
`IsHeaderBorderDrawingEnabled`	Gets or sets whether a border is drawn round the header band.
`LinearGradientBrushGradientAngle`	Gets or sets the direction of the body gradient.
`RoundedCornerTargets`	Gets or sets which corners of the frame are rounded.
`RoundedCornersAngle`	Gets or sets how round the rounded corners are – the size of each corner's curve, despite the name not an angle.
`ShouldDrawRoundedCorners`	Gets or sets whether the frame's corners are rounded.
`ShouldUpdateChildrenUponParentFormMoveSize`	Gets or sets whether the group box repaints itself each time the form it is on moves or is resized.
`TextLeftMargin`	Gets or sets the space between the left edge of the header band and the header text.
`TextRightMargin`	Gets or sets the space between the header text and the right edge of the header band.
Methods
`OnControlAdded`	Raises the `Control.ControlAdded` event and, while the body is a gradient, gives the new child a transparent background if it has the group box's own back colour.
`OnHandleCreated`	Raises the `Control.HandleCreated` event and starts listening to the form's move and resize, for `ShouldUpdateChildrenUponParentFormMoveSize`.
`OnHandleDestroyed`	Stops listening to the form and raises the `Control.HandleDestroyed` event.
`OnPaint`	Raises the `Control.Paint` event and then draws the body, the frame and the header over the whole control.
`OnParentChanged`	Raises the `Control.ParentChanged` event and, once the window exists, moves the move and resize listening to the form the group box is now on.

Constructors

AdvancedGroupBox

public AdvancedGroupBox()

Initialises a group box with a top-left header on a white-to-dark-grey gradient band with a black border, a dark grey one-pixel frame, and a body shaded from SystemColors.Control to SystemColors.ControlDark.

Properties

BackgroundBrushColor1

public Color BackgroundBrushColor1

Gets or sets the colour the body gradient starts with – the top, at the default angle.

Value: The start colour. The default is SystemColors.Control.

Remarks

Used only while IsBackgroundDrawingUsingLinerGradientBrush is true.

BackgroundBrushColor2

public Color BackgroundBrushColor2

Gets or sets the colour the body gradient ends with – the bottom, at the default angle.

Value: The end colour. The default is SystemColors.ControlDark.

BorderColor

public Color BorderColor

Gets or sets the colour of the frame round the body.

Value: The frame colour. The default is Color.DarkGray.

BorderThickness

public float BorderThickness

Gets or sets the width of the frame round the body.

Value: The width in logical pixels. The default is 1. Zero or less draws no frame.

ControlBorderStyle

public GroupBoxBorderStyle ControlBorderStyle

Gets or sets whether the frame is drawn as a continuous line or as dashes.

Value: One of the GroupBoxBorderStyle values. The default is GroupBoxBorderStyle.Normal.

Remarks

Rounded corners (ShouldDrawRoundedCorners) apply only to GroupBoxBorderStyle.Normal; a dotted frame is always square. The dashes are sized by DottedBorderDepth and DottedBorderGap.

DottedBorderDepth

public int DottedBorderDepth

Gets or sets the length of each dash in a dotted frame.

Value: The dash length in logical pixels. The default is 4.

Remarks

Used only while ControlBorderStyle is GroupBoxBorderStyle.Dotted.

DottedBorderGap

public int DottedBorderGap

Gets or sets the space between the dashes of a dotted frame.

Value: The gap in logical pixels. The default is 2.

HeaderAlignment

public GroupBoxHeaderAlignment HeaderAlignment

Gets or sets where along the top edge the header sits.

Value: One of the GroupBoxHeaderAlignment values. The default is GroupBoxHeaderAlignment.TopLeft.

Remarks

With GroupBoxHeaderAlignment.Custom, the header starts Control.Padding.Padding.Left pixels from the left edge – at least 1, and no further than leaves room for the whole header. The control's padding also sets the space round its children, as it does on any container.

Example

paymentGroup.HeaderAlignment = GroupBoxHeaderAlignment.Custom;
paymentGroup.Padding = new Padding(40, 0, 0, 0);   // header 40 pixels in from the left

HeaderBackgroundColor1

public Color HeaderBackgroundColor1

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

Value: The start colour. The default is Color.White.

HeaderBackgroundColor2

public Color HeaderBackgroundColor2

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

Value: The end colour. The default is Color.DarkGray.

HeaderBackgroundLeftMargin

public int HeaderBackgroundLeftMargin

Gets or sets extra space added to the header band on the left of the text, on top of TextLeftMargin.

Value: The space in logical pixels. The default is 0.

Remarks

The text moves right by this amount and the band widens by it. At display scales above 100% the band widens by the unscaled amount while the text moves by the scaled one, so large values can push the end of the text towards the band's edge.

HeaderBackgroundLinearGradientBrushGradientAngle

public float HeaderBackgroundLinearGradientBrushGradientAngle

Gets or sets the direction of the header band's gradient.

Value: The angle in degrees, measured clockwise from the x-axis. The default is 90: top to bottom.

HeaderBackgroundRightMargin

public int HeaderBackgroundRightMargin

Gets or sets extra space added to the header band on the right of the text, on top of TextRightMargin.

Value: The space in logical pixels. The default is 0.

HeaderBorderColor

public Color HeaderBorderColor

Gets or sets the colour of the border round the header band.

Value: The border colour. The default is Color.Black.

HeaderBorderThickness

public int HeaderBorderThickness

Gets or sets the width of the border round the header band.

Value: The width in logical pixels. The default is 1. Zero or less draws no header border.

HeaderExtraHeightFactor

public int HeaderExtraHeightFactor

Gets or sets how much taller than its text the header band is.

Value: The extra height in logical pixels, shared above and below the text. The default is 8.

HeaderFont

public Font HeaderFont

Gets or sets the font of the header text.

Value: The header font. The default is the control's Control.Font at the time it was created.

Remarks

Changing Control.Font afterwards does not change the header; it is still the font the group box's children inherit. The header band grows to the height of this font plus HeaderExtraHeightFactor.

HeaderForeColor

public Color HeaderForeColor

Gets or sets the colour of the header text.

Value: The text colour. The default is the control's Control.ForeColor at the time it was created – normally SystemColors.ControlText.

HeaderSolidBrushBackgroundColor

public Color HeaderSolidBrushBackgroundColor

Gets or sets the colour of the header band when it is filled with a solid colour.

Value: The band colour. The default is Color.Empty, which fills nothing, so the frame line shows through the band until a colour is set.

Remarks

Used when IsHeaderBackgroundDrawingEnabled is true and IsHeaderBackgroundGradient is false.

IsBackgroundDrawingUsingLinerGradientBrush

public bool IsBackgroundDrawingUsingLinerGradientBrush

Gets or sets whether the body is filled with a gradient rather than a solid colour.

Value: true for a gradient from BackgroundBrushColor1 to BackgroundBrushColor2; false to fill with Control.BackColor. The default is true.

Remarks

Setting it to true gives every child that has the group box's own back colour a transparent background, so the gradient shows through. Setting it back to false does not restore those children's colours.

IsHeaderBackgroundDrawingEnabled

public bool IsHeaderBackgroundDrawingEnabled

Gets or sets whether the header band has a background of its own.

Value: true to fill the band with a gradient or a solid colour (see IsHeaderBackgroundGradient); false to set the header text straight on the frame, which is broken round it. The default is true.

Example

// A classic look: plain caption text in the gap of a thin frame.
accountGroup.IsHeaderBackgroundDrawingEnabled = false;
accountGroup.IsHeaderBorderDrawingEnabled = false;
accountGroup.IsBackgroundDrawingUsingLinerGradientBrush = false;

IsHeaderBackgroundGradient

public bool IsHeaderBackgroundGradient

Gets or sets whether the header band is filled with a gradient rather than a solid colour.

Value: true for a gradient from HeaderBackgroundColor1 to HeaderBackgroundColor2; false to fill with HeaderSolidBrushBackgroundColor. The default is true.

Remarks

Has an effect only while IsHeaderBackgroundDrawingEnabled is true.

IsHeaderBorderDrawingEnabled

public bool IsHeaderBorderDrawingEnabled

Gets or sets whether a border is drawn round the header band.

Value: true to outline the header in HeaderBorderColor. The default is true.

LinearGradientBrushGradientAngle

public float LinearGradientBrushGradientAngle

Gets or sets the direction of the body gradient.

Value: The angle in degrees, measured clockwise from the x-axis. The default is 90: top to bottom.

Remarks

0 runs left to right, 90 top to bottom, 45 diagonally from the top-left corner.

RoundedCornerTargets

public GroupBoxCornerTargets RoundedCornerTargets

Gets or sets which corners of the frame are rounded.

Value: A combination of GroupBoxCornerTargets flags. The default is GroupBoxCornerTargets.All.

Remarks

Used only while ShouldDrawRoundedCorners is true.

Example

summaryGroup.ShouldDrawRoundedCorners = true;
summaryGroup.RoundedCornerTargets = GroupBoxCornerTargets.TopRight | GroupBoxCornerTargets.BottomLeft;

RoundedCornersAngle

public float RoundedCornersAngle

Gets or sets how round the rounded corners are – the size of each corner's curve, despite the name not an angle.

Value: The diameter of the corner arc in logical pixels. The default is 60. It is limited to the width and height of the body; zero or less gives square corners.

ShouldDrawRoundedCorners

public bool ShouldDrawRoundedCorners

Gets or sets whether the frame's corners are rounded.

Value: true to round the corners named by RoundedCornerTargets. The default is false.

Remarks

Applies only while ControlBorderStyle is GroupBoxBorderStyle.Normal. The body is clipped to the rounded shape, and the area outside it shows the colour of the nearest parent that is not transparent. With rounded corners the top line runs behind the header band rather than stopping at it.

ShouldUpdateChildrenUponParentFormMoveSize

public bool ShouldUpdateChildrenUponParentFormMoveSize

Gets or sets whether the group box repaints itself each time the form it is on moves or is resized.

Value: true to repaint on every move and resize of the form; false to repaint only when Windows asks. The default is false.

Remarks

Turn it on if the group box sits over something that changes as the form moves – a transparent parent showing a background image, say – and is left with stale drawing. Only the group box itself is invalidated, not its children.

TextLeftMargin

public int TextLeftMargin

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

Value: The space in logical pixels. The default is 3.

Remarks

The header band grows to hold this margin, TextRightMargin and the text.

TextRightMargin

public int TextRightMargin

Gets or sets the space between the header text and the right edge of the header band.

Value: The space in logical pixels. The default is 3.

Methods

OnControlAdded

protected override void OnControlAdded(ControlEventArgs e)

Raises the Control.ControlAdded event and, while the body is a gradient, gives the new child a transparent background if it has the group box's own back colour.

Parameters

e: The child that was added.

Remarks

A child that cannot take a transparent background keeps its colour.

OnHandleCreated

protected override void OnHandleCreated(EventArgs e)

Raises the Control.HandleCreated event and starts listening to the form's move and resize, for ShouldUpdateChildrenUponParentFormMoveSize.

Parameters

e: The data for the event.

OnHandleDestroyed

protected override void OnHandleDestroyed(EventArgs e)

Stops listening to the form and raises the Control.HandleDestroyed event.

Parameters

e: The data for the event.

OnPaint

protected override void OnPaint(PaintEventArgs e)

Raises the Control.Paint event and then draws the body, the frame and the header over the whole control.

Parameters

e: The graphics surface and the area to paint.

Remarks

The control's drawing covers everything a Control.Paint handler drew, because the handlers run first. To draw on top of the group box, override this method and draw after calling the base implementation.

OnParentChanged

protected override void OnParentChanged(EventArgs e)

Raises the Control.ParentChanged event and, once the window exists, moves the move and resize listening to the form the group box is now on.

Parameters

e: The data for the event.

AdvancedGroupBox

Remarks

What it is for

The parts of the frame

Good to know

Examples

See also

Members at a glance

Constructors

AdvancedGroupBox

Properties

BackgroundBrushColor1

Remarks

See also

BackgroundBrushColor2

See also

BorderColor

See also

BorderThickness

ControlBorderStyle

Remarks

DottedBorderDepth

Remarks

See also

DottedBorderGap

See also

HeaderAlignment

Remarks

Example

HeaderBackgroundColor1

See also

HeaderBackgroundColor2

See also

HeaderBackgroundLeftMargin

Remarks

See also

HeaderBackgroundLinearGradientBrushGradientAngle

See also

HeaderBackgroundRightMargin

See also

HeaderBorderColor

See also

HeaderBorderThickness

HeaderExtraHeightFactor

HeaderFont

Remarks

HeaderForeColor

HeaderSolidBrushBackgroundColor

Remarks

IsBackgroundDrawingUsingLinerGradientBrush

Remarks

See also

IsHeaderBackgroundDrawingEnabled

Example

IsHeaderBackgroundGradient

Remarks

IsHeaderBorderDrawingEnabled

See also

LinearGradientBrushGradientAngle

Remarks

RoundedCornerTargets

Remarks

Example

RoundedCornersAngle

See also

ShouldDrawRoundedCorners

Remarks

See also

ShouldUpdateChildrenUponParentFormMoveSize

Remarks

TextLeftMargin

Remarks

See also

TextRightMargin

See also

Methods

OnControlAdded

Parameters

Remarks

OnHandleCreated