WebControls

I l @ ve RuBoard

WebControls are all derived from System.Web.UI.WebControls.WebControl , which itself derives from the Control class. The hierarchy of WebControls thus looks very similar to the HtmlControl class hierarchy from Figure 5.1. Figure 5.4 shows the WebControl class hierarchy.

Figure 5.4. WebControls class hierarchy.

For this chapter, we'll be looking at the controls on the left side of Figure 5.4. Most of the more complex controls are covered in the next few chapters.

WebControl Properties

To begin, though, we should take a look at the WebControl class itself, because all of its properties and methods are built into every WebControl. The most commonly used properties of the WebControl class are detailed in Table 5.11.

Table 5.11. WebControl Properties
Property Description
AccessKey : String Gets or sets a keyboard key to be used as a shortcut for setting focus to this control.
Attributes : AttributeCollection Same as for HtmlControl.
BackColor : Color Gets or sets the background color of the control. Defaults to Empty .
BorderColor : Color Gets or sets the border color of the control. Defaults to Empty .
BorderStyle : BorderStyle Gets or sets the border style of the control. Defaults to NotSet .
BorderWidth : Unit Gets or sets the border width of the control. Defaults to Empty .
CssClass : String Gets or sets the CSS class for the control. Defaults to Empty .
Enabled : Boolean Gets or sets a value indicating whether the control is enabled. Defaults to true.
Font : FontInfo Gets font information from the control.
ForeColor : Color Gets or sets the foreground color of the control. Typically used for the text of the control. Defaults to Empty .
Height : Unit Gets or sets the height of the control. Defaults to Empty .
Style : CssStyleCollection Same as for HtmlControl.
TabIndex : Int16 Gets or sets the tab index of the control. Used to determine the tab order on the page. Defaults to 0.
ToolTip : String Gets or sets the tool tip value for the control. Defaults to Empty .
Width : Unit Gets or sets the width of the control. Defaults to Empty .

At first glance, you can easily see that the WebControl base class has a lot more properties than the HtmlControl base class. In addition to those properties listed here, WebControls also share all of the properties and methods of the System.Web.UI.Control class, such as the ones in italics in the description of the HtmlControl class at the start of this chapter. Furthermore, notice that almost all of the properties are strongly typed to custom datatypes. Instead of using a string for colors and an integer for pixel lengths like many of the HtmlControls do, the WebControl class uses a Color class and a Unit class to allow for strongly typed property setting. This makes for code that is easier to read and debug at compile time as opposed to runtime.

As with the HtmlControls, it is fairly simple to create a single ASP.NET page that demonstrates the use of every WebControl we will be covering in this chapter. Figure 5.5 shows what this page looks like in a browser.

Figure 5.5. WebControlsDemo.aspx.

As with the HtmlControls section, we'll go ahead and look at the complete source code for our demo page before we go through each control as it appears on the page. Listing 5.2 shows the source for our example.

