If you've ever created a Windows application before, you're probably familiar with the basic set of standard controls, including labels, buttons, and text boxes. ASP.NET provides web controls for all these standbys. (And if you've created .NET Windows applications, you'll notice that the class names and properties have many striking similarities, which are designed to make it easy to transfer the experience you acquire in one type of application to another.)

Table 6-1 lists the basic control classes and the HTML elements they generate. Some controls (such as Button and TextBox) can be rendered as different HTML elements. In this case, ASP.NET uses the element that matches the properties you've set. Also, some controls have no real HTML equivalent. For example, when the CheckBoxList and RadioButtonList controls render themselves, they may output a <table> that contains multiple HTML check boxes or radio buttons. ASP.NET exposes them as a single object on the server side for convenient programming, thus illustrating one of the primary strengths of web controls.

This table omits some of the more specialized controls used for data, navigation, security, and web portals. You'll see these controls as you learn about their features throughout this book.

ASP.NET tags have a special format. They always begin with the prefix asp: followed by the class name. If there is no closing tag, the tag must end with />. (This syntax convention is borrowed from XML, which you'll learn about in much more detail in Chapter 18.) Each attribute in the tag corresponds to a control property, except for the runat="server" attribute, which signals that the control should be processed on the server.

The following, for example, is an ASP.NET TextBox:

<asp:TextBox ID="txt" runat="server" />

When a client requests this .aspx page, the following HTML is returned. The name is a special attribute that ASP.NET uses to track the control.

<input type="text" ID="txt" name="txt" />

Alternatively, you could place some text in the TextBox, set its size, make it read-only, and change the background color. All these actions have defined properties. For example, the TextBox.TextMode property allows you to specify SingleLine (the default), MultiLine (for a <textarea> type of control), or Password (for an input control that displays bullets to hide the true value). You can adjust the color using the BackColor and ForeColor properties. And you can tweak the size of the TextBox in one of two ways—either using the Rows and Columns properties (for the pure HTML approach) or using the Height and Width properties (for the style-based approach). Both have the same result.

Here's one example of a customized TextBox:

<asp:TextBox ID="txt" BackColor="Yellow" Text="Hello World"
 ReadOnly="True" TextMode="MultiLine" Rows="5" runat="server" />

The resulting HTML uses the <textarea> element and sets all the required attributes (such as rows and readonly) and the style attribute (with the background color). It also sets the cols attribute with the default width of 20 columns, even though you didn't explicitly set the TextBox.Columns property:

<textarea name="txt" rows="5" cols="20" readonly="readonly" id="txt"
 style="background-color:Yellow;">Hello World</textarea>

Figure 6-1 shows the <textarea> element in the browser.

Figure 6.1. A customized text box

Clearly, it's easy to create a web control tag. It doesn't require any understanding of HTML. However, you will need to understand the control class and the properties that are available to you.

<asp:Button ID="Button1" runat="server"
  Enabled="False" Text="Button" Font-Size="XX-Small" />
<asp:button ID="Button2" runat="server"
  Enabled="false" tExT="Button" Font-Size="xx-small" />

Most web controls begin by inheriting from the WebControl base class. This class defines the essential functionality for tasks such as data binding and includes some basic properties that you can use with almost any web control, as described in Table 6-2.

The next few sections describe some of the common concepts you'll use with almost any web control, including how to set properties that use units and enumerations and how to use colors and fonts.

All the properties that use measurements, including BorderWidth, Height, and Width, require the Unit structure, which combines a numeric value with a type of measurement (pixels, percentage, and so on). This means when you set these properties in a control tag, you must make sure to append px (pixel) or % (for percentage) to the number to indicate the type of unit.

Here's an example with a Panel control that is 300 pixels high and has a width equal to 50 percent of the current browser window:

<asp:Panel Height="300px" Width="50%" ID="pnl" runat="server" />

If you're assigning a unit-based property through code, you need to use one of the shared methods of the Unit type. Use Pixel() to supply a value in pixels, and use Percentage() to supply a percentage value:

' Convert the number 300 to a Unit object
' representing pixels, and assign it.
pnl.Height = Unit.Pixel(300)

' Convert the number 50 to a Unit object
' representing percent, and assign it.
pnl.Width = Unit.Percentage(50)

You could also manually create a Unit object and initialize it using one of the supplied constructors and the UnitType enumeration. This requires a few more steps but allows you to easily assign the same unit to several controls:

' Create a Unit object.
Dim myUnit As New Unit(300, UnitType.Pixel)

' Assign the Unit object to several controls or properties.
pnl.Height = myUnit
pnl.Width = myUnit

Enumerations are used heavily in the .NET class library to group a set of related constants. For example, when you set a control's BorderStyle property, you can choose one of several predefined values from the BorderStyle enumeration. In code, you set an enumeration using the dot syntax:

ctrl.BorderStyle = BorderStyle.Dashed

In the .aspx file, you set an enumeration by specifying one of the allowed values as a string. You don't include the name of the enumeration type, which is assumed automatically.

<asp:Label BorderStyle="Dashed" Text="Border Test" ID="lbl"
 runat="server" />

Figure 6-3 shows the label with the altered border.

Figure 6.3. Modifying the border style

The Color property refers to a Color object from the System.Drawing namespace. You can create color objects in several ways:

To use any of these techniques, you'll probably want to start by importing the System.Drawing namespace, as follows:

Imports System.Drawing

The following code shows several ways to specify a color in code:

' Create a color from an ARGB value
Dim alpha As Integer = 255, red As Integer = 0
Dim green As Integer = 255, blue As Integer = 0
ctrl.ForeColor = Color.FromArgb(alpha, red, green, blue)

' Create a color using a .NET name
ctrl.ForeColor = Color.Crimson

' Create a color from an HTML code
ctrl.ForeColor = ColorTranslator.FromHtml("Blue")

When defining a color in the .aspx file, you can use any one of the known color names:

<asp:TextBox ForeColor="Red" Text="Test" ID="txt" runat="server" />

The HTML color names that you can use are listed in the Visual Studio Help. Alternatively, you can use a hexadecimal color number (in the format #<red><green><blue>) as shown here:

<asp:TextBox ForeColor="#ff50ff" Text="Test"
     ID="txt" runat="server" />

The Font property actually references a full FontInfo object, which is defined in the System.Web.UI.WebControls namespace. Every FontInfo object has several properties that define its name, size, and style (see Table 6-3).

In code, you can assign a font by setting the various font properties using the familiar dot syntax:

ctrl.Font.Name = "Verdana"
ctrl.Font.Bold = True

You can also set the size using the FontUnit type:

' Specifies a relative size.
ctrl.Font.Size = FontUnit.Small

' Specifies an absolute size of 14 pixels.
ctrl.Font.Size = FontUnit.Point(14)

In the .aspx file, you need to use a special "object walker" syntax to specify object properties such as Font. The object walker syntax uses a hyphen (-) to separate properties. For example, you could set a control with a specific font (Tahoma) and font size (40 point) like this:

<asp:TextBox Font-Name="Tahoma" Font-Size="40" Text="Size Test" ID="txt"
 runat="server" />

Or you could set a relative size like this:

<asp:TextBox Font-Name="Tahoma" Font-Size="Large" Text="Size Test"
 ID="txt" runat="server" />

Figure 6-4 shows the altered TextBox in this example.

Figure 6.4. Modifying a control's font

A font setting is really just a recommendation. If the client computer doesn't have the font you request, it reverts to a standard font. To deal with this problem, it's common to specify a list of fonts, in order of preference. To do so, you use the Font.Names property instead of Font.Name, as shown here:

<asp:TextBox Font-Names="Verdana,Tahoma,Arial"
 Text="Size Test" ID="txt" runat="server" />

Here, the browser will use the Verdana font (if it has it). If not, it will fall back on Tahoma or, if that isn't present, Arial.

When specifying fonts, it's a good idea to end with one of the following fonts, which are supported on all browsers:

The following fonts are found on almost all Windows and Mac computers, but not necessarily on other operating systems like Unix:

Unlike HTML server controls, every web control provides a Focus() method. The Focus() method affects only input controls (controls that can accept keystrokes from the user). When the page is rendered in the client browser, the user starts in the focused control.

For example, if you have a form that allows the user to edit customer information, you might call the Focus() method on the first text box in that form. That way, the cursor appears in this text box immediately when the page first loads in the browser. If the text box is partway down the form, the page even scrolls down to it automatically. The user can then move from control to control using the time-honored Tab key.

If you're a seasoned HTML developer, you know there isn't any built-in way to give focus to an input control. Instead, you need to rely on JavaScript. This is the secret to ASP.NET's implementation. When your code is finished processing and the page is rendered, ASP.NET adds an extra block of JavaScript code to the end of your page. This JavaScript code simply sets the focus to the last control that used the Focus() method. If you haven't called Focus() at all, this code isn't added to the page.

Rather than call the Focus() method programmatically, you can set a control that should always be focused by setting the DefaultFocus property of the <form> tag:

<form DefaultFocus="TextBox2" runat="server">

You can override the default focus by calling the Focus() method in your code.

Another way to manage focus is using access keys. For example, if you set the AccessKey property of a TextBox to A, pressing Alt+A focus will switch to the TextBox. Labels can also get into the game, even though they can't accept focus. The trick is to set the Label.AssociatedControlID property to specify a linked input control. That way, the label transfers focus to the associated control.

For example, the following label gives focus to TextBox2 when the keyboard combination Alt+2 is pressed:

<asp:Label AccessKey="2" AssociatedControlID="TextBox2" runat="server"
 Text="TextBox2:" />
<asp:TextBox runat="server" ID="TextBox2" />

Focusing and access keys are also supported in non-Microsoft browsers, including Firefox.

Along with control focusing, ASP.NET also allows you to designate a default button on a web page. The default button is the button that is "clicked" when the user presses the Enter key. For example, if your web page includes a form, you might want to make the submit button into a default button. That way, if the user hits Enter at any time, the page is posted back and the Button.Click event is fired for that button.

To designate a default button, you must set the HtmlForm.DefaultButton property with the ID of the respective control, as shown here:

<form DefaultButton="cmdSubmit" runat="server">

The default button must be a control that implements the IButtonControl interface. The interface is implemented by the Button, LinkButton, and ImageButton web controls but not by any of the HTML server controls.

In some cases, it makes sense to have more than one default button. For example, you might create a web page with two groups of input controls. Both groups may need a different default button. You can handle this by placing the groups into separate panels. The Panel control also exposes the DefaultButton property, which works when any input control it contains gets the focus.

Some list controls can allow multiple selections. This isn't allowed for the DropDownList or RadioButtonList, but it is supported for a ListBox, provided you have set the SelectionMode property to the enumerated value ListSelectionMode.Multiple. The user can then select multiple items by holding down the Ctrl key while clicking the items in the list. With the CheckBoxList, multiple selections are always possible.

The SelectedIndex and SelectedItem properties aren't much help with a list that supports multiple selection, because they will simply return the first selected item. Instead, you can find all the selected items by iterating through the Items collection of the list control and checking the ListItem.Selected property of each item. (If it's True, that item is one of the selected items.) Figure 6-5 shows a simple web page example. It provides a list of computer languages and indicates which selections the user made when the OK button is clicked.

Figure 6.5. A simple CheckListBox test

The .aspx file for this page defines CheckListBox, Button, and Label controls, as shown here:

<%@ Page Language="VB" AutoEventWireup="false"
    CodeFile="CheckListTest.aspx.vb" Inherits="CheckListTest" %>
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
  <title>CheckBoxTest</title>
</head>
<body>
  <form runat="server">
    <div>
      Choose your favorite programming languages:<br /><br />
      <asp:CheckBoxList ID="chklst" runat="server" /><br /><br />
      <asp:Button ID="cmdOK" Text="OK" runat="server" />
      <br /><br />
      <asp:Label ID="lblResult" runat="server" />
    </div>
  </form>
</body>
</html>

The code adds items to the CheckListBox at startup and iterates through the collection when the button is clicked:

Public Partial Class CheckListTest
  Inherits System.Web.UI.Page

    Protected Sub Page_Load(ByVal sender As Object, _
      ByVal e As EventArgs) Handles Me.Load
        If Me.IsPostBack = False
            chklst.Items.Add("C")
            chklst.Items.Add("C++")
            chklst.Items.Add("C#")
            chklst.Items.Add("Visual Basic 6.0")
            chklst.Items.Add("VB.NET")
            chklst.Items.Add("Pascal")
        End If
    End Sub

    Protected Sub cmdOK_Click(ByVal sender As Object, _
      ByVal e As System.EventArgs) Handles cmdOK.Click
        lblResult.Text = "You chose:<b>"

        Dim lstItem As ListItem
        For Each lstItem In chklst.Items
            If lstItem.Selected = True Then
                ' Add text to label.
                lblResult.Text &= "<br />" & lstItem.Text
            End If
        Next

        lblResult.Text &= "</b>"
    End Sub

End Class

The BulletedList control is a server-side equivalent of the <ul> (unordered list) and <ol> (ordered list) elements. As with all list controls, you set the collection of items that should be displayed through the Items property. Additionally, you can use the properties in Table 6-4 to configure how the items are displayed.

If you set the DisplayMode to LinkButton, you can react to the Button.Click event to determine which item was clicked. Here's an example:

Protected Sub BulletedList1_Click(ByVal sender As Object, _
  ByVal e As BulletedListEventArgs) Handles BulletedList1.Click

    ' Find the clicked item in the list.
    ' (You can't use the SelectedIndex property here because static lists
    ' don't support selection.)
    Dim itemText As String = BulletedList1.Items(e.Index).Text
    Label1.Text = "You choose item" & itemText
