HypernovaDesktop Components · docs
Binarymission
WinForms › Watermark Text Box › WatermarkTextBox

WatermarkTextBox

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

A text box that shows a prompt – a line of grey or coloured text, with an optional picture – while it is empty, telling the user what to type: "Search orders", "Customer reference", "Notes for the courier".

public class WatermarkTextBox : Control

Inherits from / implements: Control

Remarks

What it is for

Use it in place of a TextBox wherever a label beside the box would take room the form does not have, or where a hint of the expected input helps more than a caption. The prompt – the watermark – disappears as soon as the user clicks into the box or the box holds text, and comes back when the box is left empty.

How it works

  • The control hosts an ordinary multi-line text box and, laid over it, a WatermarkProvider that draws the prompt. A click anywhere on the prompt hides it and puts the caret in the text box.
  • Text is the text the user typed; it follows the inner text box as the user types, and Control.TextChanged is raised for each change.
  • The prompt is shown when IsWatermarkEnabled is true, Text is empty and the control does not have the focus.

Appearance

WatermarkText, WatermarkTextFont, WatermarkTextForeColor and WatermarkBackColor style the prompt; WatermarkImage with ShouldRenderWatermarkImage adds a picture to the left of it. The control draws a one-pixel border in BorderColor round the box.

Important

The control clears Text when its window is created, so text assigned before the form is shown is discarded. Set initial text once the form is on screen – in the form's Form.Shown event, for example.

Examples

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

public class CourierNotesForm : Form
{
    private readonly WatermarkTextBox notesBox;
    private readonly Label characterCount;

    public CourierNotesForm()
    {
        Text = "Delivery instructions";
        ClientSize = new Size(420, 180);

        notesBox = new WatermarkTextBox
        {
            Location = new Point(12, 12),
            Size = new Size(396, 120),
            WatermarkText = "Notes for the courier - gate codes, safe places, opening hours",
            WatermarkTextForeColor = SystemColors.GrayText,
            WatermarkTextFont = new Font("Segoe UI", 9f, FontStyle.Italic),
            BorderColor = SystemColors.ControlDark,
            TextScrollBars = ScrollBars.Vertical
        };
        notesBox.TextChanged += (sender, e) =>
            characterCount.Text = notesBox.Text.Length + " / 500 characters";

        characterCount = new Label { Location = new Point(12, 142), AutoSize = true };

        Controls.Add(notesBox);
        Controls.Add(characterCount);
    }
}

See also

Members at a glance

Constructors
WatermarkTextBoxInitialises an empty watermark text box with the prompt "[Type your text here...]" in red italics of the control's font, a black border and a window-coloured background.
Properties
BorderColorGets or sets the colour of the one-pixel line drawn round the box.
IsWatermarkEnabledGets or sets whether the prompt is shown while the box is empty.
ShouldRenderWatermarkImageGets or sets whether the WatermarkImage is drawn to the left of the prompt text.
SiteGets or sets the site that ties the control to its container – set by the Windows Forms designer.
TextGets or sets the text in the box – what the user typed, never the prompt.
TextScrollBarsGets or sets which scroll bars the text box shows when its text is longer than the box.
WatermarkBackColorGets or sets the background colour behind the prompt while it is shown.
WatermarkImageGets or sets a picture drawn to the left of the prompt text – a magnifier on a search box, say.
WatermarkImageSizeGets or sets the size the watermark picture is drawn at, beside the prompt text.
WatermarkPaddingGets or sets the space between the edge of the box and the prompt.
WatermarkProviderGets or sets the child control that draws the prompt over the empty box.
WatermarkTextGets or sets the prompt shown while the box is empty – a hint of what to type, such as "Customer reference" or "Search by name or email".
WatermarkTextFontGets or sets the font the prompt text is drawn in.
WatermarkTextForeColorGets or sets the colour of the prompt text.
Methods
OnBackColorChangedRaises the Control.BackColorChanged event and gives the inner text box the new Control.BackColor.
OnGotFocusRaises the Control.GotFocus event and shows either the prompt or the text box, depending on whether there is text to show.
OnHandleCreatedRaises the Control.HandleCreated event.
OnLeaveRaises the Control.Leave event and puts the prompt back if the box is empty.
OnLostFocusRaises the Control.LostFocus event and puts the prompt back if the box is empty.
OnMouseUpRaises the Control.MouseUp event, hides the prompt and gives the inner text box the focus so the user can type.
OnPaintRaises the Control.Paint event, brings the prompt or the text box to the front as the state requires, and draws the border in BorderColor.
OnPaintBackgroundFills the control with its Control.BackColor.
OnResizeRaises the Control.Resize event and sizes the inner text box to fill the control inside the border.
OnSizeChangedRaises the Control.SizeChanged event and sizes the prompt to fill the control inside the border.

