Using the TextBox Class

Using the TextBox Class

Other commonly used controls include the text box control, the list box control, and the combo box control. Although these controls present a different appearance than the button controls described earlier in this chapter, they share many of the same characteristics. Many of the properties exposed by button controls are used with other controls, and most events raised by the button control are also raised by the controls we’ll examine in this section and the following sections.

The text box control is used to create a standard Windows edit control, also known as a text box. The text box control is most often used to accept text input from the user and is probably the most commonly used control after the ubiquitous push button control. The TextBox class is used to manage text box controls and is a subclass of the TextBoxBase class. The TextBoxBase class serves as the parent class for the TextBox and RichTextBox classes and contains the properties and methods common to all text input controls. (The RichTextBox class will be discussed in Chapter 15.)

The text entered in a text box control by the user is available through the Text property, as shown here:

string newItem = itemTextBox.Text;
int itemLength = itemTextBox.TextLength;

As shown in this example, you can retrieve the length of the text stored in the text box control by using the TextLength property. You also can set the text ­displayed in the control by assigning a string value to the Text property of the TextBox instance, as shown here:

itemTextBox.Text = "Elvis has left the building";

To remove the text in a text box control, call the TextBox.Clear method, as shown here:


In addition to the Clear method, the TextBox class also offers full support for interaction with the clipboard, including the ability to cut, copy, and paste. Using the cut and paste functions exposed by the TextBox class is discussed in Chapter 17.

The text box control exposes the TextChanged event, which is raised each time the text in the control is changed. This event is useful when another control must be updated based on the current contents of the text box, as shown here:

public TextBoxForm()

    textBox.TextChanged += new EventHandler(textBox_TextChanged);
private void textBox_TextChanged(object sender, System.EventArgs e)
    label.Text = "Contents: " + textBox.Text;

In this example, the value of the label control is updated whenever the contents of the textBox control are updated.

Hiding Passwords in a Text Box Control

When a password or other sensitive information is entered in a text box control, the user’s input is typically hidden to protect the information from prying eyes. To mask the characters entered in a text box control, use the PasswordChar property to specify a masking symbol for the text box. The following code sets the PasswordChar property to an asterisk (*):

passwordTextBox.PasswordChar = '*';
Working with Multiline Text Box Controls

When a text box control is dropped on a Windows Form using the Windows Forms Designer, initially the control can be resized horizontally but not vertically. This is because the default behavior for a text box control is to support the entry of a single line of text. To accept multiple lines, the TextBox class’s Multiline property must be set to true, as shown here:

multilineTextBox.Multiline = true;

When working with an instance of the TextBox class that supports multiple lines, you can elect to have the text for each line extend past the far edge of the control or wrap automatically to the next line at the control boundary. This behavior is controlled by the control’s WordWrap property, which will wrap long text lines into paragraphs if set to true or extend long lines if set to false, as shown in the following code. The default value is true.

multilineTextBox.WordWrap = false;

Scroll bars aren’t automatically provided for TextBox objects. Although the user can use the keyboard’s arrow keys to navigate a multiline control, in most cases you’ll want to provide at least a vertical scroll bar to assist in navigation. Scroll bars are specified using the TextBox class’s ScrollBars property, which must be assigned a value from the ScrollBars enumeration, shown in Table 12-4.

A horizontal scroll bar is never displayed if the control’s WordWrap property is set to true.

There are two ways to retrieve the text from a multiline TextBox object. The first approach, shown here, is to use the Text property, as is done with ­single-line TextBox objects:

string str = multilineTextBox.Text;

Another way to extract the text from a multiline control is to use the Lines property, which returns an array of strings, with each array element referring to a text line, as shown here:

private void getContents_Click(object sender, System.EventArgs e)
    string [] strs = multilineTextBox.Lines;
    foreach(string line in strs)
        MessageBox.Show(line, "Line-by-line display");

The elements in the Lines array don’t necessarily reflect the physical lines in the control. If word wrapping is enabled, a single line of text can occupy multiple physical lines in the control but is only one element in the Lines array.

You also can use the Lines property in the Properties window to provide the initial text for a multiline text box control. If you select the Lines property in the Properties window, a small push button will be displayed, with a caption that consists of an ellipsis (…). If you click this button, the String Collection Editor dialog box will be displayed, in which you can enter the initial text for the control.

Using Other Text Box Properties

When you’re working with a multiline text box, it’s not unusual to use the Tab and Enter keys to format the text input. By default, however, these keys have special meaning in a form. If a button is specified in the form’s AcceptButton property, that button will be clicked when the user presses the Enter key, which usually results in closing the form. If the user presses the Tab key, the input focus will move to the next control in the tab order. The TextBox class exposes two properties that enable you to override this default behavior, as follows:

  • AcceptsReturn  If set to true, this property specifies that pressing the Enter key in the control will create a new line of text in the control. If set to false, this property specifies that pressing the Enter key will activate the default button for the form. The default value is false.

  • AcceptsTab  If set to true, this property specifies that pressing the Tab key in the control will enter a tab character in the control. If this property is set to false, the user can move the focus by pressing the Tab key. The default value is false.


    If the AcceptsReturn property is false, the user can create a new line in a control by pressing Ctrl+Enter. When the AcceptsTab property is true, the user can move to the next control in the tab order by pressing Ctrl+Tab. These properties have no effect if the text box doesn’t support multiple lines.

As with the button control, described earlier in this chapter, in the section “Using the Button Classes,” you can control the appearance of a text box control. The appearance of a text box control is managed through the BorderStyle property, which must be set to one of the values from the BorderStyle enumeration, shown in Table 12-5.

By default, the BorderStyle property of TextBox objects is set to Fixed3D. The following code changes the BorderStyle property to FixedSingle, resulting in a control that has a flat appearance:

printerTextBox.BorderStyle = BorderStyle.FixedSingle;

Part III: Programming Windows Forms