Features

The most important properties of the RadWatermarkTextBox control are:

  • WatermarkContent: Gets or sets the content to be shown when the TextBox is empty and not focused.

  • WatermarkTemplate: Gets or sets the template for presenting the content, shown when the TextBox is empty and not focused.

  • CurrentText: Gets or sets the text of the TextBox. This property is meant to be used for TwoWay binding in order to be updated on each change of the text and not when the focus is lost.

  • IsWatermarkVisible: A read-only property indicating whether the Watermark is visible or not.

  • SelectionOnFocus: Specifies the modification over the selection when the control receives focus. The values for this properties are predefined in the SelectionOnFocus enumeration, which exposes the following fields:

    • Unchanged: Selection will not be modified.

    • SelectAll: The whole text will be selected.

    • CaretToBeginning: The caret will be moved at the start of the text.

    • CaretToEnd: The caret will be moved at the end of the text.

The RadWatermarkTextBox control is part of the Telerik.Windows.Controls.dll assembly.

Using the WatermarkContent Property

In scenarios, where you want to show custom content, when an empty string is entered, you need to use the WatermarkContent property.

In the following example, the user is asked to enter four digits:

Example 1: Setting the WatermarkContent property

<telerik:RadWatermarkTextBox x:Name="radWatermarkTextBox" WatermarkContent="Please Enter Four Digits:" /> 

Figure 1: RadWatermarkTextBox with watermark text

RadWatermarkTextBox with watermark text

The WatermarkContent property is of type object. Which means that you can set anything you want. For example:

Example 2: Defining custom content for the WatermarkContent property

<telerik:RadWatermarkTextBox x:Name="radWatermarkTextBox1"> 
    <telerik:RadWatermarkTextBox.WatermarkContent> 
        <StackPanel Orientation="Horizontal"> 
            <Image Source="/Silverlight.Help.RadMaskedTextBox;component/Images/EURFlag.png" /> 
            <TextBlock Margin="3,0,0,0" Text="Please Enter Four Digits" /> 
        </StackPanel> 
    </telerik:RadWatermarkTextBox.WatermarkContent> 
</telerik:RadWatermarkTextBox> 

Figure 2: RadWatermarkTextBox with custom watermark content

RadWatermarkTextBox with custom watermark content

Using WatermarkTemplate Property

Similarly, you can use the WatermarkTemplate property for the same sort of scenarios. Note that in this case you should define a new DataTemplate for the WatermarkTemplate property.

Example 3: Defining the WatermarkTemplate

<telerik:RadWatermarkTextBox x:Name="radWatermarkTextBox2"> 
    <telerik:RadWatermarkTextBox.WatermarkTemplate> 
        <DataTemplate> 
            <StackPanel Orientation="Horizontal"> 
                <Image Source="/Silverlight.Help.RadMaskedTextBox;component/Images/EURFlag.png" /> 
                <TextBlock Margin="3,0,0,0" Text="Please Enter Four Digits" /> 
            </StackPanel> 
        </DataTemplate> 
    </telerik:RadWatermarkTextBox.WatermarkTemplate> 
</telerik:RadWatermarkTextBox> 

Figure 3: RadWatermarkTextBox with custom WatermarkTemplate

RadWatermarkTextBox with custom WatermarkTemplate

Setting the SelectionOnFocus Property

The SelectionOnFocus property of RadWatermarkTextBox allows you to specify what will happen with the cursor when the control gets focus. In the following example the SelectionOnFocus property is set to SelectAll. Once the RadWatermarkTextBox gets focused, it will select its whole text.

Example 4: Setting the SelectionOnFocus property

<telerik:RadWatermarkTextBox x:Name="radWatermarkTextBox3"  
                             SelectionOnFocus="SelectAll" 
                             WatermarkContent="Please Enter Four Digits:" /> 

WatermarkBehavior

WatermarkBehavior is an enumeration property which specifies when the watermark content of RadWatermarkTextBox will be hidden. It could receive the following values:

  • HiddenWhenFocused - The watermark will be hidden when the RadWatermarkTextBox receives focus
  • HideOnClick - The watermark will be hidden when the the user clicks on the RadWatermarkTextBox
  • HideOnTextEntered - The watermark will be hidden when the the user writes text into the RadWatermarkTextBox

The default value is HideOnTextEntered.

ReadOnlyBackground and DisabledBackground

As of R1 2019, the RadWatermarkTextBox control exposes two new properties to set its background when it is disabled or read-only, namely DisabledBackground and ReadOnlyBackground respectively.

Examples 5 and 6 demonstrate how to set these properties in XAML and figures 4 and 5 illustrate the respective results in the Office2016 theme.

Example 5: Setting the DisabledBackground property

    <telerik:RadWatermarkTextBox WatermarkContent="Please Enter Four Digits:" IsEnabled="False" DisabledBackground="DarkGray" /> 

Figure 4: Disabled RadWatermarkTextBox with and without DisabledBackground

Disabled RadWatermarkTextBox with and without DisabledBackground

Example 6: Setting the ReadOnlyBackground property

    <telerik:RadWatermarkTextBox WatermarkContent="Please Enter Four Digits:" IsReadOnly="True" ReadOnlyBackground="DarkGray" /> 

Figure 5: Read-only RadWatermarkTextBox with and without ReadOnlyBackground

Read-only RadWatermarkTextBox with and without ReadOnlyBackground

Please note that the read-only visual is drawn over the disabled visual so the ReadOnlyBackground will take precedence over the DisabledBackground if the control is in both the disabled and read-only states.

See also

Overview

In this article
Not finding the help you need? Improve this article