Listing 5.2 WebControlsDemo.aspx.
 <%@ Page language="c#" Codebehind="WebControlsDemo.aspx.cs" Src="WebControlsDemo.aspx.cs" AutoEventWireup="false" Inherits="ASPAuthors.aspnetbyexample.ch05.WebControlsDemo" %> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" > <HTML>   <HEAD>           <title>WebControls</title> </HEAD>      <body>           <h1>                WebControls           </h1>           <form id="WebControls" method="post" runat="server">                <table>                     <tr>                          <td>                               Button                          </td>                          <td>                               <asp:Button runat="server" id=Button1></asp:Button>                          </td>                     </tr>                     <tr>                          <td>                               Checkbox                          </td>                          <td>                               <asp:CheckBox runat="server"                               id=CheckBox1></asp:CheckBox>                          </td>                     </tr>                     <tr>                          <td>                               RadioButton                          </td>                          <td>                               <asp:RadioButton runat="server" id="RadioButton1"                               GroupName="Group"></asp:RadioButton>                               <asp:RadioButton runat="server" id="RadioButton2"                               GroupName="Group"></asp:RadioButton>                          </td>                     </tr>                     <tr>                          <td>                               HyperLink                          </td>                          <td>                               <asp:HyperLink runat="server"                               id=HyperLink1></asp:HyperLink>                          </td>                     </tr>                     <tr>                          <td>                               Image                          </td>                          <td>                               <asp:Image runat="server" id=Image1></asp:Image>                          </td>                     </tr>                     <tr>                          <td>                               ImageButton                          </td>                          <td>                               <asp:ImageButton runat="server"                               id=ImageButton1></asp:ImageButton>                          </td>                     </tr>                     <tr>                          <td>                               Label                          </td>                          <td>                               <asp:Label runat="server" id=Label1></asp:Label>                          </td>                     </tr>                     <tr>                          <td>                               LinkButton                          </td>                          <td>                               <asp:LinkButton runat="server"                               id=LinkButton1></asp:LinkButton>                          </td>                     </tr>                     <tr>                          <td>                               Literal                          </td>                          <td>                               <asp:Literal runat="server" id=Literal1></asp:Literal>                          </td>                     </tr>                     <tr>                          <td>                               Panel                          </td>                          <td>                               <asp:Panel runat="server" id=Panel1></asp:Panel>                          </td>                     </tr>                     <tr>                          <td>                               PlaceHolder                          </td>                          <td>                               <asp:PlaceHolder runat="server"                               id=PlaceHolder1></asp:PlaceHolder>                          </td>                     </tr>                     <tr>                          <td>                               Table, Row, Cell                          </td>                          <td>                               <asp:Table runat="server" id=Table1> <asp:TableRow id="TableRow1" runat="server"> <asp:TableCell id="TableCell1" runat="server"></asp:TableCell></asp:TableRow>                               </asp:Table>                          </td>                     </tr>                     <tr>                          <td>                               TextBox                          </td>                          <td>                               <asp:TextBox runat="server" id=TextBox1></asp:TextBox>                          </td>                     </tr>                     <tr>                          <td>                               XML                          </td>                          <td>                               <asp:Xml runat="server" id=Xml1></asp:Xml>                          </td>                     </tr>                </table>           </form>      </body> </HTML> 

Some of the values in this example are set in the codebehind; the complete source is available on the book's Web site at http://aspauthors.com/aspnetbyexample/ch05/.

Button

The Button WebControl is used to render any HTML button, and supports Click or custom Command events. Its properties are described in Table 5.12.

Table 5.12. Button Properties
Property Description
CausesValidation : Boolean Gets or sets a value that determines whether clicking this control causes ValidationControls to execute their behavior. Defaults to true.
CommandArgument : String Gets or sets an optional parameter that would be passed to the Command event. Should be used in conjunction with the CommandName property. Defaults to Empty .
CommandName : String Gets or sets the command name associated with the control. Defaults to Empty .
Text : String Gets or sets the text displayed in the control.

For our example, the only one of these properties we used was the Text property, which we set to " Button Control " using code. The CausesValidation property is a good one to remember because any page that has multiple buttons, only some of which are used to submit values, should have the other buttons ' CausesValidation property set to false.

In addition to these properties, the Button control supports two events: Click and Command . The Click event is fired whenever the button is clicked. The Command event is fired if there is a CommandName specified, in which case the name specified in CommandName determines the signature of the event handler that is expected. Using CommandName and CommandArgument , you can specify a particular command to execute, such as a sort , and specify a single argument for that command, such as ascending .

CheckBox

The CheckBox control exposes the properties described in Table 5.13.

Table 5.13. CheckBox Properties
Property Description
AutoPostBack : Boolean Gets or sets a value that determines whether a change to this control should result in an automatic form postback. Defaults to false.
Checked : Boolean Gets or sets whether or not the control is checked. Defaults to false.
Text : String Gets or sets the text label associated with the control. Defaults to Empty .
TextAlign : TextAlign Gets or sets the alignment of the text label (that is, which side of the control the text appears on). The default is Right .

In our example, we have set the AutoPostBack value of CheckBox to true, so checking or unchecking the box results in the form posting immediately. The CheckBox control also supports one event, CheckedChanged , which is fired on any postback where the value of the check box has changed. The use of this control is also covered in the example from Listing 5.2.

RadioButton

The RadioButton control is a subclass of the CheckBox control, so it includes all of that control's behavior. In addition, it has the GroupName : String property, which gets or sets the name of the group to which the radio button belongs. Only one RadioButton in a group can be set at a time. Defaults to Empty .

To demonstrate the use of the GroupName property, the example uses two radio buttons with the same group name. Thus, only one or the other of the two buttons can be selected at a time, which is how one typically uses the radiobutton control.

HyperLink

The HyperLink control simply renders a link on a page, which can be either text or an image. Table 5.14 describes the HyperLink properties.

