WinForms › Extended Text › BinaryExtendedText

BinaryExtendedText

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

A TextBox with a flat, coloured border that can light up under the pointer, be drawn dotted, and blink to draw the eye to a field that needs attention.

public class BinaryExtendedText : System.Windows.Forms.TextBox

Inherits from / implements: System.Windows.Forms.TextBox

Remarks

What it is for

Use it in place of a TextBox on forms where the classic sunken 3-D edge looks out of place, or where a field should call for attention – a required field left empty, or a value that failed validation. All the editing, selection, clipboard and scrolling behaviour is the standard text box's; only the frame round it is drawn by the control.

The border

While ExtendedState is true (the default), a one-pixel border is drawn in BorderColor, continuous or dotted (DrawBorder). With ExtendedState false the box keeps a classic sunken edge.
With ShowBorderAlways true (the default) the border is always drawn in BorderColor. Set it to false for a hover effect: the border is drawn in BorderColorWhenControlIsNotInFocus at rest, and in BorderColor while the pointer is over the box or it has the focus.
When the box is disabled, the control draws the greyed text itself; in the flat style it does so on a window background, with a border in BorderColorWhenControlIsDisabled.

Blinking

StartToBlink() flashes the border between a colour of your choice and BorderColor until StopBlinking is called – a quiet way to point at the field a validation message is about.

Examples

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

public class NewCustomerForm : Form
{
    private readonly BinaryExtendedText emailBox;

    public NewCustomerForm()
    {
        Text = "New customer";
        ClientSize = new Size(340, 110);

        emailBox = new BinaryExtendedText
        {
            Location = new Point(12, 12),
            Width = 316,
            BorderColor = Color.SteelBlue,
            BorderColorWhenControlIsNotInFocus = Color.Silver,
            ShowBorderAlways = false          // grey at rest, blue under the pointer or with the focus
        };
        emailBox.TextChanged += (sender, e) => emailBox.StopBlinking();

        var saveButton = new Button { Text = "Save", Location = new Point(253, 70) };
        saveButton.Click += SaveButton_Click;

        Controls.Add(emailBox);
        Controls.Add(saveButton);
    }

    private void SaveButton_Click(object sender, EventArgs e)
    {
        if (!emailBox.Text.Contains("@"))
        {
            emailBox.StartToBlink(Color.Crimson, 400);   // flash until the user edits the field
            emailBox.Focus();
            return;
        }

        Close();
    }
}

Members at a glance

Constructors
`BinaryExtendedText`	Initialises a text box with the flat border on, drawn constantly in `SystemColors.Highlight`.
Properties
`BorderColor`	Gets or sets the colour of the border – all the time, or while the box is under the pointer or has the focus when `ShowBorderAlways` is `false`.
`BorderColorWhenControlIsDisabled`	Gets or sets the colour of the border while the box is disabled.
`BorderColorWhenControlIsNotInFocus`	Gets or sets the border colour at rest – when the box has neither the focus nor the pointer over it – while `ShowBorderAlways` is `false`.
`BorderStyle`	Gets the standard text box border style underneath the control's own frame; it cannot be set.
`DotBorderDepth`	Gets or sets the length of each dash in a dotted border.
`DotBorderGap`	Gets or sets the space between the dashes of a dotted border.
`DrawBorder`	Gets or sets whether the border is drawn as a continuous line or as dashes.
`ExtendedState`	Gets or sets whether the control draws its flat, coloured border, or keeps the classic sunken 3-D edge of a standard text box.
`OptimiseRedrawWhenDisabled`	Gets or sets whether the control skips its own drawing of the border and greyed text while the box is disabled.
`ShowBorderAlways`	Gets or sets whether the border is always drawn in `BorderColor`, rather than only while the pointer is over the box or it has the focus.
`UseEnhancedPasswordChar`	Gets or sets whether a password box masks its text with round bullets (●) instead of its own `TextBox.PasswordChar`.
Methods
`Dispose`	Releases the resources the control holds, including the timer behind the blinking border.
`OnGotFocus`	Redraws the border for the box having the focus, and raises the `Control.GotFocus` event.
`OnLostFocus`	Redraws the border for the box losing the focus, and raises the `Control.LostFocus` event.
`OnMouseEnter`	Redraws the border for the pointer being over the box, and raises the `Control.MouseEnter` event.
`OnMouseLeave`	Redraws the border for the pointer leaving the box, and raises the `Control.MouseLeave` event.
`StartToBlink`	Starts flashing the border between `BlinkColor` and `BorderColor`, every half second, until `StopBlinking` is called.
`StartToBlink`	Starts flashing the border between `BlinkColor` and `BorderColor` at the given interval, until `StopBlinking` is called.
`StopBlinking`	Stops the border blinking and puts back the `BorderColor` and `ShowBorderAlways` it had when the blinking started.
`WndProc`	Processes the box's window messages, drawing the control's border – and, when disabled, its greyed text – after the standard text box has painted.

