BlackWaspTM

This web site uses cookies. By using the site you accept the cookie policy.This message is for compliance with the UK ICO law.

Windows Presentation Foundation
.NET 4.0+

WPF Text Input Controls - TextBox - Multiline

The fifty-first part of the Windows Presentation Foundation Fundamentals tutorial continues to describe the TextBox control. This instalment looks at the properties and methods used when working with TextBoxes with multiple lines of text.

TextBox

The last few articles in this tutorial have considered the use of the TextBox control. This WPF control is used to request plain text from the user. We've seen how to add a TextBox to a window, how to determine and change the selected text and some of the TextBox styling options. In this article we'll expand upon this functionality by looking at multiline TextBoxes, which allow several lines of plain text to be edited.

To demonstrate, we need a basic WPF project to work with. Create a new WPF application project in Visual Studio, naming the solution, "TextBoxMultilineDemo". Once loaded, replace the XAML in the automatically generated window with the code below:

<Window x:Class="TextBoxMultilineDemo.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 Height="Auto"/>
        </Grid.RowDefinitions>

        <TextBox Name="MyTextBox" Margin="5" />
        
        <StackPanel Grid.Row="1"
                    Orientation="Horizontal"
                    HorizontalAlignment="Right">
            <Button Content="Info" Width="75" Margin="0 0 5 5"/>
            <Button Content="Move" Width="75" Margin="0 0 5 5"/>
        </StackPanel>
    </Grid>
</Window>

The above XAML defines a window that contains a TextBox and two buttons. So far, the TextBox does not support multiple lines of text. If you type more text than will fit in the horizontal area, the content scrolls horizontally and some characters are hidden, as shown below:

WPF Multiline TextBox Demo Window

TextBox Wrapping

To change the TextBox to be multiline, you can alter the way that text is wrapped within the control's area. This is achieved using the TextWrapping property. There are three options for the property, each defined by the TextWrapping enumeration. The options are:

  • NoWrap. The default option is for no text wrapping. All of the text in the TextBox appears on a single line.
  • Wrap. Setting the TextWrapping property to Wrap generates a multiline TextBox. When more text is entered that can fit within the width of the TextBox, it is wrapped onto the next line. The algorithm used to perform text wrapping looks for characters such as white space to determine the position at which to start new lines. If no suitable splitting point is found, the text wraps at the edge of the control.
  • WrapWithOverflow. This option is similar to Wrap but the algorithm that defines the wrapping point is slightly different. As before, if possible the text wraps at a white space character. If no such character exists, the text will continue beyond the boundary of the TextBox

Let's modify the TextBox XAML to add wrapping:

<TextBox Name="MyTextBox" Margin="5" TextWrapping="Wrap" />

As we've used the Wrap option, new lines start at white space characters if possible but words that are too long to fit within the width of the control are split over several lines. This is shown below:

WPF Multiline TextBox

Carriage Returns and Tabs

If you run the example code and press the Enter key whilst the TextBox has the focus, you will find that a carriage return is not added; the key press has no effect. You'll also find that pressing the tab key does not insert a tab. As you might expect, the focus simply moves to the next control in the tab order.

Often it is useful to permit the insertion of carriage returns in a multiline textbox, or to allow text to be aligned with tabs. You can enable these two control characters with two properties. Set AcceptsReturn and AcceptsTab to true to accept carriage returns and tabs respectively.

To demonstrate, modify the XAML of the TextBox:

<TextBox Name="MyTextBox" AcceptsReturn="True" AcceptsTab="True"
         Margin="5" TextWrapping="Wrap" />

You can now use the Enter and Tab keys to insert text, allowing input such as the following:

WPF TextBox with Tabs and Returns

2 March 2014