Constructors

WatermarkTextBox

public WatermarkTextBox()

Initialises an empty watermark text box with the prompt "[Type your text here...]" in red italics of the control's font, a black border and a window-coloured background.

Remarks

Set WatermarkText and WatermarkTextForeColor to something that suits the form; SystemColors.GrayText is the usual choice for the colour.

Properties

BorderColor

public Color BorderColor

Gets or sets the colour of the one-pixel line drawn round the box.

Value
The border colour. The default is Color.Black; SystemColors.ControlDark matches the standard Windows text box more closely.

IsWatermarkEnabled

public bool IsWatermarkEnabled

Gets or sets whether the prompt is shown while the box is empty.

Value
true to show WatermarkText in the empty box; false to behave as a plain text box. The default is true.
Remarks

When the change leaves the text box on show – it is set to false, the box has text, or the control has the focus – the inner text box takes the keyboard focus.

ShouldRenderWatermarkImage

public bool ShouldRenderWatermarkImage

Gets or sets whether the WatermarkImage is drawn to the left of the prompt text.

Value
true to draw the picture; false for a text-only prompt. The default is false.
Remarks

The picture appears only when this is true and WatermarkImage is set. With no picture the prompt text starts at the left edge.

Example
searchBox.WatermarkImage = Properties.Resources.Magnifier16;   // a 16 x 16 bitmap
searchBox.ShouldRenderWatermarkImage = true;
searchBox.WatermarkText = "Search by order number or postcode";
See also

Site

public override ISite Site

Gets or sets the site that ties the control to its container – set by the Windows Forms designer.

Value
The site, or null when the control is not sited. The default is null.
Remarks

In the designer the control watches for changes to its own Text and clears it at once, so the box always shows its watermark on the design surface. Set Text in code instead.

Text

public override string Text

Gets or sets the text in the box – what the user typed, never the prompt.

Value
The text. The default is an empty string.
Default
Remarks

The property follows the inner text box as the user types, raising Control.TextChanged for each change. Setting it in code replaces the box's text and hides the prompt when the text is not empty.

The control sets Text to an empty string when its window is created, and the designer clears it whenever it is changed there, so set the text in code after the form is shown.

TextScrollBars

public ScrollBars TextScrollBars

Gets or sets which scroll bars the text box shows when its text is longer than the box.

Value
One of the ScrollBars values. The default is None.
Remarks

The text box is multi-line, so Vertical is the useful setting for a notes or comments box.

WatermarkBackColor

public Color WatermarkBackColor

Gets or sets the background colour behind the prompt while it is shown.

Value
The prompt's background. The default is SystemColors.Window.
Remarks

Once the user starts typing, the box shows the control's own Control.BackColor; keep the two the same unless the empty box is meant to look different.

WatermarkImage

public Bitmap WatermarkImage

Gets or sets a picture drawn to the left of the prompt text – a magnifier on a search box, say.

Value
The picture, or null for none. The default is null.
Remarks

The picture is drawn only while ShouldRenderWatermarkImage is true. Setting this property also sets the drawn size to the image's own size (or to zero for null); set WatermarkImageSize afterwards to change it.

See also

WatermarkImageSize

public Size WatermarkImageSize

Gets or sets the size the watermark picture is drawn at, beside the prompt text.

Value
The width and height of the picture, in pixels. The image is stretched to fit. The default is Size.Empty.
Remarks

Setting WatermarkImage sizes the drawn picture to the image's own size, so set this property afterwards to draw it at another size. The getter returns only the last value assigned here, not the size taken from the image.

The size is applied as given; it is not scaled for the display's DPI.

See also

WatermarkPadding

public Padding WatermarkPadding

Gets or sets the space between the edge of the box and the prompt.

Value
The padding, in pixels, applied to the provider that draws the prompt. The default is Padding.Empty.