Constructors

BinaryExtendedText

public BinaryExtendedText()

Initialises a text box with the flat border on, drawn constantly in SystemColors.Highlight.

Properties

BorderColor

public Color BorderColor

Gets or sets the colour of the border – all the time, or while the box is under the pointer or has the focus when ShowBorderAlways is false.

Value: The border colour. The default is SystemColors.Highlight.

Remarks

While the border is blinking, the control sets this property itself on each blink, so a value assigned then is overwritten; StopBlinking restores the colour it had when the blinking started.

BorderColorWhenControlIsDisabled

public Color BorderColorWhenControlIsDisabled

Gets or sets the colour of the border while the box is disabled.

Value: The disabled border colour. The default is SystemColors.InactiveBorder.
Default: InactiveBorder

Remarks

Used while ExtendedState is true and OptimiseRedrawWhenDisabled is false. The control then fills the disabled box with the window colour and draws the text in SystemColors.GrayText, masked when TextBox.PasswordChar is set.

On some Windows themes SystemColors.InactiveBorder is white or nearly so, and the disabled border all but disappears; set this to BorderColorWhenControlIsNotInFocus's colour, or another visible one, to keep it.

BorderColorWhenControlIsNotInFocus

public Color BorderColorWhenControlIsNotInFocus

Gets or sets the border colour at rest – when the box has neither the focus nor the pointer over it – while ShowBorderAlways is false.

Value: The resting border colour. The default is SystemColors.ControlDark.

Remarks

With ShowBorderAlways true (the default) the border is always BorderColor and this colour is not used.

BorderStyle

public new BorderStyle BorderStyle

Gets the standard text box border style underneath the control's own frame; it cannot be set.

Value: Fixed3D, set by the constructor. The control draws its own frame over this edge, so the property is hidden from the Properties window and from IntelliSense.

DotBorderDepth

public int DotBorderDepth

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

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

Remarks

Used while DrawBorder is BorderState.Dotted. A value set while ExtendedState is false is ignored.

DotBorderGap

public int DotBorderGap

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

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

Remarks

A value set while ExtendedState is false is ignored.

DrawBorder

public BorderState DrawBorder

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

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

Remarks

A value set while ExtendedState is false is ignored, so set ExtendedState first.

Example

notesBox.DrawBorder = BorderState.Dotted;
notesBox.DotBorderDepth = 3;
notesBox.DotBorderGap = 2;

ExtendedState

public bool ExtendedState

Gets or sets whether the control draws its flat, coloured border, or keeps the classic sunken 3-D edge of a standard text box.

Value: true for the flat border; the default is true.

Remarks

While it is false, DrawBorder, DotBorderDepth, DotBorderGap and ShowBorderAlways ignore new values, and the border does not blink.

OptimiseRedrawWhenDisabled

public bool OptimiseRedrawWhenDisabled

Gets or sets whether the control skips its own drawing of the border and greyed text while the box is disabled.

Value: true to leave the disabled box to the standard text box's own drawing; false to draw the disabled look described under BorderColorWhenControlIsDisabled. The default is false.

Remarks

Set it on forms that disable and enable many boxes at once, where the extra drawing is not wanted.

ShowBorderAlways

public bool ShowBorderAlways

Gets or sets whether the border is always drawn in BorderColor, rather than only while the pointer is over the box or it has the focus.

Value: true for a constant border; false for the hover effect, with BorderColorWhenControlIsNotInFocus at rest. The default is true.

Remarks

A value set while ExtendedState is false is ignored. While the border is blinking it is held at true, and StopBlinking puts back the value it had before.

UseEnhancedPasswordChar

public bool UseEnhancedPasswordChar

Gets or sets whether a password box masks its text with round bullets (●) instead of its own TextBox.PasswordChar.

