70-526 MCTS

The TextBox control displays text entered at design time that can be edited by users at run time, or changed programmatically. Typically, a TextBox control is used to display a single line of text or allow a single line of text to be input by the user. It may also be set up to display/input multiline text with scrollbars, for use such as the notepad application. Optionally it may also be set up to display a password character instead of the actual text entered. There are other properties that allow the behaviour of the TextBox to be configured in several ways such as only entering uppercase or lowercase letters.

A TextBox usually has a Label associated with it. This is usually positioned to the left or the top of the TextBox.

Inheritance hierarchy

System.Object 
  System.MarshalByRefObject 
    System.ComponentModel.Component 
      System.Windows.Forms.Control 
        System.Windows.Forms.TextBoxBase 
          System.Windows.Forms.TextBox

TextBoxBase provides the base functionality for text manipulation in a TextBox, such as selecting text, cutting to and pasting from the Clipboard.

Setting MultiLine text graphically

Clicking the smart tag icon on a TextBox control in the designer and ticking MultiLine enables the TextBox to have more than one line of text.

Useful properties

AcceptsReturn - Indicates whether pressing ENTER in a multiline TextBox control creates a new line of text in the control or activates the default button for the form.

AcceptsTab - Indicates whether pressing the TAB key in a multiline TextBox control types a TAB character in the control instead of moving the focus to the next control in the tab order.

AutoCompleteCustomSource - Indicates the custom System.Collections.Specialized.StringCollection to use when the AutoCompleteSource property is set to CustomSource.

AutoCompleteMode - Controls how automatic completion works for the TextBox. Takes a value from the AutoCompleteMode enumeration:

• Append - Appends the remainder of the most likely candidate string to the existing characters, highlighting the appended characters.
• None - Disables the automatic completion feature for the ComboBox and TextBox controls.
• Suggest - Displays the auxiliary drop-down list associated with the edit control. This drop-down is populated with one or more suggested completion strings.
• SuggestAppend - Applies both Suggest and Append options.

AutoCompleteSource - Specifies the source of complete strings used for automatic completion. Takes a value from the AutoCompleteSource enumeration:

• AllSystemSources - Specifies the equivalent of FileSystem and AllUrl as the source. This is the default value when AutoCompleteMode has been set to a value other than the default.
• AllUrl - Specifies the equivalent of HistoryList and RecentlyUsedList as the source.
• CustomSource - Specifies strings from a built-in AutoCompleteStringCollection as the source.
• FileSystem - Specifies the file system as the source.
• FileSystemDirectories - Specifies that only directory names and not file names will be automatically completed.
• HistoryList - Includes the Uniform Resource Locators (URLs) in the history list.
• ListItems - Specifies that the items of the ComboBox represent the source.
• None - Specifies that no AutoCompleteSource is currently in use. This is the default value of AutoCompleteSource.
• RecentlyUsedList - Includes the Uniform Resource Locators (URLs) in the list of those URLs most recently used.

CausesValidation - Indicates whether the control causes validation to be performed on any controls that require validation when it receives focus.

CharacterCasing - Indicates whether the TextBox control modifies the case of characters as they are typed. Takes a value from the CharacterCasing enumeration:

• Lower - Converts all characters to lowercase.
• Normal - The case of characters is left unchanged.
• Upper - Converts all characters to uppercase.

Lines - Specifies the lines of text in a TextBox control stored as a string array.

Note

A Line is defined as a string that is terminated by a carriage return character. A Line is NOT a visible line as seen when WordWrap is set to true.

MaxLength - Specifies the maximum number of characters the user can type or paste into the TextBox control.

Multiline - Indicates whether this is a multiline TextBox control.

PasswordChar - Specifies the character used to mask characters of a password in a single-line TextBox control.

ReadOnly - Indicates whether text in the TextBox control is read-only.

ScrollBars - Specifies which scroll bars should appear in a multiline TextBox control.

SelectedText - Indicates the currently selected text in the TextBox control.

SelectionLength - Specifies the number of characters selected in the TextBox control.

SelectionStart - Specifies the starting point of text selected in the TextBox control.

Text - Specifies the current text in the TextBox control.

TextAlign - Specifies how text is aligned in a TextBox control.

TextLength - Gets the length of text in the TextBox control.

UseSystemPasswordChar - Indicates whether the text in the TextBox control should appear as the default password character.

WordWrap - Indicates whether a multiline TextBox control automatically wraps words to the beginning of the next line when necessary.

Using AutoComplete

Three of the above properties allow the user to auto-complete text within a TextBox control. This can only happen when Multiline is set to false.

In the example above, the following settings are used:

• AutoCompleteMode is set to Suggest.
• AutoCompleteSource is set to CustomSource.
• AutoCompleteCustomSource is set to a list of the C# keywords.

Download the above sample application (written in C# Express).

Masking Characters as Passwords

The properties PasswordChar and UseSystemPasswordChar can be used to create a TextBox that does not show the characters when they are types in. This will happen if either PasswordChar is set to a value or UseSystemPasswordChar is set to true. However, if both are set then the system password character wil be used.

MSDN references