SmartTextBox

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

A text box with a watermark prompt, a button that clears it, an optional flag that shows whether a required value has been given, and a filter on what can be typed.

public class SmartTextBox : TextBox

Inherits from / implements: TextBox

Remarks

It is a TextBox, so TextBox.Text, binding, validation and the keyboard all work as usual; it adds four things.

A watermark. WatermarkContent – "Search orders", "Customer reference" – is shown in grey while the box is empty and does not have the focus.
A clear button. A small "X" at the right-hand end empties the box with one click. It is shown while there is text to clear (IsClearTextVisualRenderingFeatureEnabled, IsClearTextVisualAlwaysVisible), and can show any content (ClearTextVisualContent).
An alert flag. With IsAlertClueImageRenderingEnabled on, a small picture sits over the box's top right corner: AlertClueImageSourceOnError while the box is empty, AlertClueImageSource once something has been entered – a red flag that turns to a green tick on a required field.
An input filter. DataEntryMode can limit the box to the digits 0 to 9, or refuse whatever a regular expression of your own matches (DisallowedInputRegularExpression). The filter applies to typing and to pasting; a paste holding anything that would be refused is refused whole.

The colours of the watermark, the clear button and the border come from the theme; while a Binarymission skin is applied through BinarySkinManager it supplies them, and a brush set on the box itself still wins.

Examples

A required reference field and a quantity field. The assembly is Binarymission.WPF.Controls.SmartTextBox.

<Window x:Class="Orders.NewOrderWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:smart="clr-namespace:Binarymission.WPF.Controls.InputControls;assembly=Binarymission.WPF.Controls.SmartTextBox"
        Title="New order" Width="420" Height="200">

    <Window.Resources>
        <BitmapImage x:Key="RequiredFlag" UriSource="/Images/Required.png" />
        <BitmapImage x:Key="DoneTick" UriSource="/Images/Done.png" />
    </Window.Resources>

    <StackPanel Margin="16">
        <smart:SmartTextBox Width="240" Height="26" HorizontalAlignment="Left"
                            WatermarkContent="Customer reference"
                            Text="{Binding CustomerReference, UpdateSourceTrigger=PropertyChanged}"
                            DataEntryMode="None"
                            DisallowedInputRegularExpression="[^A-Za-z0-9-]"
                            IsAlertClueImageRenderingEnabled="True"
                            AlertClueImageSourceOnError="{StaticResource RequiredFlag}"
                            AlertClueImageSource="{StaticResource DoneTick}"
                            AlertFlagToolTipContent="A customer reference is required." />

        <smart:SmartTextBox Width="100" Height="26" Margin="0,12,0,0" HorizontalAlignment="Left"
                            WatermarkContent="Quantity"
                            DataEntryMode="NumericOnly" />
    </StackPanel>
</Window>

Members at a glance

