The TextBox control is a typical everyday text box. The user can enter and modify text, click and drag to select text, press Ctrl+C to copy the selected text to the clipboard, and so forth.
The TextBox control is much simpler than the RichTextBox control described earlier in this appendix. It can use only one font, background color, and foreground color for all of its text. It also cannot provide special formatting such as bullets, hanging indentation, and margins the way the RichTextBox can. If you need those extra features, use a RichTextBox instead of a TextBox control.
The following table describes the TextBox control’s most useful properties.
Property | Purpose |
---|---|
AcceptsReturn | For multiline controls, determines whether pressing the Enter key adds a new line to the text rather than triggering the form’s Accept button. |
AcceptsTab | For multiline controls, determines whether pressing the Tab key adds a Tab to the text rather than moving to the next control in the tab sequence. |
AutoSize | For single-line controls, determines whether the control automatically sets its height for the fonts it contains. |
CharacterCasing | Determines whether the control automatically changes the case of text as it is entered. This property can take the values Normal (leave the case alone), Upper (uppercase), and Lower (lowercase). The control changes the text’s case whether the user types or pastes it into the control, or if the program sets the control’s text. |
Lines | An array of strings giving the lines of text (separated by carriage returns) displayed by the control. You can use this property to give the control more than one paragraph at design time. |
MaxLength | The maximum number of characters the user can enter into the control. |
MultiLine | Determines whether the control displays multiple lines. |
PasswordChar | Determines the password character displayed by a single-line TextBox control for each character it contains. For example, if you set PasswordChar to *, then each character the user types appears as a * in the text box. The control’s Text property returns the actual text to the program. |
PreferredHeight | Returns the height a single-line control would want to use for the font size. |
ReadOnly | Determines whether the user can modify the control’s text. You can display read-only text in a label, but then the user cannot select it and copy it to the clipboard. If you want to display information that the user might want to copy, place it in a TextBox control and set ReadOnly to True. |
ScrollBars | Determines which scroll bars the control displays. This property can take the values None, Vertical, Horizontal, and Both. The appropriate scroll bars are always displayed, although they are disabled when they are not needed. Note that some of these values may not always be honored. For example, if WordWrap is True, then the control never displays horizontal scroll bars. |
SelectedText | Gets or sets the selected text’s value. |
SelectionLength | Gets the length of the selected text, or selects this number of letters. You can use SelectionStart and SelectionLength to select text, or you can use the Select method. |
SelectionStart | Gets or sets the start of the selection. You can use SelectionStart and SelectionLength to select text, or you can use the Select method. |
Text | Gets or sets the control’s text. |
TextAlign | Determines the text’s alignment within the control. This can be Left, Right, or Center. |
TextLength | Returns the length of the control’s text. |
WordWrap | For multiline controls, determines whether the control wraps text to a new line if it is too long to fit. |
The control also provides several important methods, described in the following table.
Method | Purpose |
---|---|
AppendText | Adds text to the end of the control’s text. |
Clear | Clears the control’s text. |
ClearUndo | Empties the control’s undo list. |
Copy | Copies the control’s selection to the clipboard. |
Cut | Copies the control’s selection to the clipboard and removes it from the control’s text. |
Paste | Pastes the clipboard’s contents into the control, replacing the current selection. This method does nothing if the clipboard doesn’t contain textual data. |
ScrollToCaret | Scrolls the text so the insertion position is visible. |
Select | Selects the indicated text. |
SelectAll | Selects all of the control’s text. |
Undo | Undoes the most recent action. The TextBox only stores information for one undo action, so calling Undo again undoes the undo. That also means that the TextBox doesn’t need a Redo method because it would do the same thing as Undo. |
The TextBox control’s most useful event is TextChanged. You can use this event to take action when the user changes the control’s text. For example, you can display a visible indication that the data has been modified.