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.

Limiting the Number of Visible Lines

In the sample project the TextBox is placed within a Grid cell, so expands to fill the available area by default. If you use an alternative vertical alignment for the TextBox and do not specify a height, the control will be tall enough for a single line of text. As the number of lines increases, the TextBox enlarges accordingly.

To avoid this behaviour, you can set the minimum and maximum number of lines of text that can be visible at any time, using the MinLines and MaxLines properties. Set the two properties to the same value to fix the number of visible lines. In any case, this only affects the number of visible lines. Entering further text causes some of the content of the TextBox to scroll out of view.

To demonstrate, change the XAML for the TextBox, as follows:

<TextBox Name="MyTextBox" AcceptsReturn="True" AcceptsTab="True"
         MinLines="2" MaxLines="4" VerticalAlignment="Top"
         Margin="5" TextWrapping="Wrap" />

The updated control specifies that a minimum of two lines and a maximum of four are visible at any time. As there is no default text, the control starts with space for two lines. As you add text, the TextBox grows.

WPF TextBox with MinLines and MaxLines set

Determining the Number of Lines

Sometimes it is useful to know how many lines of text are present in a TextBox. This can be found by reading the LineCount property. This member returns an integer value. To see this in action, start by registering a Click event for the Info button:

<Button Content="Info" Width="75" Margin="0 0 5 5" Click="Info_Click"/>

We can show the number of lines of text in a message box when you click the button. Add the following code behind the window:

private void Info_Click(object sender, RoutedEventArgs e)
    MessageBox.Show("Line count: " + MyTextBox.LineCount.ToString());

Run the program, enter some lines of text and click the Info button to see the results.

Vertical Scrolling

When you provide a multiline TextBox, it is likely that vertical scrolling will be required. By default, a vertical scroll bar is not present and the TextBox only scrolls if the cursor is moved into a hidden area. However, you can elect to add a vertical scroll bar to the control using the VerticalScrollBarVisibility property. You set this to a value from the ScrollBarVisibility enumeration. Four options are available:

  • Hidden. The default option of Hidden allows scrolling by moving the cursor but displays no scroll bar.
  • Visible. When set to Visible, the TextBox always displays a vertical scroll bar, even if scrolling is not possible.
  • Auto. The Auto setting hides the scroll bar when there is insufficient text to require scrolling. When the text extends beyond the top or bottom of the visible area, the scroll bar appears automatically.
  • Disabled. If you set the value to Disabled, no scroll bar is shown. In addition, vertical scrolling is disabled.

Modify the TextBox as shown below to set the vertical scroll bar visibility to automatic:

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

Run the program to test the new setting. Initially no scroll bar will be visible. Once you type enough characters to require scrolling, the bar appears:

WPF TextBox with automatic scrolling

If you need to determine the amount by which the text has been scrolled, you can read the VerticalOffset property. This returns a double-precision floating point number that represents the number of device independent units by which the text has been scrolled. A value of zero indicates that the very top of the TextBox's content is visible.

To demonstrate the property, modify the code for the Info button's Click event, as shown below. Run the program and click the button to see both the line count and the amount of scrolling.

private void Info_Click(object sender, RoutedEventArgs e)
    int count = MyTextBox.LineCount;
    double offset = MyTextBox.VerticalOffset;
    string msg = string.Format("Line count: {0}\nOffset: {1}", count, offset);

Scrolling Programmatically

You can set the VerticalOffset to scroll the content of the TextBox to a specific position. Although this is accurate, its use is somewhat limited. More commonly you will want to scroll a TextBox's content in order to make a specific line of text visible. You can achieve this using the ScrollToLine method.

ScrollToLine has a single parameter, which accepts an integer value. This value is the line number that you wish to show, where line zero is the first line of text. If the line of text is already visible, the TextBox does not scroll. If it is out of view, the content is scrolled by the minimum amount necessary in order to display the line.

To show the use of the method, add a Click event to the Move button, as follows:

<Button Content="Move" Width="75" Margin="0 0 5 5" Click="Move_Click"/>

Add the following code behind the window. This scrolls the TextBox to show the eleventh line of text.

private void Move_Click(object sender, RoutedEventArgs e)
2 March 2014