End Sub

Figure 6-6 shows all the BulletStyle values that the BulletList supports. When you click one of the items, the list changes to use that BulletStyle. You can try this example page with the sample WebControls project for this chapter.

Figure 6.6. Various BulletedList styles

Chapter 1 explained that not all types of web programming use server-side code like ASP.NET. One common example of client-side web programming is JavaScript, which uses script code that's executed by the browser. ASP.NET uses the client-side abilities of JavaScript to bridge the gap between client-side and server-side code. (Another scripting language is VBScript, but JavaScript is the only one that works on all modern browsers, including Internet Explorer, Firefox, Opera, Safari, and Netscape.)

Here's how it works: If you create a web page that includes one or more web controls that are configured to use AutoPostBack, ASP.NET adds a special JavaScript function to the rendered HTML page. This function is named __doPostBack(). When called, it triggers a postback, sending data back to the web server.

ASP.NET also adds two additional hidden input fields that are used to pass information back to the server. This information consists of the ID of the control that raised the event and any additional information that might be relevant. These fields are initially empty, as shown here:

<input type="hidden" name="__EVENTTARGET" id="__EVENTTARGET" value="" />
<input type="hidden" name="__EVENTARGUMENT" id="__EVENTARGUMENT" value="" />

The __doPostBack() function has the responsibility for setting these values with the appropriate information about the event and then submitting the form. The __doPostBack() function is shown here:

<script language="text/javascript">
function __doPostBack(eventTarget, eventArgument) {
    if (!theForm.onsubmit || (theForm.onsubmit() != false)) {
        theForm.__EVENTTARGET.value = eventTarget;
        theForm.__EVENTARGUMENT.value = eventArgument;
        theForm.submit();
    }
  ...
}
</script>

Remember, ASP.NET generates the __doPostBack() function automatically, provided at least one control on the page uses automatic postbacks.

Finally, any control that has its AutoPostBack property set to True is connected to the __doPostBack() function using the onclick or onchange attributes. These attributes indicate what action the browser should take in response to the client-side JavaScript events onclick and onchange.

The following example shows the tag for a list control named lstBackColor, which posts back automatically. Whenever the user changes the selection in the list, the client-side onchange event fires. The browser then calls the __doPostBack() function, which sends the page back to the server.

<select ID="lstBackColor" onchange="__doPostBack('lstBackColor','')"
 language="javascript">

In other words, ASP.NET automatically changes a client-side JavaScript event into a server-side ASP.NET event, using the __doPostBack() function as an intermediary. Figure 6-13 shows this process.

Figure 6.13. An automatic postback

To understand how web control events work, you need to have a solid understanding of the page life cycle. Consider what happens when a user changes a control that has the AutoPostBack property set to True:

To watch these events in action, it helps to create a simple event tracker application. All this application does is write a new entry to a list control every time one of the events it's monitoring occurs. This allows you to see the order in which events are triggered. Figure 6-14 shows what the window looks like after it's been loaded once, posted back (when the text box content was changed), and posted back again (when the check box state was changed).

Figure 6.14. The event tracker

Listing 6-1 shows the markup code for the event tracker, and Listing 6-2 shows the code-behind class that makes it work.

<%@ Page Language="VB" AutoEventWireup="false"
    CodeFile="EventTracker.aspx.vb" Inherits="EventTracker" %>
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
  <title>Event Tracker</title>
</head>
<body>
  <form runat="server">
    <div>
      <h1>Controls being monitored for change events:</h1>
      <asp:TextBox ID="txt" runat="server" AutoPostBack="True" />
      <br /><br />
      <asp:CheckBox ID="chk" runat="server" AutoPostBack="True" />

<br /><br />
      <asp:RadioButton ID="opt1" runat="server" GroupName="Sample"
       AutoPostBack="True" />
      <asp:RadioButton ID="opt2" runat="server" GroupName="Sample"
       AutoPostBack="True" />

      <h1>List of events:</h1>
      <asp:ListBox ID="lstEvents" runat="server" Width="355px"
       Height="150px" /><br />
      <br /><br /><br />
    </div>
  </form>