Constructors
`SmartTextBox`	Creates an empty text box that accepts any text, with the clear button on and no watermark.
Properties
`AlertClueImageSource`	Gets or sets the picture the alert flag shows once the box has text in it – a green tick, say.
`AlertClueImageSourceOnError`	Gets or sets the picture the alert flag shows while the box is empty – a red flag on a field that must be filled in, say.
`AlertFlagToolTipContent`	Gets or sets the tooltip shown when the pointer rests on the alert flag – what the field needs, or why it is flagged.
`ClearTextVisualContent`	Gets or sets what the clear button at the right-hand end of the box shows.
`ClearTextVisualForeground`	Gets or sets the colour of the clear button's "X" while the text box is disabled.
`ClearTextVisualOnHoverForeground`	Gets or sets the colour of the clear button's "X" while the pointer is over it, warning that a click will empty the box.
`DataEntryMode`	Gets or sets what the user may type or paste into the box.
`DisallowedInputRegularExpression`	Gets or sets a regular expression matching the input to refuse, when `DataEntryMode` is `SmartTextBoxDataEntryMode.None`.
`IsAlertClueImageRenderingEnabled`	Gets or sets whether the alert flag is shown over the box's top right corner.
`IsClearTextVisualAlwaysVisible`	Gets or sets whether the clear button is shown even while the box is empty.
`IsClearTextVisualRenderingFeatureEnabled`	Gets or sets whether the box has a clear button at all.
`WatermarkContent`	Gets or sets the prompt shown in the empty box – what to type there.
`WatermarkContentTemplate`	Gets or sets the template the watermark is drawn with.
Methods
`OnApplyTemplate`	Finds the parts of the template – the clear button `PART_ClearTextVisual`, the alert flag `PART_AlertClueImage` and the watermark `PART_WatermarkContent` – and sets their state.
Fields
`AlertClueImageSourceOnErrorProperty`	Identifies the `AlertClueImageSourceOnError` dependency property.
`AlertClueImageSourceProperty`	Identifies the `AlertClueImageSource` dependency property.
`AlertFlagToolTipContentProperty`	Identifies the `AlertFlagToolTipContent` dependency property.
`ClearTextVisualContentProperty`	Identifies the `ClearTextVisualContent` dependency property.
`ClearTextVisualForegroundProperty`	Identifies the `ClearTextVisualForeground` dependency property.
`ClearTextVisualOnHoverForegroundProperty`	Identifies the `ClearTextVisualOnHoverForeground` dependency property.
`DataEntryModeProperty`	Identifies the `DataEntryMode` dependency property.
`DisallowedInputRegularExpressionProperty`	Identifies the `DisallowedInputRegularExpression` dependency property.
`IsAlertClueImageRenderingEnabledProperty`	Identifies the `IsAlertClueImageRenderingEnabled` dependency property.
`IsClearTextVisualAlwaysVisibleProperty`	Identifies the `IsClearTextVisualAlwaysVisible` dependency property.
`IsClearTextVisualRenderingFeatureEnabledProperty`	Identifies the `IsClearTextVisualRenderingFeatureEnabled` dependency property.
`WatermarkContentProperty`	Identifies the `WatermarkContent` dependency property.
`WatermarkContentTemplateProperty`	Identifies the `WatermarkContentTemplate` dependency property.

Constructors

SmartTextBox

public SmartTextBox()

Creates an empty text box that accepts any text, with the clear button on and no watermark.

Properties

AlertClueImageSource

public BitmapSource AlertClueImageSource

Gets or sets the picture the alert flag shows once the box has text in it – a green tick, say.

Value: The picture, drawn 12 logical pixels square. The default is null: no flag while the box has text.

Remarks

Shown only while IsAlertClueImageRenderingEnabled is true.

AlertClueImageSourceOnError

public BitmapSource AlertClueImageSourceOnError

Gets or sets the picture the alert flag shows while the box is empty – a red flag on a field that must be filled in, say.

Value: The picture, drawn 12 logical pixels square. The default is null: no flag while the box is empty.

Remarks

Shown only while IsAlertClueImageRenderingEnabled is true.

AlertFlagToolTipContent

public object AlertFlagToolTipContent

Gets or sets the tooltip shown when the pointer rests on the alert flag – what the field needs, or why it is flagged.

Value: Any content: text, or an element. The default is null: no tooltip.

ClearTextVisualContent

public object ClearTextVisualContent

Gets or sets what the clear button at the right-hand end of the box shows.

Value: Any content – text, a symbol, a small picture. The default is the text " X ", in bold.

Remarks

Text is drawn in the box's Control.FontSize.

Example

<smart:SmartTextBox WatermarkContent="Search invoices" ClearTextVisualContent="&#x2715;" />

ClearTextVisualForeground

public Brush ClearTextVisualForeground

Gets or sets the colour of the clear button's "X" while the text box is disabled.

Value: The default with no skin in force is the system window text colour; a Binarymission skin supplies its own.

Remarks

The built-in template uses it only while the box is disabled, when the "X" is also drawn faint. At rest the "X" takes the box's Control.Foreground, and under the pointer ClearTextVisualOnHoverForeground.

ClearTextVisualOnHoverForeground

public Brush ClearTextVisualOnHoverForeground

Gets or sets the colour of the clear button's "X" while the pointer is over it, warning that a click will empty the box.

