.NET 4.0+

WPF Text Input Controls - TextBox

by Richard Carr, published at http://www.blackwasp.co.uk/WPFTextBox.aspx

The forty-eighth part of the Windows Presentation Foundation Fundamentals tutorial begins an examination of the WPF controls that allow users to enter text. The first such control is the TextBox, which allows unformatted text input.

TextBox

Almost all business applications require the input of text. When a small amount of plain text is required, you can use the TextBox control. WPF TextBoxes let the user input a single line of text, or can be used for multiline editing. You can also place restrictions on the information entered, such as limiting the length or the character casing of the information provided.

The TextBox control is a complex one with many members. We won't examine at them all in this tutorial. However, we will look at some of the more commonly used methods, properties and events. In this article we'll perform some basic input for a single line of text. In the next few instalments we'll extend this with multiline text, styling and some other TextBox features.

To demonstrate the basic use of a TextBox we need an example project. Create a new WPF Application project in Visual Studio, naming the solution, "TextBoxDemo". Once loaded, replace the XAML of the main window with the code below:

<Window x:Class="TextBoxDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="TextBox Demo"
        Height="200"
        Width="250">
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition/>
            <RowDefinition/>
            <RowDefinition/>
            <RowDefinition/>
        </Grid.RowDefinitions>

        <Label Content="Enter some text" Margin="5"/>
        <TextBox Grid.Row="1" Name="MyTextBox" Margin="5"/>
        <Button Grid.Row="2" Content="OK" Margin="5"/>
        <Label Grid.Row="3" Name="MyLabel" Margin="5"/>
    </Grid>
</Window>

The above XAML creates a window containing a TextBox and a few other controls. The window appears as shown below:

Text Property

The most important member of the TextBox class is the Text property. This string property holds the text that is currently displayed in the control. You can set it via the XAML or by assigning the property from code. Any changes are reflected in the control's user interface. Reading the property allows you to access the text entered by a user.

To demonstrate, we'll initialise the Text property in the XAML, then read it from C# code. Start by modifying the TextBox's XAML as shown below. This sets the text to "Hello, world!". If you are using the XAML designer in Visual Studio you should see the rendered window update. If not, run the program to see the results.

<TextBox Grid.Row="1" Name="MyTextBox" Margin="5" Text="Hello, world!"/>

We'll modify the text in the control within the Click event of the button. Modify the XAML for the button to register the event:

<Button Grid.Row="2" Content="OK" Margin="5" Click="Button_Click"/>

You can now change the code for the event. The code below changes the content of the lower Label to match the text in the TextBox when you click the button.

private void Button_Click(object sender, RoutedEventArgs e)
{
    MyLabel.Content = MyTextBox.Text;
}

Run the program to see the results. Try entering text into the TextBox and clicking the Button to see how the string is obtained.

Clearing the Text

Sometimes it is necessary to clear the text from a TextBox. You can achieve this by setting the Text property to an empty string. Alternatively you can call the Clear method for the same effect. Some would see this as more readable code.

Modify the Button's Click event code as shown below. This clears the TextBox after copying its contents into the Label.

private void Button_Click(object sender, RoutedEventArgs e)
{
    MyLabel.Content = MyTextBox.Text;
    MyTextBox.Clear();
}

Run the program again to see the results.