Web Server Controls

IOTA^_^    

Sams Teach Yourself ASP.NET in 21 Days, Second Edition
By Chris Payne
Table of Contents
Appendix C.  ASP.NET Controls: Properties and Methods


Web server controls are objects that reside on the server, but render HTML that provides a familiar display to the browser. This section details each of these controls.

Common Web Server Control Properties

Table C.25 describes properties and methods that are available to all ASP.NET Web server controls inherited from the System.Web.UI.WebControls.WebControl class.

Table C.25. Properties and Methods Common to All Web Server Controls
Property Description
AccessKey Specifies a character that, when combined with the Alt key, represents a keyboard shortcut to the control. Supported only in Internet Explorer 4.0 and higher.
Attributes Returns an AttributeCollection object that represents the attributes for each control (this does not included defined properties).
BackColor The background color of the control.
BorderColor The border color of the control.
BorderStyle A border style. Possible values are Dashed, Dotted, Double, Inset, Groove, None, NotSet, Outset, Ridged, and Solid.
BorderWidth The width of the border around the control.
ControlStyle The style of the control (used when developing custom controls).
ControlStyleCreated Indicates whether the style associated with the control has been created.
CssClass The Cascading Style Sheets class to assign to the control.
Enabled Makes the control read-only if false.
Font The style attributes for the font displayed in the control.
ForeColor The color of the foreground of the control (the foreground is generally text).
Height The height of the control.
Style A CSSStyleCollection of attributes that are displayed for the control.
TabIndex The control's position in the tab order.
ToolTip Text that is displayed when the mouse cursor rests over the control.
Width The width of the control.
Method Description
ApplyStyle Applies any non-blank elements of the specified Style object to the control, overwriting existing styles.
CopyBaseAttributes Copies the AccessKey, Enabled, ToolTip, TabIndex, and Attributes properties from a specified server control to this control.
MergeStyle Applies any non-blank elements of the specified Style object to the control, without overwriting existing styles.
RenderBeginTag Renders the opening tag of the corresponding HTML output to the browser.
RenderEndTag Renders the closing tag of the corresponding HTML output to the browser.

Table C.26 describes properties and events that are available to all ASP.NET Web server list controls (CheckBoxList, DropDownList, ListBox, RadioButtonList) inherited from the System.Web.UI.WebControls.ListControl class.

Table C.26. Properties and Events Common to All Web Server List Controls
Property Description
AutoPostBack Indicates whether the form should be posted immediately upon the control's event.
DataMember The table name of a data source to use to fill the list control (used when DataSource is set to a DataSet).
DataSource The data source to use to fill the list control.
DataTextField The field in the data source used to provide the text content of the list control.
DataTextFormatString The format of the text in DataTextField.
DataValueField The field in the data source used to provide the value content of the list control.
Items A ListItemCollection of items of the list control.
SelectedIndex The index of the selected item. If multiple items are selected, this specifies the first one.
SelectedItem A ListItem representing the current selected item. If multiple items are selected, returns the first one.
Event Description
SelectedIndexChanged Occurs when the selected item has changed and the form is posted to the server.

Table C.27 describes properties, methods, and events that are available to all ASP.NET Web server datalist controls (DataList, DataGrid) inherited from the System.Web.UI.WebControls.BaseDataList class.

Table C.27. Properties, Methods, and Events Common to All Web Server Datalist Controls
Property Description
CellPadding The padding within the data cells.
CellSpacing The spacing between data cells.
DataKeyField The primary key field in the data source.
DataKeys A DataKeyCollection of the key fields in a data source.
DataMember The table name in the data source to use to fill the control with data (used when DataSource is set to a DataSet).
DataSource The data source with which to populate the datalist control.
GridLines The grid line style. Can be Both, Horizontal, None, or Vertical.
HorizontalAlign Specifies the alignment of rows with respect to the surrounding elements.
Method Description
DataBind Specifies whether a data type is bindable to the datalist control.
Event Description
SelectedIndexChanged Occurs when the selected item has changed and the form is posted to the server.

The ASP.NET Web Server Controls

The following sections detail all the available ASP.NET Web server controls. The syntax for all Web controls is as follows:

 <asp:controlName properties runat="server"/> 