</body>
</html>

Public Partial Class EventTracker
    Inherits System.Web.UI.Page

    Protected Sub Page_Load(ByVal sender As Object, _
      ByVal e As EventArgs) Handles Me.Load
        Log("<< Page_Load >>")
    End Sub

    Protected Sub Page_PreRender(ByVal sender As Object, _
      ByVal e As EventArgs) Handles Me.PreRender
        ' When the Page.PreRender event occurs it is too late
        ' to change the list.
        Log("Page_PreRender")
    End Sub

    ' This control handles an event from all four controls.
    Protected Sub CtrlChanged(ByVal sender As Object, _
      ByVal e As System.EventArgs) _
      Handles chk.CheckedChanged, opt1.CheckedChanged, opt2.CheckedChanged, _
              txt.TextChanged
        ' Find the control ID of the sender.
        ' This requires converting the Object type into a Control class.
        Dim ctrlName As String = CType(sender, Control).ID
        Log(ctrlName & " Changed")
    End Sub

    Private Sub Log(ByVal entry As String)
        lstEvents.Items.Add(entry)

        ' Select the last item to scroll the list so the most recent
        ' entries are visible.
        lstEvents.SelectedIndex = lstEvents.Items.Count - 1
    End Sub

End Class

ASP.NET pages have access to the full .NET class library. With a little exploration, you'll find classes that might help the greeting-card maker, such as tools that let you retrieve all the known color names and all the fonts installed on the web server.

For example, you can fill the lstFontName control with a list of fonts using the InstalledFontCollection class. To access it, you need to import the System.Drawing.Text namespace. You also need to import the System.Drawing namespace, because it defines the FontFamily class that represents the individual fonts that are installed on the web server:

Imports System.Drawing
Imports System.Drawing.Text

Here's the code that gets the list of fonts and uses it to fill the list:

' Get the list of available fonts, and add them to the font list.
Dim fonts As New InstalledFontCollection()
For Each family As FontFamily In fonts.Families
    lstFontName.Items.Add(family.Name)
Next

Figure 6-17 shows the resulting font list.

Figure 6.17. The font list

