The TextBox control is the primary mechanism for displaying and entering text. It is a small text editor that provides all the basic text-editing facilities: inserting and selecting text, scrolling if the text doesn’t fit in the control’s area, and even exchanging text with other applications through the Clipboard.
The TextBox control is an extremely versatile data-entry tool that can be used for entering and editing single lines of text, such as a number or a password, or an entire text file. Figure 4.1 shows a few typical examples. All the boxes in Figure 4.1 contain text — some a single line, some several lines. The scroll bars you see in some text boxes are part of the control. You can specify which scroll bars (vertical and/or horizontal) will be attached to the control, and they will appear automatically whenever the control’s contents exceed the visible area of the control.
Figure 4.1 – TextBox Examples
Basic Properties of the TextBox Control
Let’s start with the properties that specify the appearance and, to some degree, the functionality of the TextBox control; these properties are usually set at design time through the Propertieswindow. Then, we’ll look at the properties that allow you to manipulate the control’s contents and interact with users from within your code.
TextAlign
This property sets (or returns) the alignment of the text on the control, and its value is a member of the HorizontalAlignment enumeration: Left, Right, or Center. The TextBox control doesn’t allow you to format text (mix different fonts, attributes, or colors), but you can set the font in which the text will be displayed with the Font property, as well as the control’s background color with the BackColor property.
MultiLine
This property determines whether the TextBox control will hold a single line or multiple lines of text. Every time you place a TextBox control on your form, it’s sized for a single line of text and you can change its width only. To change this behavior, set the MultiLine property to True. When creating multiline TextBoxes, you will most likely have to set one or more of the MaxLength, ScrollBars, and WordWrap properties in the Properties window.
MaxLength
This property determines the number of characters that the TextBox control will accept. Its default value is 32,767, which was the maximum number of characters the VB 6 version of the control could hold. Set this property to zero, so that the text can have any length, up to the control’s capacity limit — 2,147,483,647 characters, to be exact. To restrict the number of characters that the user can type, set the value of this property accordingly.
The MaxLength property of the TextBox control is often set to a specific value in data-entry applications, which prevents users from entering more characters than can be stored in a database field. A TextBox control for entering international standard tutorial numbers (ISBNs), for instance, shouldn’t accept more than 13 characters.
ScrollBars
This property lets you specify the scroll bars you want to attach to the TextBox if the text exceeds the control’s dimensions. Single-line text boxes can’t have a scroll bar attached, even if the text exceeds the width of the control. Multiline text boxes can have a horizontal or a vertical scroll bar, or both.
If you attach a horizontal scroll bar to the TextBox control, the text won’t wrap automatically as the user types. To start a new line, the user must press Enter. This arrangement is useful for implementing code editors in which lines must break explicitly. If the horizontal scroll bar is missing, the control inserts soft line breaks when the text reaches the end of a line, and the text is wrapped automatically. You can change the default behavior by setting the WordWrap property.
WordWrap
This property determines whether the text is wrapped automatically when it reaches the right edge of the control. The default value of this property is True. If the control has a horizontal scroll bar, however, you can enter very long lines of text. The contents of the control will scroll to the left, so the insertion point is always visible as you type. You can turn off the horizontal scroll bar and still enter long lines of text; just use the left/right arrows to bring any part of the text into view. You can experiment with the WordWrap and ScrollBars properties in the TextPad sample application, which is described later in this chapter.
Notice that the WordWrap property has no effect on the actual line breaks. The lines are wrapped automatically, and there are no hard breaks (returns) at the end of each line. Open the TextPad project, enter a long paragraph, and resize the window — the text is automatically adjusted to the new width of the control.
AcceptsReturn, AcceptsTab
These two properties specify how the TextBox control reacts to the Return (Enter) and Tab keys. The Enter key activates the default button on the form, if there is one. The default button is usually an OK button that can be activated with the Enter key, even if it doesn’t have the focus. In a multiline TextBox control, however, we want to be able to use the Enter key to change lines. The default value of the AcceptsReturn property is True, so pressing Enter creates a new line on the control. If you set it to False, users can still create new lines in the TextBox control, but they’ll have to press Ctrl+Enter. If the form contains no default button, the Enter key creates a new line regardless of the AcceptsReturn setting.
Likewise, the AcceptsTab property determines how the control reacts to the Tab key.Normally, the Tab key takes you to the next control in the Tab order, and we generally avoid changing the default setting of the AcceptsTab property. In a multiline TextBox control, however, you may want the Tab key to insert a Tab character in the text of the control instead; to do this, set the control’s AcceptsTab property to True (the default value is False). If you change the default value, users can still move to the next control in the Tab order by pressing Ctrl+Tab. Notice that the AcceptsTab property has no effect on other controls. Users may have to press Ctrl+Tab to move to the next control while a TextBox control has the focus, but they can use the Tab key to move from any other control to the next one.
CharacterCasing
This property tells the control to change the casing of the characters as they’re entered by the user. Its default value is Normal, and characters are displayed as typed. You can set it to Upper or Lower to convert the characters to upper or lowercase automatically.
PasswordChar
This property turns the characters typed into any character you specify. If you don’t want to display the actual characters typed by the user (when entering a password, for instance), use this property to define the character to appear in place of each character the user types.
The default value of this property is an empty string, which tells the control to display the characters as entered. If you set this value to an asterisk (*), for example, the user sees an asterisk in the place of every character typed. This property doesn’t affect the control’s Text property, which contains the actual characters. If the PasswordChar property of the TextBox control is set to any character, the user can’t copy or cut the text on the control.
ReadOnly, Locked
If you want to display text on a TextBox control but prevent users from editing it (such as for an agreement or a contract they must read, software installation instructions, and so on), you can set the ReadOnly property to True.When ReadOnly is set to True, you can put text on the control from within your code, and users can view it, yet they can’t edit it.
To prevent editing of the TextBox control with VB 6, you had to set the Locked property to True. Oddly, the Locked property is also supported, but now it has a very different function. The Locked property of VB 2008 locks the control at design time (so that you won’t move it or change its properties by mistake as you design the form).