For example, for the AdRotator control in the next section, a sample declaration would be

 <asp:AdRotator Target="blank" runat="server"/> 
AdRotator

This control displays a set of rotating advertisements, defined by an XML file. Table C.28 lists the properties and events of this server control.

Table C.28. Properties and Events of the AdRotator Control
Property Description
AdvertisementFile The path to an XML file containing advertisement information.
KeywordFilter A category filter that limits the ads displayed, according to categories in the XML advertisement file.
Target Specifies the target window to load the URL linked by an advertisement.
Event Description
AdCreated

Occurs after the creation of the control, before page rendering. Uses an AdCreateEventArgs object for the event parameter. This object contains the following properties:

AdProperties The properties for the current ad.

AlternateText The alternative text displayed for the image.

ImageUrl The URL of the image to display for the ad.

NavigateUrl The URL to which the ad directs users.

BoundColumn

Represents a column in a DataGrid that is bound with a field in a data source. Table C.29 lists the properties and methods of this server control.

Table C.29. Properties and Methods of the BoundColumn Control
Property Description
DataField The name of the data field bound to this column.
DataFormatString The format to display the data in this column.
ReadOnly Indicates whether the data in the column is read-only (often used in conjunction with EditCommandColumns).
Method Description
Initialize Initializes the column.
InitializeCell Initializes a cell in the column.

Button

Displays a simple HTML button. Table C.30 lists the properties and events of this server control.

Table C.30. Properties and Events of the Button Control
Property Description
CommandArgument The value propagated in the Command event with the associated CommandName property.
CommandName The command associated with the Command event.
Text The content of the control.
Event Description
Click Occurs when the button is clicked.
Command Same as Click.

ButtonColumn

Represents a column in a DataGrid control that displays a column with a set of buttons. Table C.31 lists the properties of this server control.

Table C.31. Properties of the ButtonColumn Control
Property Description
ButtonType Specifies the type of button to display. Can be LinkButton or PushButton.
CommandName A string that represents the command to perform when a button is clicked.
DataTextField The field name of the data source that is displayed in this column.
DataTextFormatString Indicates how the content from DataTextField should be formatted.
Text The caption displayed by the button.

Calendar

This control displays a fully customizable and interactive calendar in the browser. Table C.32 lists the properties and events of this server control.

Table C.32. Properties and Events of the Calendar Control
Property Description
CellPadding The padding within a day cell in the calendar.
CellSpacing The spacing between days cells in the calendar.
DayHeaderStyle The style for displaying the names of the days of the week.
DayNameFormat The format for displaying the names of the days of the week. Can be FirstLetter, FirstTwoLetters, Full, or Short.
DayStyle The style for displaying days.
FirstDayOfWeek The first day of the week to display in the calendar. Can be Default (as specified by the server) or any of the days Sunday through Saturday.
NextMonthText The text displayed for the next month navigation (for example, "Next" or ">").
NextPrevFormat The format of the next and previous month navigation links. Can be CustomText (default; use with NextMonthText and PrevMonthText), FullMonth, or ShortMonth.
NextPrevStyle The style for displaying next and previous month navigation links.
OtherMonthDayStyle The style for days displayed that are not in the current month.
PrevMonthText The text displayed for the previous month navigation link (for example, "Previous" or "<").
SelectedDate The selected date.
SelectedDates A collection of DateTime objects that represent the selected dates in the calendar.
SelectedDayStyle The style for selected days.
SelectionMode Specifies how a user is allowed to select dates (that is, only select individual days, select weeks at a time, and so on). Can be Day, DayWeek, DayWeekMonth, or None.
SelectMonthText The text displayed for the month selection link.
SelectorStyle The styles for the month and week selection links.
SelectWeekText The text displayed for the week selection link.
ShowDayHeader Specifies whether the days of the week header should be shown.
ShowGridLines Specifies whether grid lines between calendar days should be shown.
ShowNextPrevMonth Specifies whether the next and previous month navigation links are shown.
ShowTitle Specifies whether the title of the calendar should be shown.
TitleFormat The format for the title of the calendar. Can be Month or MonthYear.
TitleStyle The style of the title of the calendar.
TodayDayStyle The style for today's date on the calendar.
TodaysDate Specifies today's date.
VisibleDate The date that specifies the month that is currently visible in the calendar. (Note that the selected date and visible date do not have to coincide.)
WeekendDayStyle The style for weekends in the calendar.
Event Description
DayRender Occurs when each day cell is created in the calendar. Uses a DayRenderEventArgs object for the event parameter. This object contains the following properties:

Cell A TableCell object that represents the cell being rendered in the calendar.

Day A CalendarDay that represents the day being rendered in the calendar.

SelectionChanged Occurs when the user selects a day, week, or month.
VisibleMonthChanged Occurs when the user navigates to a different month. Uses a MonthChangedEventArgs object for the event parameter. This object contains the following properties:

NewDate The date that determines the currently visible month.

PreviousDate The date that determines the previously visible month.

CheckBox

This control represents an HTML form check box. Table C.33 lists the properties and events of this server control.

Table C.33. Properties and Events of the CheckBox Control
Property Description
AutoPostBack Indicates whether the form should be posted immediately upon the CheckedChanged event.
Checked Indicates whether the control is checked.
Text The text to display next to the check box.
TextAlign The alignment of the text associated with this control.
Event Description
CheckedChanged Occurs when the Checked property changes.

CheckBoxList

This control displays a list of checkboxes in the browser that describe related information. Table C.34 lists the properties of this server control.

Table C.34. Properties of the CheckBoxList Control
Property Description
CellPadding The padding within the cells containing the CheckBox controls.
CellSpacing The distance between the cells containing the CheckBox controls.
RepeatColumns The number of columns to use to display the CheckBox controls.
RepeatDirection Specifies whether the CheckBox controls should be repeated horizontally (Horizontal) or vertically (Vertical).
RepeatLayout The layout of the CheckBox list. Can be Table (to display the controls in a table) or Flow (without a table).
TextAlign The alignment for the text associated with each CheckBox.

DataGrid

This control displays a complex table from a supplied data source. Table C.35 lists the properties, and events of this server control.

Table C.35. Properties, and Events of the DataGrid Control
Property Description
AllowCustomPaging Indicates whether custom paging is enabled.
AllowPaging Indicates whether paging is enabled.
AllowSorting Indicates whether sorting is enabled.
AlternatingItemStyle Style properties for alternating items in the DataGrid.
AutoGenerateColumns Indicates whether the DataGrid should automatically generate BoundColumn columns using the data supplied in a data source (the DataGrid will use all fields in the data source to do so).
BackImageUrl The URL of an image to display in the background of the control.
Columns A collection of objects that represent the columns in the DataGrid.
CurrentPageIndex The index of the current page.
EditItemIndex The index of the item in the DataGrid to edit (this causes BoundColumn column to become editable, unless specified as read-only).
EditItemStyle The style for items that are in edit mode.
FooterStyle The style of the footer in the DataGrid.
HeaderStyle The style of the header in the DataGrid.
Items A collection of DataGridItems that represent the individual items in the DataGrid.
ItemStyle The style of the items in the DataGrid.
PageCount The total number of pages used to completely display the data in the DataGrid.
PagerStyle The style of the paging links.
PageSize Specifies the number of items to display on a single page.
SelectedIndex The index of the currently selected item.
SelectedItem The selected item.
SelectedItemStyle The style of the selected item.
ShowFooter Indicates whether the footer should be shown.
ShowHeader Indicates whether the header should be shown.
VirtualItemCount Indicates the number of total items to be displayed by the DataGrid. Used only when AllowCustomPaging is set to true.
Event Description
CancelCommand Occurs when button is clicked with the CommandName property set to "Cancel". Uses a DataGridCommandEventArgs object for the event parameter. This object contains the following properties:

CommandArgument The argument for the command.

CommandName The name of the command.

CommandSource The object that raised the command.

Item The selected item in the list.

DeleteCommand Occurs when button is clicked with the CommandName property set to "Delete". Uses a DataGridCommandEventArgs object.
EditCommand Occurs when button is clicked with the CommandName property set to "Edit". Uses a DataGridCommandEventArgs object.
ItemCommand Occurs when button is clicked. Uses a DataGridCommandEventArgs object.
ItemCreated Occurs immediately before an item is created in the DataGrid. Uses the DataGridItemEventArgs object for the event parameter. This object contains the following property:

