The CheckBoxList Web control provides a multi-selection check box group that can be dynamically generated using data binding.
Note You can also use the CheckBox control. The CheckBoxList control is easier for data binding, while the individual CheckBox control gives you greater control over the layout of the controls.
Required properties are noted in boldface type.
<asp:CheckBoxList id="CheckBoxList1" runat="server" AutoPostBack="True|False" CellPadding="Pixels" DataSource='<% databindingexpression %>' DataTextField="DataSourceField" DataValueField="DataSourceField" RepeatColumns="ColumnCount" RepeatDirection="Vertical|Horizontal" RepeatLayout="Flow|Table" TextAlign="Right|Left" OnSelectedIndexChanged="OnSelectedIndexChangedMethod" /> <asp:ListItem text="label" value="value" selected="Truae|False" /> </asp:CheckBoxList>
Property | Description |
---|---|
(Base control properties) | The properties defined in Base Web Control Properties. |
AutoPostBack | True if client-side changes in the control automatically cause a postback to the server; false otherwise. The default is false. |
CellPadding | The amount of space, in pixels, between check boxes.
When programming, this property is set using Units. |
DataSource | A data-binding expression that references any object that supports the ICollection interface.
Note In ASP+ syntax, it is preferable to include the data-binding expression in single quotation marks to accommodate quoted expressions. |
DataTextField | The field or property of the object in DataSource that will be the source of data for the Text property of individual list items. |
DataValueField | The field or property of the object in DataSource that will be the source of data for the Value property of individual list items. |
Items | A collection of ListItem objects representing individual items within the list of check boxes.
This property is only used when programming. At design time, you set this property by declaring <asp:ListItem> items. |
RepeatColumns | The number of columns to use to display the checkboxes. The default is 1. |
RepeatDirection | The direction in which check boxes are displayed in the list. If Vertical, the check boxes are ordered top to bottom, like text in a newspaper. If Horizontal, check boxes are ordered left-to-right, like days in a calendar. This property has no effect if RepeatColumns is set to 1. The default is Vertical.
When programming, this property is set using the RepeatDirection enumeration. |
RepeatLayout | Indicates whether control renders in-line (Flow) or in a table (Table). The default is Table.
When programming, this property is set using the RepeatLayout enumeration. |
SelectedIndeces | A collection of index values for check boxes that are selected. If only one check box is selected, the collection contains the same information as SelectedIndex.
This property is only used when programming. At design time, you set this property by including a Selected property in any ListItem elements that should be checked. |
SelectedIndex | Ordinal index of currently selected check box in the list.
This property is only used when programming. At design time, you set this property by including a Selected property in a ListItem element. |
SelectedItem | Reference to the Value property of the currently selected check box in the list.
This property is only used when programming. At design time, you set this property by including a Selected property in a ListItem element. |
SelectedItems | (Read-only) References to a collection of selected check boxes.
This property is only used when programming. At design time, you set this property by including a Selected property in the ListItem elements to be selected. |
TextAlign | The position of the caption with respect to the check box. The default is Right.
When programming, you set this property using the TextAlign enumeration. |
Event (and paramters) | Description |
---|---|
OnSelectedIndexChanged(Object sender, EventArgs e) | Raised on the server when a check box in the list is selected. This event does not cause the Web Forms page to be posted to the server unless the AutoPostBack property is set to true.
The e events argument object has no properties. |
The following shows a sample declaration for a CheckBoxList control in an .aspx file. The list contains six items that are not mutually exclusive. When a user checks one of the boxes, the page is not immediately posted. Instead, the page is not posted until some other gesture occurs, such as a Button control click). No OnSelectedIndexChanged will be called, because no method is declared for that event.
<asp:CheckBoxList id=Check1 runat="server" RepeatLayout="flow" > <asp:ListItem>Item 1</asp:ListItem> <asp:ListItem>Item 2</asp:ListItem> <asp:ListItem>Item 3</asp:ListItem> <asp:ListItem>Item 4</asp:ListItem> <asp:ListItem>Item 5</asp:ListItem> <asp:ListItem>Item 6</asp:ListItem> </asp:CheckBoxList>
The following example shows how you can determine which check boxes in a CheckBoxList control are checked. The code loops through the control's Items collection, and for each item, tests the item's Selected property.
[C#]
protected void Button1_OnClick(object Source, EventArgs e)
{
string s;
s = "Selected items:<br>";
for (int i=0; i < Check1.Items.Count; i++)
{
if ( Check1.Items[ i ].Selected )
{
s = s + Check1.Items[i].Text;
s = s + "<br>";
}
}
Label1.Text = s;
}
See Also