Introduction

By default, when you add a new text box to your form, it appears empty. When the application comes up, 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. Type the desired text and click OK. On the other hand, after the user has entered some text or a few lines of text in the control, it holds these lines. The lines of text of a text box are stored in an array represented by a property named Lines. This means that, at run time, you can create an array of lines of text and assign it to the text box. Or, to get the lines of text of the control, you can retrieve the value of the Lines property.

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:

Public Sub InitializeComponent()

            Text = "Memorandum"

            txtMemo = New TextBox
            txtMemo.Location = New Point(10, 10)
            txtMemo.Width = Width - 30
            txtMemo.Height = Height - 50
            txtMemo.Anchor = AnchorStyles.Left Or _
                              AnchorStyles.Top Or _
                              AnchorStyles.Right Or _
                              AnchorStyles.Bottom
            txtMemo.Multiline = True

            txtMemo.Modified = True

            Controls.Add(txtMemo)

End Sub

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:

Public Sub InitializeComponent()

            Text = "Memorandum"

            txtMemo = New TextBox
            txtMemo.Location = New Point(10, 10)
            txtMemo.Width = Width - 30
            txtMemo.Height = Height - 50
            txtMemo.Anchor = AnchorStyles.Left Or _
                              AnchorStyles.Top Or _
                              AnchorStyles.Right Or _
                              AnchorStyles.Bottom
            txtMemo.Multiline = True
            txtMemo.Modified = True

            txtMemo.MaxLength = 1020

            Controls.Add(txtMemo)

End Sub

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:

Public Sub InitializeComponent()

            Text = "Memorandum"

            txtMemo = New TextBox
            txtMemo.Location = New Point(10, 10)
            txtMemo.Width = Width - 30
            txtMemo.Height = Height - 50
            txtMemo.Anchor = AnchorStyles.Left Or _
                              AnchorStyles.Top Or _
                              AnchorStyles.Right Or _
                              AnchorStyles.Bottom
            txtMemo.Multiline = True

            txtMemo.AcceptsReturn = True

            Controls.Add(txtMemo)

End Sub

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:

Public Sub InitializeComponent()

            Text = "Memorandum"

            txtMemo = New TextBox
            txtMemo.Location = New Point(10, 10)
            txtMemo.Width = Width - 30
            txtMemo.Height = Height - 50
            txtMemo.Anchor = AnchorStyles.Left Or _
                              AnchorStyles.Top Or _
                              AnchorStyles.Right Or _
                              AnchorStyles.Bottom
            txtMemo.Multiline = True
            txtMemo.AcceptsReturn = True

            txtMemo.WordWrap = True

            Controls.Add(txtMemo)

End Sub

When a text box has been configured to hold multiple lines and once its text becomes too long, part of the content could become hidden. To show the hidden part, the control should be equipped with scrollbars so the user can navigate up and down, left and right. To support the display of scrollbars, the TextBox class is equipped with the ScrollBars property. You can specify the option of this property at either the design time or the run time or both.

The TextBox.ScrollBars property is based on the ScrollBars enumeration that has four members:

• None: This is the default value and its means that the text box would not display any scrollbar
• Vertical: This option specifies that the text box should display a vertical scroll bar when its content becomes too long
• Horizontal: This is valid only if the WordWrap property is set to false. In this case, the text box would display a horizontal scroll bar
• Both: This allows displaying both the vertical and the horizontal scrollbars

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.

Here is an example:

Imports System.Drawing
Imports System.Windows.Forms

Module Exercise

    Public Class Starter
        Inherits Form

        Private txtMemo As TextBox
        Friend WithEvents btnSelectAll As Button

        Dim components As System.ComponentModel.Container

        Public Sub New()
            InitializeComponent()
        End Sub

        Public Sub InitializeComponent()

            Text = "Memorandum"

            btnSelectAll = New Button()
            btnSelectAll.Location = New Point(10, 10)
            btnSelectAll.Text = "Action"
            Controls.Add(btnSelectAll)

            txtMemo = New TextBox
            txtMemo.Location = New Point(10, 43)
            txtMemo.Width = Width - 30
            txtMemo.Height = Height - 80
            txtMemo.Anchor = AnchorStyles.Left Or _
                              AnchorStyles.Top Or _
                              AnchorStyles.Right Or _
                              AnchorStyles.Bottom
            txtMemo.Multiline = True
            txtMemo.AcceptsReturn = True
            txtMemo.WordWrap = True
            Controls.Add(txtMemo)

        End Sub

        Private Sub SelectAllClicked(ByVal sender As Object, _
                                  ByVal e As EventArgs) _
                                  Handles btnAction.Click
            txtMemo.Undo()
        End Sub
    End Class

    Function Main() As Integer

        Dim frmStart As Starter = New Starter

        Application.Run(frmStart)

        Return 0
    End Function

End Module