Item The currently selected item.

ItemDataBound Occurs when data is bound to an item in the DataGrid. Uses the DataGridItemEventArgs object.
PageIndexChanged Occurs when one of the pager links is clicked. Uses the DataGridPageChangedEventArgs object for the event parameter. This object contains the following properties:

CommandSource The object that generated the command.

NewPageIndex The index of the newly selected page.

SortCommand Occurs when a column is sorted. Uses the DataGridSortCommandEventArgs object for the event parameter. This object contains the following properties:

CommandSource The object that generated the command.

SortExpression The expression used to sort the DataGrid.

UpdateCommand Occurs when button is clicked with the CommandName property set to "Update". Uses a DataGridCommandEventArgs object.

DataList

This control renders a customized display from a supplied data source, using templates. Table C.36 lists the fields, properties, and events of this server control.

Table C.36. Fields, Properties, and Events of the DataList Control
Field Description
CancelCommandName The name of the Cancel command.
DeleteCommandName The name of the Delete command.
EditCommandName The name of the Edit command.
SelectCommandName The name of the Select command.
UpdateCommandName The name of the Update command.
Property Description
AlternatingItemStyle Style properties for alternating items in the DataList.
AlternatingItemTemplate The template to use for alternating items in the DataList.
EditItemIndex The index of the item in the DataList to edit.
EditItemStyle The style for items that are in edit mode.
EditItemTemplate The template to use for items that are in edit mode.
ExtractTemplateRows Indicates whether template rows should be extracted.
FooterStyle The style of the footer in the DataList.
FooterTemplate The template to use for the footer.
GridLines Indicates the type of grid lines to use. Can be Both, Horizontal, None, or Vertical.
HeaderStyle The style of the header in the DataList.
HeaderTemplate The template to use for the header.
Items A collection of DataListItems that represent the individual items in the DataList.
ItemStyle The style of the items in the DataList.
ItemTemplate The template to use for generic items in the DataList.
RepeatColumns The number of columns to use to display the data.
RepeatDirection The direction to repeat the data items. Can be Horizontal or Vertical.
RepeatLayout The layout for items to be displayed. Can be Table or Flow.
SelectedIndex The index of the currently selected item.
SelectedItem The selected item.
SelectedItemStyle The style of the selected item.
SelectedItemTemplate The template to use to display to currently selected item.
SeparatorStyle The style of the separator between items.
SeparatorTemplate The template to use to display separators between items in the DataList.
ShowFooter Indicates whether the footer should be shown.
ShowHeader Indicates whether the header should be shown.
Event Description
CancelCommand Occurs when an event is raised with the Command property set to "Cancel". Uses a DataListCommandEventArgs object for the event parameter. This object contains the following properties:

CommandArgument The argument for the command.

CommandName The name of the command.

CommandSource The object that raised the command.

Item The selected item in the list.

DeleteCommand Occurs when an event is raised with the Command property set to "Delete". Uses the DataListCommandEventArgs object.
EditCommand Occurs when an event is raised with the Command property set to "Edit". Uses the DataListCommandEventArgs object.
ItemCommand Occurs when an event is raised. Uses the DataListCommandEventArgs object.
ItemCreated

Occurs immediately before an item is created in the DataGrid. Uses the DataListItemEventArgs object for the event parameter. This object contains the following property:

Item The currently selected item.

ItemDataBound Occurs when data is bound to an item in the DataGrid. Uses the DataListItemEventArgs object.
UpdateCommand Occurs when an event is raised with the Command property set to "Update". Uses the DataListCommandEventArgs object.

DropDownList

This control represents a dropdown list of selectable items. Table C.37 lists the properties of this server control.

Table C.37. Properties of the DropDownList Control
Property Description
BorderColor The color of the border surrounding the list box.
BorderStyle The style of the border surrounding the list box.
BorderWidth The width of the border surrounding the list box.
SelectedIndex The index of the currently selected item.

EditCommandColumn

This control represents a column in a DataGrid that displays links allowing users to edit fields. Table C.38 lists the properties of this server control.