To get a list of the color names, you need to resort to a more advanced trick. Although you could hard-code a list of common colors, .NET actually provides a long list of color names in the System.Drawing.KnownColor enumeration. However, actually extracting the names from this enumeration takes some work.

The trick is to use a basic feature of all enumerations: the shared Enum.GetNames() method, which inspects an enumeration and provides an array of strings, with one string for each value in the enumeration. The web page can then use data binding to automatically fill the list control with the information in the ColorArray. (You'll explore data binding in much more detail in Chapter 15.)

Here's the code that copies all the color names into the list box:

' Get the list of colors.
Dim colorArray As String() = System.Enum.GetNames(GetType(KnownColor))
lstBackColor.DataSource = colorArray
lstBackColor.DataBind()

A minor problem with this approach is that it includes system environment colors (for example, ActiveBorder) in the list. It may not be obvious to the user what colors these values represent. Still, this approach works well for this simple application. You can use a similar technique to fill in BorderStyle options:

' Set border style options.
Dim borderStyleArray As String()
borderStyleArray = System.Enum.GetNames(GetType(BorderStyle))
lstBorder.DataSource = borderStyleArray
lstBorder.DataBind()

This code raises a new challenge: how do you convert the value that the user selects into the appropriate constant for the enumeration? When the user chooses a border style from the list, the SelectedItem property will have a text string like "Groove". But to apply this border style to the control, you need a way to determine the enumerated constant that matches this text.

You can handle this problem in a few ways. (Earlier, you saw an example in which the enumeration integer was stored as a value in the list control.) In this case, the most direct approach involves using an advanced feature called a TypeConverter. A TypeConverter is a special class that is able to convert from a specialized type (in this case, the BorderStyle enumeration) to a simpler type (such as a string), and vice versa.

To access this class, you need to import the System.ComponentModel namespace:

Imports System.ComponentModel

You can then add the following code to the cmdUpdate_Click event handler:

' Find the appropriate TypeConverter for the BorderStyle enumeration.
Dim converter As TypeConverter

converter = CType(TypeDescriptor.GetConverter(GetType(BorderStyle)), _
  TypeConverter)

' Update the border style using the value from the converter.
pnlCard.BorderStyle = converter.ConvertFromString(lstBorder.SelectedItem.Text)

This code gets the appropriate TypeConverter (in this case, one that's designed expressly to work with the BorderStyle enumeration). It then converts the text name (such as Solid) to the appropriate value (BorderStyle.Solid).

The last step is to use ASP.NET's automatic postback events to make the card update dynamically every time an option is changed. The Update button could now be used to submit the final, perfected greeting card, which might then be e-mailed to a recipient or stored in a database.

To configure the controls so they automatically trigger a page postback, simply set the AutoPostBack property of each input control to True. An example is shown here:

Choose a background color:<br />
<asp:DropDownList ID="lstBackColor" AutoPostBack="True" runat="server"
     Width="194px" Height="22px"/>

Next, you need to create an event handler that can handle the change events. To save a few steps, you can use the same event handler for all the input controls. All the event handler needs to do is call the update routine that regenerates the greeting card.

Protected Sub ControlChanged(ByVal sender As System.Object, _
  ByVal e As System.EventArgs) _
  Handles lstBackColor.SelectedIndexChanged, chkPicture.CheckedChanged, _
          txtFontSize.TextChanged, lstBorder.SelectedIndexChanged, _
          lstFontName.SelectedIndexChanged, lstForeColor.SelectedIndexChanged, _
          txtGreeting.TextChanged

    ' Refresh the greeting card (because a control was changed).
    UpdateCard()
End Sub

Protected Sub cmdUpdate_Click(sender As Object, e As EventArgs) _
  Handles cmdUpdate.Click

    ' Refresh the greeting card (because the button was clicked).
    UpdateCard()
End Sub

Private Sub UpdateCard()
    ' (The code that draws the greeting card goes here.)
End Sub

With these changes, it's easy to perfect the more extensive card-generating program shown in Figure 6-18. The full code for this application is provided with the online samples.

Figure 6.18. A more extensive card generator