CheckBoxList Web Server Control Declarative Syntax
Creates a multiselection check box group. This control supports binding to a data source.
<asp:CheckBoxList
AccessKey="string"
AppendDataBoundItems="True|False"
AutoPostBack="True|False"
BackColor="color name|#dddddd"
BorderColor="color name|#dddddd"
BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
Inset|Outset"
BorderWidth="size"
CausesValidation="True|False"
CellPadding="integer"
CellSpacing="integer"
CssClass="string"
DataMember="string"
DataSource="string"
DataSourceID="string"
DataTextField="string"
DataTextFormatString="string"
DataValueField="string"
Enabled="True|False"
EnableTheming="True|False"
EnableViewState="True|False"
Font-Bold="True|False"
Font-Italic="True|False"
Font-Names="string"
Font-Overline="True|False"
Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|
Large|X-Large|XX-Large"
Font-Strikeout="True|False"
Font-Underline="True|False"
ForeColor="color name|#dddddd"
Height="size"
ID="string"
OnDataBinding="DataBinding event handler"
OnDataBound="DataBound event handler"
OnDisposed="Disposed event handler"
OnInit="Init event handler"
OnLoad="Load event handler"
OnPreRender="PreRender event handler"
OnSelectedIndexChanged="SelectedIndexChanged event handler"
OnTextChanged="TextChanged event handler"
OnUnload="Unload event handler"
RepeatColumns="integer"
RepeatDirection="Horizontal|Vertical"
RepeatLayout="Table|Flow"
runat="server"
SelectedIndex="integer"
SelectedValue="string"
SkinID="string"
Style="string"
TabIndex="integer"
TextAlign="Left|Right"
ToolTip="string"
ValidationGroup="string"
Visible="True|False"
Width="size"
>
<asp:ListItem
Enabled="True|False"
Selected="True|False"
Text="string"
Value="string"
/>
</asp:CheckBoxList>
Remarks
The CheckBoxList control creates a multiselection check box group that can be dynamically generated using data binding. To specify items that you want to appear in the CheckBoxList control, place a ListItem element for each entry between the opening and closing tags of the CheckBoxList control.
.gif) Note |
|---|
You can also use multiple CheckBox controls. The CheckBoxList control is easier for creating a set of check boxes using data binding, while the individual CheckBox control gives you greater control over layout. |
The CheckBoxList control also supports data binding. To bind the control to a data source, first create a data source, such as one of the DataSourceControl objects, that contains the items to display in the control. Next, use the DataBind method to bind the data source to the CheckBoxList control. Use the DataTextField and DataValueField properties to specify which field in the data source to bind to the Text and Value properties of each list item in the control, respectively. The CheckBoxList control will now display the information from the data source.
To determine the selected items in the CheckBoxList control, iterate through the Items collection and test the Selected property of each item in the collection.
You can specify the way the list is displayed by using the RepeatLayout and RepeatDirection properties. If RepeatLayout is set to RepeatLayout.Table (the default setting), the list is rendered within a table. If it is set to RepeatLayout.Flow, the list is rendered without any table structure. By default, RepeatDirection is set to RepeatDirection.Vertical. Setting this property to RepeatDirection.Horizontal renders the list horizontally.
.gif) Caution |
|---|
Text is not HTML encoded before it is displayed in the CheckBoxList control. This makes it possible to embed script within HTML tags in the text. If the values for the control come from user input, be sure to validate the values to help prevent security vulnerabilities. |
For detailed information on the CheckBoxList Web server control's properties and events, see the CheckBoxList class documentation.
Example
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 back to the server (the page is not posted until some other event occurs, such as a Button click). No OnSelectedIndexChanged event handler is called because no method is declared for that event.
<asp:CheckBoxList id="Check1"
RepeatLayout="flow"
runat="server">
<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>
<asp:CheckBoxList id="Check1"
RepeatLayout="flow"
runat="server">
<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 the selected check boxes in a CheckBoxList control. The code iterates through the control's Items collection and tests each item's Selected property. The selected items are then displayed in the Label control.
Sub Button1_OnClick(ByVal sender As Object, ByVal e As EventArgs)
Dim s As String
Dim i As Integer
s = "Selected items:<br />"
For i = 0 To Check1.Items.Count - 1
If Check1.Items(i).Selected Then
s = s & Check1.Items(i).Text & "<br />"
End If
Next i
Label1.Text = s
End Sub
void Button1_OnClick(Object sender, 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 + "<br />";
}
}
Label1.Text = s;
}