WatermarkProvider

public WatermarkProvider WatermarkProvider

Gets or sets the child control that draws the prompt over the empty box.

Value
The provider in use. The default is a WatermarkProvider the control creates for itself.
Remarks

Most applications leave this alone and style the prompt through WatermarkText, WatermarkTextFont, WatermarkTextForeColor and WatermarkBackColor, which the control copies to the provider each time it paints.

Assigning a provider takes the old one out of the control and adds the new one. The new provider is resized to fill the box when the control is next resized. Assigning null is ignored: the control keeps its provider.

WatermarkText

public string WatermarkText

Gets or sets the prompt shown while the box is empty – a hint of what to type, such as "Customer reference" or "Search by name or email".

Value
The prompt text. The default is "[Type your text here...]".
Default
Remarks

The prompt is shown while IsWatermarkEnabled is true, Text is empty and the control does not have the focus. It is never part of Text.

The designer's default value is an empty string, so the Properties window shows the built-in prompt as changed, and Reset sets the prompt to an empty string rather than to "[Type your text here...]".

Example
var referenceBox = new WatermarkTextBox
{
    WatermarkText = "Customer reference, e.g. ACC-10442",
    WatermarkTextForeColor = SystemColors.GrayText
};
See also

WatermarkTextFont

public Font WatermarkTextFont

Gets or sets the font the prompt text is drawn in.

Value
The prompt's font. The default is an italic version of the control's Control.Font at the time the control was created.
Remarks

The font of the text the user types is Control.Font; this one affects only the prompt.

See also

WatermarkTextForeColor

public Color WatermarkTextForeColor

Gets or sets the colour of the prompt text.

Value
The prompt's colour. The default is Color.Red; SystemColors.GrayText gives the conventional muted look.
Remarks

The colour of the text the user types is Control.ForeColor.

Methods

OnBackColorChanged

protected override void OnBackColorChanged(EventArgs e)

Raises the Control.BackColorChanged event and gives the inner text box the new Control.BackColor.

Parameters
e
The data for the event.
Remarks

A derived class that overrides this should call the base implementation.

OnGotFocus

protected override void OnGotFocus(EventArgs e)

Raises the Control.GotFocus event and shows either the prompt or the text box, depending on whether there is text to show.

Parameters
e
The data for the event.
Remarks

A derived class that overrides this should call the base implementation.

OnHandleCreated

protected override void OnHandleCreated(EventArgs e)

Raises the Control.HandleCreated event.

Parameters
e
The data for the event.
Remarks

A derived class that overrides this should call the base implementation.

OnLeave

protected override void OnLeave(EventArgs e)

Raises the Control.Leave event and puts the prompt back if the box is empty.

Parameters
e
The data for the event.
Remarks

A derived class that overrides this should call the base implementation.

OnLostFocus

protected override void OnLostFocus(EventArgs e)

Raises the Control.LostFocus event and puts the prompt back if the box is empty.

Parameters
e
The data for the event.
Remarks

A derived class that overrides this should call the base implementation.

OnMouseUp

protected override void OnMouseUp(MouseEventArgs e)

Raises the Control.MouseUp event, hides the prompt and gives the inner text box the focus so the user can type.

Parameters
e
The mouse button and position.
Remarks

A derived class that overrides this should call the base implementation.

OnPaint

protected override void OnPaint(PaintEventArgs e)

Raises the Control.Paint event, brings the prompt or the text box to the front as the state requires, and draws the border in BorderColor.

Parameters
e
The graphics surface and the area to paint.
Remarks

A derived class that overrides this should call the base implementation.

OnPaintBackground

protected override void OnPaintBackground(PaintEventArgs pevent)

Fills the control with its Control.BackColor.

Parameters
pevent
The graphics surface and the area to fill.
Remarks

The base implementation is not called, so the Control.BackgroundImage is not drawn.

OnResize

protected override void OnResize(EventArgs e)

Raises the Control.Resize event and sizes the inner text box to fill the control inside the border.

Parameters
e
The data for the event.
Remarks

A derived class that overrides this should call the base implementation.

OnSizeChanged

protected override void OnSizeChanged(EventArgs e)

Raises the Control.SizeChanged event and sizes the prompt to fill the control inside the border.

Parameters
e
The data for the event.
Remarks

A derived class that overrides this should call the base implementation.