Table C.38. Properties of the EditCommandColumn Control
Property Description
ButtonType The type of buttons to display. Can be LinkButton or PushButton.
CancelText The text to display for the cancel button.
EditText The text to display for the edit button.
UpdateText The text to display for the update button.

HyperLink

This control represents an HTML hyperlink. Note that it does not generate any events; it simply redirects users. To generate events that can be handled, use the LinkButton control. Table C.39 lists the properties of this server control.

Table C.39. Properties of the HyperLink Control
Property Description
ImageUrl The URL of an image to display for the link.
NavigateUrl The URL that this link directs users to.
Target The target window to display the linked content in.
Text The text to display for the link.

HyperLinkColumn

Represents a column in a DataGrid that is bound with a field in a data source. These fields will become navigable hyperlinks. Table C.40 lists the properties and methods of this server control.

Table C.40. Properties and Methods of the HyperLinkColumn Control
Property Description
DataNavigateUrlField The name of the data field that provides the link for this column.
DataNavigateUrlFormatString The format to display the data field that provides the link in this column.
DataTextField The name of the data field that contains the text to display for the link.
DataTextFormatString The format to display the data containing the text to display links.
NavigatUrl The URL to navigate to when a link is clicked.
Target The window to display the page loaded by the URL.
Text The text to display for the link.
Method Description
Initialize Initializes the column.
InitializeCell Initializes a cell in the column.

Image

This control represents an image displayed in the browser. Table C.41 lists the properties of this server control.

Table C.41. Properties of the Image Control
Property Description
AlternateText The text to display in place of the image.
Enabled Indicates whether the control is enabled.
Font The font properties for the alternative text.
ImageAlign The alignment of the image on the page with respect to other UI elements.
ImageUrl The URL of the image to display.

ImageButton

This control represents an HTML form button with an image instead of a push-style button. Table C.42 lists the properties and events of this server control.

Table C.42. Properties and Events of the ImageButton Control
Property Description
CommandArgument An argument that provides additional information about the CommandName property.
CommandName The name of the command to execute when this image is clicked.
Event Description
Click Occurs when the image is clicked.
Command Occurs when the image is clicked.

Label

This control displays text in the browser. Table C.43 lists its only property.

Table C.43. Properties of the Label Control
Property Description
Text The text to display in the browser.

LinkButton

This control represents an HTML form button with a link instead of a push-style button. Table C.44 lists the properties and events of this server control.

Table C.44. Properties and Events of the LinkButton Control
Property Description
CommandArgument An argument that provides additional information about the CommandName property.
CommandName The name of the command to execute when this image is clicked.
Text The text to display for the link.
Event Description
Click Occurs when the image is clicked.
Command Occurs when the image is clicked.

ListBox

This control represents a dropdown list of selectable items. Table C.45 lists the properties of this server control.

Table C.45. Properties of the ListBox Control
Property Description
BorderColor The color of the border surrounding the list box.
BorderStyle The style of the border surrounding the list box.
BorderWidth The width of the border surrounding the list box.
Rows The number of rows to display in the list box.
SelectionMode Allows single (Single) or multiple (Multiple) selections in the list box.

Panel

This control represents a container for other controls. Table C.46 lists the properties of this server control.

Table C.46. Properties of the Panel Control
Property Description
BackImageUrl The image to display in the background of this control.
HorizontalAlign The horizontal alignment for the content within this control.
Wrap Indicates whether the control's contents should wrap.

RadioButton

This control represents an HTML radio button. It inherits from the CheckBox control, so all of the CheckBox's events and properties are available to it as well. Table C.47 lists the only unique property of this server control.

Table C.47. Properties of the RadioButton Control
Property Description
GroupName The name of the group to which this radio button belongs.

RadioButtonList

This control displays a list of radio buttons in the browser that describe related information. Table C.48 lists the properties of this server control.

Table C.48. Properties of the RadioButtonList Control
Property Description
CellPadding The padding within the cells containing the RadioButton controls.
CellSpacing The distance between the cells containing the RadioButton controls.
RepeatColumns The number of columns to use to display the RadioButton controls.
RepeatDirection Specifies whether the RadioButton controls should be repeated horizontally (Horizontal) or vertically (Vertical).
RepeatLayout The layout of the RadioButton list. Can be Table (to display the controls in a table) or Flow (without a table).
TextAlign The alignment for the text associated with each RadioButton.