Value: The default with no skin in force is Red; a Binarymission skin supplies its own.

DataEntryMode

public SmartTextBoxDataEntryMode DataEntryMode

Gets or sets what the user may type or paste into the box.

Value: The default is SmartTextBoxDataEntryMode.AlphaNumeric, which accepts any text. SmartTextBoxDataEntryMode.NumericOnly accepts only the digits 0 to 9, and SmartTextBoxDataEntryMode.None refuses whatever DisallowedInputRegularExpression matches.

Remarks

Refused typing is simply ignored. A paste is refused whole if any part of it would be refused. Text set from code or by a binding is not filtered, and nor is text dragged and dropped onto the box: set UIElement.AllowDrop to false if that matters.

Example

<smart:SmartTextBox WatermarkContent="PIN" DataEntryMode="NumericOnly" MaxLength="6" />

DisallowedInputRegularExpression

public string DisallowedInputRegularExpression

Gets or sets a regular expression matching the input to refuse, when DataEntryMode is SmartTextBoxDataEntryMode.None.

Value: A .NET regular expression. The default is null; null or empty refuses nothing.

Remarks

It is tested against each piece of text as it is typed – usually one character – and against the whole of a paste; input in which it finds a match is refused. So write it to match one unwanted character: [^A-Za-z0-9-] allows only letters, digits and hyphens, and \s refuses spaces.

It is ignored in the other two modes. An expression that is not valid throws an ArgumentException when the first character is typed.

IsAlertClueImageRenderingEnabled

public bool IsAlertClueImageRenderingEnabled

Gets or sets whether the alert flag is shown over the box's top right corner.

Value: true to show it; the default is false.

Remarks

The flag is a picture 12 logical pixels square. While the box is empty it shows AlertClueImageSourceOnError, and once anything has been entered, AlertClueImageSource; it changes as the user types. Leave either picture null to show nothing in that state – a flag only while a required field is empty, say.

IsClearTextVisualAlwaysVisible

public bool IsClearTextVisualAlwaysVisible

Gets or sets whether the clear button is shown even while the box is empty.

Value: true to show it always; the default is false, which shows it only while there is text to clear.

Remarks

Has no effect while IsClearTextVisualRenderingFeatureEnabled is false. Showing it always keeps the text from shifting when the button appears.

IsClearTextVisualRenderingFeatureEnabled

public bool IsClearTextVisualRenderingFeatureEnabled

Gets or sets whether the box has a clear button at all.

Value: true, the default, to show the button while there is text to clear; false never to show it.

WatermarkContent

public object WatermarkContent

Gets or sets the prompt shown in the empty box – what to type there.

Value: Any content: usually text such as "Search orders" or "Postcode", or an element – an icon and text in a StackPanel, say. The default is null: no watermark.

Remarks

Shown while the box is empty and does not have the focus, lined up with where the text will start; it cannot be clicked or selected. Text is drawn in grey by the default WatermarkContentTemplate.

Example

<smart:SmartTextBox Width="260">
    <smart:SmartTextBox.WatermarkContent>
        <StackPanel Orientation="Horizontal">
            <Image Source="/Images/Search.png" Width="14" Height="14" Margin="0,0,4,0" />
            <TextBlock Text="Search orders" FontStyle="Italic" />
        </StackPanel>
    </smart:SmartTextBox.WatermarkContent>
</smart:SmartTextBox>

WatermarkContentTemplate

public DataTemplate WatermarkContentTemplate

Gets or sets the template the watermark is drawn with.

Value: The control's style sets a template that shows WatermarkContent in grey (the skin's secondary text colour while a Binarymission skin is in force).

Remarks

A template of your own replaces the grey too, so set the colour in it. Its data context is WatermarkContent.

Example

<smart:SmartTextBox WatermarkContent="Required">
    <smart:SmartTextBox.WatermarkContentTemplate>
        <DataTemplate>
            <TextBlock Text="{Binding}" Foreground="IndianRed" FontStyle="Italic" />
        </DataTemplate>
    </smart:SmartTextBox.WatermarkContentTemplate>
</smart:SmartTextBox>