Value: true to use the round bullet; the default is false.

Remarks

Applies only when TextBox.PasswordChar is set, and not in the designer. While it is true, the control puts the bullet back each time it paints, so a different TextBox.PasswordChar assigned meanwhile does not last.

Setting it back to false restores the password character the bullet replaced. The text stays masked either way.

Example

var passwordBox = new BinaryExtendedText { PasswordChar = '*' };
passwordBox.UseEnhancedPasswordChar = true;   // shown as ●●●●●●

Methods

Dispose

protected override void Dispose(bool disposing)

Releases the resources the control holds, including the timer behind the blinking border.

Parameters

disposing: true when called from Dispose(), to release managed resources too; false when called from a finaliser.

OnGotFocus

protected override void OnGotFocus(EventArgs e)

Redraws the border for the box having the focus, and raises the Control.GotFocus event.

Parameters

e: The data for the event.

Remarks

The event is always raised. The border is redrawn only while ExtendedState is true and the box is enabled.

OnLostFocus

protected override void OnLostFocus(EventArgs e)

Redraws the border for the box losing the focus, and raises the Control.LostFocus event.

Parameters

e: The data for the event.

Remarks

The event is always raised. The border is redrawn only while ExtendedState is true and the box is enabled.

OnMouseEnter

protected override void OnMouseEnter(EventArgs e)

Redraws the border for the pointer being over the box, and raises the Control.MouseEnter event.

Parameters

e: The data for the event.

Remarks

The event is always raised. The border is redrawn only while ExtendedState is true and the box is enabled.

OnMouseLeave

protected override void OnMouseLeave(EventArgs e)

Redraws the border for the pointer leaving the box, and raises the Control.MouseLeave event.

Parameters

e: The data for the event.

Remarks

The event is always raised. The border is redrawn only while ExtendedState is true and the box is enabled.

StartToBlink

public void StartToBlink(Color BlinkColor)

Starts flashing the border between BlinkColor and BorderColor, every half second, until StopBlinking is called.

Parameters

BlinkColor: The colour the border flashes to – Color.Red or Color.Crimson to flag an error, say.

Remarks

Does nothing while ExtendedState is false or the box is disabled; a box disabled while blinking holds its colour until it is enabled again. Calling it while the border is already blinking restarts the blinking with the new colour.

The border is shown constantly while blinking (ShowBorderAlways is held at true).

StartToBlink

public void StartToBlink(Color BlinkColor, int BlinkInterval)

Starts flashing the border between BlinkColor and BorderColor at the given interval, until StopBlinking is called.

Parameters

BlinkColor: The colour the border flashes to.
BlinkInterval: The time each colour is shown, in milliseconds. Values below 1 are taken as 1.

Remarks

Behaves as StartToBlink() in every other respect.

Example

if (string.IsNullOrWhiteSpace(postcodeBox.Text))
{
    postcodeBox.StartToBlink(Color.OrangeRed, 300);
}

StopBlinking

public void StopBlinking()

Stops the border blinking and puts back the BorderColor and ShowBorderAlways it had when the blinking started.

Remarks

Does nothing when the border is not blinking.

WndProc

protected override void WndProc(ref Message m)

Processes the box's window messages, drawing the control's border – and, when disabled, its greyed text – after the standard text box has painted.

Parameters

m: The message to process.

BinaryExtendedText

Remarks

What it is for

The border

Blinking

Examples

See also

Members at a glance

Constructors

BinaryExtendedText

Properties

BorderColor

Remarks

See also

BorderColorWhenControlIsDisabled

Remarks

BorderColorWhenControlIsNotInFocus

Remarks

See also

BorderStyle

DotBorderDepth

Remarks

See also

DotBorderGap

Remarks

See also

DrawBorder

Remarks

Example

ExtendedState

Remarks

OptimiseRedrawWhenDisabled

Remarks

ShowBorderAlways

Remarks

UseEnhancedPasswordChar

Remarks

Example

Methods

Dispose

Parameters

OnGotFocus

Parameters

Remarks

OnLostFocus

Parameters

Remarks

OnMouseEnter

Parameters

Remarks

OnMouseLeave

Parameters

Remarks

StartToBlink

Parameters

Remarks

See also

StartToBlink

Parameters

Remarks

Example

StopBlinking

Remarks

See also

WndProc

Parameters