.NET Controls: The Multi-Line Text Box

The TextBox control is equipped with one particular property that, when considered, changes the control tremendously. This property is called Multiline. Multiline is a Boolean property whose default value is false. If it is set to a true value, it allows the control to display multiple lines of text, unlike the normal text box that can display only one line.

To create a multi-line, after adding a TextBox control to a form, probably the first action you should take is to set its Multiline Boolean property to True. After the TextBox control has been added to the form, it is positioned where you drop it at design time. If you are creating a text editor, you can use the Dock property to specify how much room of the form the text box would use.

The user mostly reads and/or enters text in the multi-line text box when interacting with the control. At design time, you can set the text that would display when the multi-line text box comes up. To enter this text, in the Properties window, click the Lines field to reveal its ellipsis button that allows you to open the String Collection Editor. If you want the control to be empty at startup, delete the content of the String Collector Editor and click OK. Otherwise, type the desired text and click OK.

The user, on the other hand has the ability to type text to alter the content of the multi-line text box. This is possible only if the ReadOnly property is set to True, which is the default. If you want to prevent the user from altering the text in the multi-line text box, set the ReadOnly property to False. You can also do this programmatically.

When a multi-line text box opens, the compiler registers the content of the control. If the user has the ability to change the text in the control and if the user changes it, the compiler flags the control as Modified. This allows you to take actions. You can acknowledge this by programmatically setting the Modified property to true. If another control or some other action alters the contents of the multi-line text box, you can make sure that this property reflects the change. You can change this programmatically as follows:

private void btnModified_Click(object sender, System.EventArgs e)
{
	this.textBox1.Modified = true;
}

The multi-line text box allows the user to enter up to 32767 characters. If you want to limit the maximum number of characters that the user can enter to a value lower than this, you can use the MaxLength property at design time. You can also change this programmatically. Here is an example:

private void btnModified_Click(object sender, System.EventArgs e)
{
	this.textBox1.MaxLength = 1020;
}

If the control will be used to enter text, the user can press Enter at the end of a line to move to the next line. This ability is controlled by the Boolean AcceptsReturn property. By default, this property is set to False because this control is primarily created from a normal single-line TextBox control that has no formal action to take when the user presses Enter. If you are creating a multi-line text box and you expect your users to perform some type of text editing, you certainly should allow them to press Enter to move to the next line. Therefore, in most cases, when creating a multi-line text box, you should set its AcceptsReturn property to True. To set it programmatically, assign the desired value to the AcceptstReturn property. Here is an example:

private void btnModified_Click(object sender, System.EventArgs e)
{
	this.txtMemo.AcceptsReturn = true;
}

The user is accustomed to pressing Tab to insert tab characters in the text. By default, when the user presses Tab when interacting with your application, the focus moves from one control to the next, following the TabIndex values of the form. Even when using a multi-line text box to perform text editing, if the user presses Tab, the focus would switch to another control or to the form. If you want a multi-line text box to receive focus when the user presses the Tab key, set the AcceptTab property from False (the default), to True.

When entering text in a multi-line text box control, the characters start on the left side of the multi-line text box and are subsequently added on the right side. The ability to align text is controlled by the TextAlign property. For a multi-line text box control, the alignment is configured using the HorizontalAlignment enumerator.

As the user enters text in a multi-line text box box, the compiler considers that a paragraph starts from the user typing a character until he or she presses Enter. Therefore, a paragraph could be an empty space, a character, a word, a line of text, a whole page or an entire book. Depending on the width of the multi-line text box control, the text is incrementally added to the right side of each previous character. If the caret gets to the right border of the control, the text automatically continues to the next line, although it is still considered as one paragraph. To start a new paragraph, the user has to press Enter. The ability for the text to continue on the next line when the caret encounters the right border of the multi-line text box is controlled by the WordWrap property whose default Boolean value is set to true. If you do not want text to wrap to the subsequent line, set the WordWrap property to false. You can also set it programmatically as follows:

private void btnModified_Click(object sender, System.EventArgs e)
{
	this.txtMemo.AcceptsReturn = true;
	this.txtMemo.WordWrap = false;
}

The multi-line text box control is based on the TextBox class. To dynamically create a multi-line text box, declare a TextBox variable and use its default constructor to initialize it. The other operations the user can perform on a multi-line text box can be controlled by methods such as Undo(), Cut(), Copy(), Paste(), Clear() or SelectAll() that we reviewed for the text box control and they function the same.