Repeater

This control renders a customized display from a supplied data source, using templates. Table C.49 lists the properties and events of this server control.

Table C.49. Properties and Events of the Repeater Control
Property Description
AlternatingItemTemplate The template to use for alternating items in the Repeater.
DataMember The specific table to use for data binding (used when DataSource is set to a DataSet).
DataSource The data source to use for data binding.
FooterTemplate The template to use for the footer.
HeaderTemplate The template to use for the header.
Items A collection of RepeaterItems that represent the individual items in the Repeater.
ItemTemplate The template to use for generic items in the Repeater.
SeparatorTemplate The template to use to display separators between items in the Repeater.
Event Description
ItemCommand Occurs when an event is raised. Uses the RepeaterCommandEventArgs object for the event parameter. This object contains the following properties:

CommandArgument The argument for the command.

CommandName The name of the command.

CommandSource The object that raised the command.

Item The RepeaterItem associated with the event.

ItemCreated Occurs immediately before an item is created in the DataGrid. Uses the RepeaterItemEventArgs object for the event parameter. This object contains the following property:

Item The currently selected item.

ItemDataBound Occurs when data is bound to an item in the Repeater. Uses the RepeaterItemEventArgs object.

Table, TableCell, TableRow

These controls represent all the elements of an HTML table. Table C.50 lists the properties of the Table control.

Table C.50. Properties of the Table Server Control
Property Description
BackImageUrl The URL of the image to display in the background of the table.
CellPadding The padding within cells.
CellSpacing The spacing between cells.
GridLines The style of gridlines in the table. Can be Both, Horizontal, None, or Vertical.
HorizontalAlign The horizontal alignment of the table in the page.
Rows Returns a TableRowCollection object representing all rows in the table.

Table C.51 lists the properties of the TableCell server control. Note that there also is a TableHeaderCell object that derives from the TableCell object and contains the same properties.

Table C.51. Properties of the TableCell Control
Property Description
ColumnSpan The number of columns this cell spans.
HorizontalAlign The horizontal alignment of the content within the cell.
RowSpan The number of rows this cell spans.
Text The text contained in the cell.
VerticalAlign The vertical alignment of text within this cell.
Wrap Indicates whether the cell's contents should wrap.

Table C.52 lists the properties of the TableRow server control.

Table C.52. Properties of the TableRow Control
Property Description
Cells Returns a TableCellCollection representing the cells contained in this row.
HorizontalAlign The horizontal alignment of the content within the cells.
VerticalAlign The vertical alignment of the cells within this row.

TemplateColumn

This control represents a column in a DataGrid. Table C.53 lists the properties of this server control.

Table C.53. Properties of the TemplateColumn Control
Property Description
EditItemTemplate Gets the template that defines how items in edit mode are displayed.
FooterTemplate Gets the template that defines how footers are displayed.
HeaderTemplate Gets the template that defines how headers are displayed.
ItemTemplate Gets the template that defines how generic items are displayed.

TextBox

This control represents an HTML text box. Table C.54 lists the properties and events of this server control.

Table C.54. Properties and Events of the TextBox Control
Property Description
AutoPostBack Indicates whether the form should be posted immediately upon the TextChanged event.
Columns The display width of the control, in characters.
MaxLength The maximum number of characters allowable in the text box.
ReadOnly Indicates whether the content in the text box is editable.
Rows The number of rows to display for a multiline text box.
Text The text to display.
TextMode The behavior of the text box. Can be MultiLine, Password, or SingleLine (default).
Wrap Indicates whether text should wrap in a multiline text box.
Event Description
TextChanged Occurs when the form is submitted and the Text property is different than the previous post.


    IOTA^_^    
    Top


    Sams Teach Yourself ASP. NET in 21 Days
    Sams Teach Yourself ASP.NET in 21 Days (2nd Edition)
    ISBN: 0672324458
    EAN: 2147483647
    Year: 2003
    Pages: 307
    Authors: Chris Payne

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