Table 5.14. HyperLink Properties
Property Description
ImageUrl : String Gets or sets the URL for the image to be used by this link. If set, the Text property is used for the ALT text of the image. Defaults to Empty .
NavigateUrl : String Gets or sets the URL to which the hyperlink should link. Defaults to Empty .
Target : String Gets or sets the frame or window that should load the page linked to by NavigateUrl . Defaults to Empty .
Text : String Gets or sets the text caption for the link. Defaults to Empty .

HyperLinks are fairly simple controls, and do not support any events.

Image

The Image WebControl renders an image on a page. Table 5.15 describes the Image properties.

Table 5.15. Image Properties
Property Description
AlternateText : String Gets or sets the alternate text that is displayed in place of the image when the image is unavailable, or as a ToolTip.
Enabled : Boolean This property doesn't appear to be implemented in ASP.NET Beta 2.
Font : FontInfo Gets or sets the font properties of the alternate text. This property has no effect in Internet Explorer.
ImageAlign : ImageAlign Gets or sets the alignment of the Image in relation to other page elements. Defaults to NotSet . Allowable values include NotSet , Left , Right , Baseline , Top , Middle , Bottom , AbsBottom , AbsMiddle , and TextTop .
ImageUrl : String Gets or sets the location of an image to display in the control.

The Image control does not support any events. As with all WebControls, the Image control has properties for height and width that can be used to control the size of the image to be rendered.

ImageButton

The ImageButton WebControl inherits from the Image WebControl, and thus has all of its properties. In addition, the ImageButton has several additional properties and events that make it behave like a Button . It includes the following properties: CausesValidation : Boolean , CommandArgument : String , and CommandName : String , which function in the same way as the Button properties of the same name.

In addition, the ImageButton supports the Click and Command events, which behave just like the corresponding events for the Button WebControl.

Label

The Label is a very simple WebControl that simply renders text on a page. Label has the Text : String property, which gets or sets the value that is rendered by the Label.

Note that the Label control always renders its Text property within a <span> tag. If you want to only output specific text to the browser with no extra tags, you should use the Literal WebControl.

LinkButton

The LinkButton is another variant of the Button control, which renders on the page as a hyperlink. Table 5.16 shows its properties.

Table 5.16. LinkButton Properties
Property Description
CausesValidation : Boolean Same as for Button .
CommandArgument : String Same as for Button .
CommandName : String Same as for Button .
Text : String Gets or sets the value that is rendered on the page as the hyperlink.

The LinkButton also supports the Click and Command events, which behave just like the corresponding events for the Button WebControl.

Literal

The Literal control is the simplest of all the WebControls. It has the Text : String property and simply gets or sets the text to be output to the browser, outputting the contents of that property to the page when it is rendered.

You'll want to use the Literal control instead of a Label whenever you need complete control over the HTML you will output, such as if you are setting the content of a <title> tag. For instance:

 <title><asp:Literal runat="server" id="litTitle"/></title> 

Panel

The Panel WebControl acts as a container for other controls, which lets you adjust the style and visibility of many controls at once. This can be useful if you want to create a single ASP.NET page that has several pages of content, like a "wizard" application. Table 5.17 describes the properties of the Panel control.

Table 5.17. Panel Properties
Property Description
BackImageUrl : String Gets or sets the URL for the background image of the control. Defaults to Empty .
HorizontalAlign : HorizontalAlign Gets or sets the horizontal alignment of the controls in the Panel . Defaults to NotSet .
Wrap : Boolean Gets or sets a value determining whether controls in the Panel should wrap. Defaults to true.

Panels do not support any additional events. One of the WebControl properties that is most commonly used with the Panel control is the Visible property. By positioning several Panel s over the tops of one another, you can create a single page that acts like a wizard control by having tabs that make one Panel invisible and another visible. This is just one of the more common uses for the Panel control.

PlaceHolder

The PlaceHolder control simply provides a bookmark to a point in a page. It is used to allow you to programmatically insert controls at a specific point on an ASP.NET page. Because it doesn't render any UI itself, or have any purpose other than to provide a placeholder, the PlaceHolder control has no other properties or methods.

Table , TableRow , and TableCell

The Table , TableRow , and TableCell controls are very similar to the HtmlControls that serve the same purpose. You can use them to programmatically build HTML tables. Table 5.18 describes the Table WebControl properties.

