Programming ASP.NET, 3rd Edition

TextBox Control

The TextBox control can be used for both user input and read-only text display. You can configure it to be single line or multiline or to accept passwords. If you set it to multiline, it automatically wraps unless the Wrap property is set to false. The text it contains can exceed the length of the control displayed on the page. The TextBox, DropDownList, Label, and other text-friendly controls implement the ITextControl interface, which is new to Version 2.0 of ASP.NET. This interface has a single property, Text, which is the visual content of the control.

Table 4-2 lists many of the common properties specific to the TextBox control. If any of these attributes are omitted from the control, then the default value will apply.

Table 4-2. Some properties specific to the TextBox control

Name	Type	Get	Set	Values	Description
AutoPostBack	Boolean	✗	✗	true, false	Determines if automatic postback to server will occur if user changes contents of control. If false, postback to server will not occur until the page is posted, either by a button or another control with AutoPostBack set to true. Default is false.
Columns	Int32	✗	✗	0, 1, 2, and so on	Width of the text box in characters. Default is 0, which indicates the property is not set.
MaxLength	Int32	✗	✗	0, 1, 2, and so on	Maximum number of characters allowed. If MaxLength is greater than Columns, then only a portion of the string will display without using the Home, End, or arrow keys. Its default value is 0, which does not impose a limit on the number of characters entered into the text box.
ReadOnly	Boolean	✗	✗	true, false	If true, content cannot be changed by user though it can still be changed programmatically. Default is false.
Rows	Int32	✗	✗	0, 1, 2, and so on	Number of lines of text in a multiline text box. The default is 0, which imposes no limit on the number of lines.
Text	string	✗	✗		Content of the TextBox.
TextMode	TextBoxMode	✗	✗	SingleLine, MultiLine, Password	SingleLine The default value displays a single line of text. MultiLine Allows multiple lines of text and displays a vertical scrollbar, even for Rows = 1. The text wraps automatically to fit the width of the box. The Enter key enters a carriage return/line feed. The mouse or Tab key causes focus to leave the box and initiates postback if AutoPostBack is true. Password Displays content in asterisks, then clears the text box on posting. The value is not case-sensitive.
ValidationGroup	String	✗	✗		Specifies which validation group, if any, this control is a member of. See Chapter 8 for a discussion of validation.
Wrap	Boolean	✗	✗	true, false	Indicates if text within a multiline text box should wrap. If false, then the text box will have a horizontal scrollbar. Default is true.

In addition to the events inherited from the WebControl class, such as Init, Load, and PreRender, the TextBox control raises the TextChanged event when the contents of the text box have changed and the control loses focus. This is not a postback event unless the AutoPostBack property is set to true.

When a TextBox control is declared in a content file (.aspx or .ascx), the TextChanged event handler method is specified with the OnTextChanged attribute. TextChanged is the default event handler created by VS2005 when you double-click on a TextBox in Design view. This event handler is passed a standard EventArgs argument.

The following example demonstrates the basic use of a TextBox, including handling of the TextChanged event. This example has two text boxes: one to input text, and a second, read-only control, to echo the contents of the first box. The finished web page should look something like that shown in Figure 4-2, after changing the text in the input box.

Figure 4-2. TextBoxDemo

Create a new web site in VS2005 called TextBoxDemo. Drag two TextBox controls onto the page. Set the ID property of the first to txtInput and the second to txtEcho. Set the AutoPostBack property of txtInput to true, so that the form will automatically post back whenever the contents of the control changes. Set the BackColor property of txtEcho to LightGray and the ReadOnly property to true.

The content file is shown in Example 4-4, after the OnTextChanged attribute is added, as described in the next paragraph.

Example 4-4. Default.aspx for TextBoxDemo

<%@ Page Language="C#" AutoEventWireup="true"
   CodeFile="Default.aspx.cs" Inherits="_Default" %>
 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
 
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>TextBox Demo</title>
</head>
<body>
   <form id="form1" runat="server">
   <div>
      <h1>TextBox Demo</h1>

      <asp:TextBox ID="txtInput" runat="server"
                   AutoPostBack="true"
                   OnTextChanged="txtInput_TextChanged" >
         Enter some text
      </asp:TextBox>
      <br />

      <asp:TextBox ID="txtEcho" runat="server"
                   BackColor="LightGray"
                   ReadOnly="True">
      </asp:TextBox>
   </div>
   </form>
</body>
</html>

To easily create the default event handler for txtInput, switch to Design view and double-click on the TextBox. The OnTextChanged attribute will be added to the txtInput declaration in the content file, and the code-behind file will open with a code skeleton in place for the event handler. Enter the highlighted line of code from Example 4-5.

Example 4-5. TextChanged event handler for TextBoxDemo

protected void txtInput_TextChanged(object sender, EventArgs e)
{

   txtEcho.Text = txtInput.Text;
}

When the application is first run, txtInput will contain “Enter some text.” When you change the contents of the control and tab out of the text box, the TextChanged event will fire and the event handler specified in the OnTextChanged attribute, txtInput_TextChanged, will execute, populating txtEcho.