HypernovaDesktop Components · docs
Binarymission
WinForms › Extended Label › ExtendedLabel

ExtendedLabel

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

A label for headings, captions and status panels that can draw a gradient background, a border, a drop shadow, and text turned on its side.

public class ExtendedLabel : Control

Inherits from / implements: Control

Remarks

What it is for

Use it where a plain Label is too flat: a section heading on a settings page, a caption tile on a dashboard ("Open orders: 42"), or a vertical title down the edge of a panel. It is drawn entirely by the control, so the background, border, shadow and text can be styled independently.

The parts

The shadow and the border are on by default, so a new label shows a black one-pixel border with a soft grey shadow. Set ShouldDrawDropShadow and ShouldDrawBorder to false for a flat caption. The label is left out of the tab order.

Examples

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

public class SalesDashboard : Form
{
    public SalesDashboard()
    {
        Text = "Today's sales";
        ClientSize = new Size(360, 260);

        // A caption tile with a blue gradient and a soft shadow.
        var openOrders = new ExtendedLabel
        {
            Text = "Open orders\n42",
            Location = new Point(60, 20),
            Size = new Size(200, 80),
            Font = new Font("Segoe UI", 12f, FontStyle.Bold),
            ForeColor = Color.White,
            StartLinearGradientBackgroundColor = Color.SteelBlue,
            EndLinearGradientBackgroundColor = Color.MidnightBlue,
            BackgroundGradientFloatAngle = 90f,
            TextAlignment = ContentAlignment.MiddleCenter,
            BorderColor = Color.MidnightBlue,
            DropShadowMargin = 5
        };

        // A vertical title down the left edge, with no shadow or border.
        var sideTitle = new ExtendedLabel
        {
            Text = "Northern region",
            Location = new Point(12, 20),
            Size = new Size(220, 32),
            ShouldDrawDropShadow = false,
            ShouldDrawBorder = false,
            Orientation = ExtendedLabel.DrawingOrientation.Vertical,   // swaps Width and Height
            VerticalTextDirection = ExtendedLabel.TextDirection.BottomTop
        };

        Controls.Add(openOrders);
        Controls.Add(sideTitle);
    }
}

See also

Members at a glance

Constructors
ExtendedLabelInitialises a label with a black one-pixel border, a soft grey drop shadow 6 logical pixels deep, a SystemColors.Control background and horizontal, top-left aligned text.
Properties
BackgroundGradientFloatAngleGets or sets the direction of the background gradient.
BorderColorGets or sets the colour of the border.
BorderDashStyleGets or sets the line pattern of the border – solid, dashed, dotted and so on.
BorderDrawingStyleGets or sets how heavy the border is.
CreateParamsGets the parameters used to create the label's window, with the transparent extended style added while IsBackgroundTransparent is true.
DropShadowGradientFloatAngleGets or sets the direction of the gradient-block shadow.
DropShadowMarginGets or sets how far the drop shadow reaches beyond the label.
DropShadowOpacityGets or sets how dark the soft drop shadow is at its strongest.
EndLinearGradientBackgroundColorGets or sets the colour the background gradient ends with.
EndLinearGradientDropShadowBackgroundColorGets or sets the colour the gradient-block shadow ends with.
IsBackgroundTransparentGets or sets whether the parent shows through the label, with only the text and the border drawn.
OrientationGets or sets whether the text runs across the label or up or down it.
ShouldDrawBorderGets or sets whether a border is drawn round the label.
ShouldDrawDropShadowGets or sets whether a shadow is drawn below and to the right of the label.
ShouldDrawSoftDropShadowGets or sets whether the drop shadow is a soft, blurred shadow rather than a gradient-filled block.
ShouldRefreshUponParentMoveResizeGets or sets whether the label redraws itself straight away whenever its parent or its form is resized.
StartLinearGradientBackgroundColorGets or sets the colour the background gradient starts with.
StartLinearGradientDropShadowBackgroundColorGets or sets the colour of the drop shadow – the whole soft shadow, or where the gradient-block shadow starts.
StringFormatGets or sets the layout options the text is drawn with – trimming, wrapping and the other StringFormat flags.
TextGets or sets the text the label shows.
TextAlignmentGets or sets where the text sits within the label – one of nine positions, from top-left to bottom-right.
VerticalTextDirectionGets or sets which way vertical text reads.
Methods
OnFontChangedRaises the Control.FontChanged event and redraws the area of the parent the label covers, so text in the new font leaves no trace of the old.
OnHandleCreatedRaises the Control.HandleCreated event and starts listening to the resizing of the parent and the form, for ShouldRefreshUponParentMoveResize.
OnHandleDestroyedStops listening to the parent and the form, and raises the Control.HandleDestroyed event.
OnPaintRaises the Control.Paint event and then draws the background, the shadow, the text and the border.
OnPaintBackgroundPaints the background and the drop shadow – or nothing at all while IsBackgroundTransparent is true.
OnParentChangedRaises the Control.ParentChanged event and, once the window exists, listens to the new parent and form instead of the old ones.
OnParentFontChangedRaises the Control.ParentFontChanged event and redraws the area of the parent the label covers.
OnResizeRedraws the label at once for its new size, then raises the Control.Resize event.
WndProcProcesses the label's window messages, drawing the label again after each paint message so that the drawing is complete even when Windows paints part of the window itself.