Methods

OnApplyTemplate

public override void OnApplyTemplate()

Finds the parts of the template – the clear button PART_ClearTextVisual, the alert flag PART_AlertClueImage and the watermark PART_WatermarkContent – and sets their state.

Remarks

A template of your own needs a Button, an Image and a ContentPresenter with those names for the matching feature to work; any can be left out.

Fields

AlertClueImageSourceOnErrorProperty static

public static readonly DependencyProperty AlertClueImageSourceOnErrorProperty

Identifies the AlertClueImageSourceOnError dependency property.

AlertClueImageSourceProperty static

public static readonly DependencyProperty AlertClueImageSourceProperty

Identifies the AlertClueImageSource dependency property.

AlertFlagToolTipContentProperty static

public static readonly DependencyProperty AlertFlagToolTipContentProperty

Identifies the AlertFlagToolTipContent dependency property.

ClearTextVisualContentProperty static

public static readonly DependencyProperty ClearTextVisualContentProperty

Identifies the ClearTextVisualContent dependency property.

ClearTextVisualForegroundProperty static

public static readonly DependencyProperty ClearTextVisualForegroundProperty

Identifies the ClearTextVisualForeground dependency property.

ClearTextVisualOnHoverForegroundProperty static

public static readonly DependencyProperty ClearTextVisualOnHoverForegroundProperty

Identifies the ClearTextVisualOnHoverForeground dependency property.

DataEntryModeProperty static

public static readonly DependencyProperty DataEntryModeProperty

Identifies the DataEntryMode dependency property.

DisallowedInputRegularExpressionProperty static

public static readonly DependencyProperty DisallowedInputRegularExpressionProperty

Identifies the DisallowedInputRegularExpression dependency property.

IsAlertClueImageRenderingEnabledProperty static

public static readonly DependencyProperty IsAlertClueImageRenderingEnabledProperty

Identifies the IsAlertClueImageRenderingEnabled dependency property.

IsClearTextVisualAlwaysVisibleProperty static

public static readonly DependencyProperty IsClearTextVisualAlwaysVisibleProperty

Identifies the IsClearTextVisualAlwaysVisible dependency property.

IsClearTextVisualRenderingFeatureEnabledProperty static

public static readonly DependencyProperty IsClearTextVisualRenderingFeatureEnabledProperty

Identifies the IsClearTextVisualRenderingFeatureEnabled dependency property.

WatermarkContentProperty static

public static readonly DependencyProperty WatermarkContentProperty

Identifies the WatermarkContent dependency property.

WatermarkContentTemplateProperty static

public static readonly DependencyProperty WatermarkContentTemplateProperty

Identifies the WatermarkContentTemplate dependency property.

SmartTextBox

Remarks

Examples

See also

Members at a glance

Constructors

SmartTextBox

Properties

AlertClueImageSource

Remarks

See also

AlertClueImageSourceOnError

Remarks

See also

AlertFlagToolTipContent

See also

ClearTextVisualContent

Remarks

Example

ClearTextVisualForeground

Remarks

ClearTextVisualOnHoverForeground

See also

DataEntryMode

Remarks

Example

DisallowedInputRegularExpression

Remarks

IsAlertClueImageRenderingEnabled

Remarks

IsClearTextVisualAlwaysVisible

Remarks

IsClearTextVisualRenderingFeatureEnabled

See also

WatermarkContent

Remarks

Example

WatermarkContentTemplate

Remarks

Example

Methods

OnApplyTemplate

Remarks

Fields

AlertClueImageSourceOnErrorProperty static

AlertClueImageSourceProperty static

AlertFlagToolTipContentProperty static

ClearTextVisualContentProperty static

ClearTextVisualForegroundProperty static

ClearTextVisualOnHoverForegroundProperty static

DataEntryModeProperty static

DisallowedInputRegularExpressionProperty static

IsAlertClueImageRenderingEnabledProperty static

IsClearTextVisualAlwaysVisibleProperty static

IsClearTextVisualRenderingFeatureEnabledProperty static

WatermarkContentProperty static

WatermarkContentTemplateProperty static