Table 5.18. Table Properties
Property Description
BackImageUrl : String Gets or sets the URL of the image to display as the background for the table. Defaults to Empty .
CellPadding : Int32 Gets or sets the distance in pixels between the border and the contents of any cell in the table. Defaults to “1 (not set).
CellSpacing : Int32 Gets or sets the distance in pixels between table cells . Defaults to “1 (not set).
GridLines : GridLines Gets or sets a value determining how the gridlines of the table are displayed. Options for the GridLines Enum currently include Both , None , Horizontal , or Vertical .
HorizontalAlign : HorizontalAlign Gets or sets a value determining how the table is aligned within the page. Possible values include Center , Justify , Left , NotSet , and Right .
Rows : TableRowCollection Gets a reference to the collection of Row objects in the table.

Within a table, there are typically one or more TableRow controls, and these are accessed via the Rows collection. Table 5.19 describes the properties of each TableRow .

Table 5.19. TableRow Properties
Property Description
Cells : TableCellCollection Gets a collection of TableCell objects that represent the cells of this row in the Table control.
HorizontalAlign : HorizontalAlign Gets or sets the horizontal alignment to be used by the contents of the row.
VerticalAlign : VerticalAlign Gets or sets the vertical alignment to be used by the contents of the row.

Finally, Table 5.20 describes the properties of the TableCell control.

Table 5.20. TableCell Properties
Properties Description
ColumnSpan : Int32 Gets or sets a value determining how many columns the cell should span. Corresponds to the ColSpan HTML attribute. Defaults to 1.
HorizontalAlign : HorizontalAlign Gets or sets the horizontal alignment to be used by the contents of the cell.
RowSpan : Int32 Gets or sets a value determining how many rows the cell should span. Corresponds to the RowSpan HTML attribute. Defaults to 1 .
Text : String Gets or sets the text contents of the cell. Defaults to Empty .
VerticalAlign : VerticalAlign Gets or sets the vertical alignment to be used by the contents of the cell.
Wrap : Boolean Gets or sets a value that determines whether the contents of the cell should wrap. Defaults to true.

TextBox

The TextBox WebControl is one of the most commonly used WebForm controls for gathering user input. In addition, this one control can be configured to display as a password control, a regular text input control, or a multiline textarea control. Table 5.21 describes its properties.

Table 5.21. TextBox Properties
Property Description
AutoPostBack : Boolean Gets or sets a value that determines if the control does an automatic postback whenever a user changes its contents. Defaults to false.
Columns : Int32 Gets or sets the width of the text box in characters . Defaults to .
MaxLength : Int32 Gets or sets the maximum number of characters the text box can hold. Defaults to (unlimited).
ReadOnly : Boolean Gets or sets a value determining if the contents of the TextBox can be changed. Defaults to false.
Rows : Int32 Gets or sets the height of the TextBox in rows. Defaults to 0. Only applies to MultiLine TextMode .
Text : String Gets or sets the contents of the TextBox . Defaults to Empty .
TextMode : TextBoxMode Gets or sets the behavior of the TextBox . Can be either MultiLine , Password , or SingleLine . Defaults to SingleLine .
Wrap : Boolean Gets or sets a value indicating whether the text content wraps within the text box. Defaults to true.

The TextBox control also includes one event, TextChanged , which is fired whenever the user changes the content of the TextBox and posts back the page.

This brings us to our last WebControl (finally!), the Xml WebControl.

Xml

The Xml WebControl is a bit more advanced than the other controls and allows you to display and transform XML documents on your ASP.NET page. Complete coverage of this control is beyond the scope of this book; however, its properties are described in Table 5.22 for completeness's sake.

Table 5.22. Xml Properties
Property Description
Document : XmlDocument Gets or sets the XmlDocument to display on the page.
DocumentContent : String Gets or sets a string that contains the XML document to display in the control.
DocumentSource : String Gets or sets the URL to an XML document to display in the control.
Transform : XslTransform Gets or sets the XslTransform object that transforms the XML document before it is output.
TransformArgumentList Gets a collection of arguments used in the : XsltArgumentList transformation process.
TransformSource : String Gets or sets the URL to the XSLT document to use to format the XML document before it is output.

For outputting XML data to the client that you want to build programmatically, the Xml WebControl is the way to go.

I l @ ve RuBoard


Asp. Net. By Example
ASP.NET by Example
ISBN: 0789725622
EAN: 2147483647
Year: 2001
Pages: 154

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net