Constructors

ExtendedLabel

public ExtendedLabel()

Initialises a label with a black one-pixel border, a soft grey drop shadow 6 logical pixels deep, a SystemColors.Control background and horizontal, top-left aligned text.

Properties

BackgroundGradientFloatAngle

public float BackgroundGradientFloatAngle

Gets or sets the direction of the background gradient.

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

BorderColor

public Color BorderColor

Gets or sets the colour of the border.

Value
The border colour. The default is Color.Black.
See also

BorderDashStyle

public DashStyle BorderDashStyle

Gets or sets the line pattern of the border – solid, dashed, dotted and so on.

Value
One of the DashStyle values. The default is Solid.

BorderDrawingStyle

public BorderStyle BorderDrawingStyle

Gets or sets how heavy the border is.

Value
One of the BorderStyle values: no border, or 1, 2 or 3 logical pixels. The default is BorderStyle.Thin.
Remarks

The border is drawn only while ShouldDrawBorder is true. The text area shrinks by the border's width, so a heavier border moves the text rather than covering it.

See also

CreateParams

protected override CreateParams CreateParams

Gets the parameters used to create the label's window, with the transparent extended style added while IsBackgroundTransparent is true.

Value
The base parameters with the label's styles applied.
Remarks

Reading this property also switches double buffering off for a transparent label and on for an opaque one, so the two always match.

DropShadowGradientFloatAngle

public float DropShadowGradientFloatAngle

Gets or sets the direction of the gradient-block shadow.

Value
The angle in degrees, measured clockwise from the x-axis. The default is 45.
Remarks

Used only while ShouldDrawSoftDropShadow is false.

DropShadowMargin

public int DropShadowMargin

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

Value
The depth in logical pixels. The default is 6.
Remarks

The space is taken from the right and bottom of the control's bounds, so a deeper shadow leaves less room for the text.

DropShadowOpacity

public int DropShadowOpacity

Gets or sets how dark the soft drop shadow is at its strongest.

Value
The opacity, from 0 (invisible) to 255 (solid). Values outside that range are clamped. The default is 150.
Default
SoftDropShadowDefaultOpacity
Designer category
Appearance
Remarks

Used only for the soft shadow (ShouldDrawSoftDropShadow).

EndLinearGradientBackgroundColor

public Color EndLinearGradientBackgroundColor

Gets or sets the colour the background gradient ends with.

Value
The end colour. The default is SystemColors.Control.
See also

EndLinearGradientDropShadowBackgroundColor

public Color EndLinearGradientDropShadowBackgroundColor

Gets or sets the colour the gradient-block shadow ends with.

Value
The end colour. The default is Color.LightGray.
Remarks

Used only while ShouldDrawSoftDropShadow is false; the soft shadow is a single colour.

IsBackgroundTransparent

public bool IsBackgroundTransparent

Gets or sets whether the parent shows through the label, with only the text and the border drawn.

Value
true for a see-through label; false to draw the background and the shadow. The default is false.
Remarks

Use it to place a caption over a picture or a gradient panel. The background gradient and the drop shadow are not drawn while it is true.

Changing it re-creates the label's window, so set it once, when the label is set up, rather than repeatedly.

Example
// A caption over a banner picture.
var bannerCaption = new ExtendedLabel
{
    Text = "Spring catalogue",
    IsBackgroundTransparent = true,
    ShouldDrawBorder = false,
    ForeColor = Color.White,
    Font = new Font("Segoe UI", 16f, FontStyle.Bold)
};
bannerPicture.Controls.Add(bannerCaption);

Orientation

public DrawingOrientation Orientation

Gets or sets whether the text runs across the label or up or down it.

Value
One of the DrawingOrientation values. The default is DrawingOrientation.Horizontal.
Remarks

Changing the orientation swaps the label's width and height, so a 200 x 30 caption becomes a 30 x 200 strip. Setting the value it already has does nothing.

Example
var regionTitle = new ExtendedLabel { Text = "Southern region", Size = new Size(240, 28) };
regionTitle.Orientation = ExtendedLabel.DrawingOrientation.Vertical;   // now 28 x 240
regionTitle.VerticalTextDirection = ExtendedLabel.TextDirection.BottomTop;
See also

ShouldDrawBorder

public bool ShouldDrawBorder

Gets or sets whether a border is drawn round the label.

Value
true to draw the border; the default is true.
Remarks

The border's weight comes from BorderDrawingStyle; setting that to BorderStyle.None removes the border whatever this property says.

See also

ShouldDrawDropShadow

public bool ShouldDrawDropShadow

Gets or sets whether a shadow is drawn below and to the right of the label.

Value
true to draw the shadow; the default is true.
Remarks

The shadow takes DropShadowMargin from the right and bottom of the label, so the background, border and text are drawn in the rest. It is soft and blurred while ShouldDrawSoftDropShadow is true, and is not drawn while IsBackgroundTransparent is true.

See also

ShouldDrawSoftDropShadow

public bool ShouldDrawSoftDropShadow

Gets or sets whether the drop shadow is a soft, blurred shadow rather than a gradient-filled block.

Value
true for the soft shadow; the default is true.
Default
true
Designer category
Appearance
Remarks

The soft shadow falls down and to the right of the label, in StartLinearGradientDropShadowBackgroundColor at DropShadowOpacity, and reaches DropShadowMargin beyond it. When false, the shadow is a block offset by DropShadowMargin and filled with a gradient of the two shadow colours at DropShadowGradientFloatAngle. Either way it is drawn only while ShouldDrawDropShadow is true.

ShouldRefreshUponParentMoveResize

public bool ShouldRefreshUponParentMoveResize

Gets or sets whether the label redraws itself straight away whenever its parent or its form is resized.

Value
true to redraw on every resize of the parent and the form. The default is false.
Remarks

Turn it on for a transparent label, or one anchored in a resizing layout, that is left with stale drawing. Despite the name, moving the parent does not trigger a redraw; only resizing does.

StartLinearGradientBackgroundColor

public Color StartLinearGradientBackgroundColor

Gets or sets the colour the background gradient starts with.

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

Set EndLinearGradientBackgroundColor to the same colour for a solid background. The background is not drawn while IsBackgroundTransparent is true.

See also

StartLinearGradientDropShadowBackgroundColor

public Color StartLinearGradientDropShadowBackgroundColor

Gets or sets the colour of the drop shadow – the whole soft shadow, or where the gradient-block shadow starts.

Value
The shadow colour. The default is Color.Gray.
See also

StringFormat

public StringFormat StringFormat

Gets or sets the layout options the text is drawn with – trimming, wrapping and the other StringFormat flags.

Value
The format. The default is a new StringFormat centred both ways. null uses the framework's default layout.
Remarks

The text is first placed by TextAlignment, in a rectangle the size of the text itself, so the format's own alignment makes little difference; its trimming and flags are the useful part.

Text

public new string Text

Gets or sets the text the label shows.

Value
The text; line breaks start new lines. The default is null, which shows nothing.
Remarks

The Properties window edits it with a multi-line editor.

This property hides Text. Setting the text through a Control reference changes Text only, and the label does not show it; set it through an ExtendedLabel reference.

TextAlignment

public ContentAlignment TextAlignment

Gets or sets where the text sits within the label – one of nine positions, from top-left to bottom-right.

Value
One of the ContentAlignment values. The default is ContentAlignment.TopLeft.
Remarks

The text is placed inside Control.Padding, a 4-pixel inset, the border and the shadow. With Control.RightToLeft set to Yes, left and right are swapped.

Changing it re-creates the label's window.

VerticalTextDirection

public TextDirection VerticalTextDirection

Gets or sets which way vertical text reads.

Value
One of the TextDirection values. The default is TextDirection.TopBottom.
Remarks

Has an effect only while Orientation is DrawingOrientation.Vertical.

Methods

OnFontChanged

protected override void OnFontChanged(EventArgs e)

Raises the Control.FontChanged event and redraws the area of the parent the label covers, so text in the new font leaves no trace of the old.

Parameters
e
The data for the event.

OnHandleCreated

protected override void OnHandleCreated(EventArgs e)

Raises the Control.HandleCreated event and starts listening to the resizing of the parent and the form, for ShouldRefreshUponParentMoveResize.

Parameters
e
The data for the event.

OnHandleDestroyed

protected override void OnHandleDestroyed(EventArgs e)

Stops listening to the parent and 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 background, the shadow, the text and the border.

Parameters
e
The graphics surface and the area to paint.

OnPaintBackground

protected override void OnPaintBackground(PaintEventArgs pevent)

Paints the background and the drop shadow – or nothing at all while IsBackgroundTransparent is true.

Parameters
pevent
The graphics surface and the area to paint.

OnParentChanged

protected override void OnParentChanged(EventArgs e)

Raises the Control.ParentChanged event and, once the window exists, listens to the new parent and form instead of the old ones.

Parameters
e
The data for the event.

OnParentFontChanged

protected override void OnParentFontChanged(EventArgs e)

Raises the Control.ParentFontChanged event and redraws the area of the parent the label covers.

Parameters
e
The data for the event.

OnResize

protected override void OnResize(EventArgs e)

Redraws the label at once for its new size, then raises the Control.Resize event.

Parameters
e
The data for the event.

WndProc

protected override void WndProc(ref Message m)

Processes the label's window messages, drawing the label again after each paint message so that the drawing is complete even when Windows paints part of the window itself.

Parameters
m
The message to process.