The easiest way to use a custom control is by dragging and dropping it from the Toolbox onto a page. To add our control to the Toolbox, right-click on the Toolbox and select "Add/Remove Items": 
This will bring up a dialog box. Browse for .NET Framework Components on your PC and specify the DLL for your Web Control Library project. Remember that the DLL location will be bin\Debug folder under your project folder if you built the project in the Debug configuration, and in bin\Release if you compiled under the Release configuration.
Once you have selected the DLL, you should see a component named CategorizedCheckBoxList, which can be selected:
After clicking "OK", the CategorizedCheckBoxList should now appear in your Toolbox:
To use the CategorizedCheckBoxList on an ASPX page, drag and drop the control from the Toolbox onto the page (in Design view in VS .NET). Once the control is on your page, you can set the number of columns used in the display, and the CSS properties.
The DataTable should be specified in your code behind file, to ensure the table has been populated before the CategorizedCheckBoxList tries to access it. You can specify the names for the category, text, and value columns either in the code-behind file or in the ASPX page.
Let's take a look at the Default.aspx page included in the sample project that accompanies this article. Here is the Page_Load method:
private void Page_Load(object sender, System.EventArgs e)
{
// If the page has not posted-back, or if it has but the "Show
List" checkbox is checked,
// get the data for our CategorizedCheckBoxList.
if(!IsPostBack ||
chkShowList.Checked == true)
{
// Get the data
GetMdbData();
}
else
{
// Hide the CategorizedCheckBoxList
CategorizedCheckBoxList1.Visible
= false;
// Hide the "Show List" checkbox
chkShowList.Visible
= false;
// Hide the submit button, too
btnTestValues.Visible
= false;
}
}
We're only retrieving the data for the control if the control is going to be displayed. (If we were using dynamically-instantiated CheckBoxList controls, we would need to get the data every time, regardless of the visibility of the controls.)
Next, we call the method, GetMdbData, which selects the data from an Access database:
protected void GetMdbData()
{
// Create a connetion
OleDbConnection Conn =
new OleDbConnection();
Conn.ConnectionString =
String.Concat("Provider=Microsoft.Jet.OleDb.4.0;data source=",
Server.MapPath("SampleData.mdb"));
// Build a data adapter that selects all of the columns and rows
// in a saved query called qryCarModelCarMaker, in the Access
database
OleDbDataAdapter Adp =
new OleDbDataAdapter("SELECT * FROM qryCarModelCarMaker", Conn);
// Create an instance of our Cars typed dataset
Cars TypedSampleData =
new Cars();
// Use the adapter to fill the CarTable
Adp.Fill(TypedSampleData,
"CarTable");
// Specify the data properties for our CategorizedCheckBoxList control
CategorizedCheckBoxList1.DataTable
= TypedSampleData.CarTable;
CategorizedCheckBoxList1.DataTextColumn
= "Model";
CategorizedCheckBoxList1.DataValueColumn
= "CarModelPK";
CategorizedCheckBoxList1.DataCategoryColumn
= "Make";
// Clean-up
Conn.Dispose();
Adp.Dispose();
}
Although we're using a typed DataSet, which is filled by a dynamic database query, the CategorizedCheckBoxList only cares about the DataTable, and the names of the columns that contain the required data. Other pages in the example project load both typed and un-typed data from XML files.
view screenshot
After making a few selections, clicking on the "Test Checkbox Values" button will display the values of the selected checkboxes. In our example, these are the primary key values for the car models that were picked. Let's see how to retrieve the selected values:
private void btnTestValues_Click(object sender, System.EventArgs
e)
{
// Were any checkboxes checked?
if(CategorizedCheckBoxList1.Selections.Count
> 0)
{
// Yes. Let's use a string builder to tell
the user what we find.
StringBuilder Sb
= new StringBuilder();
Sb.Append("The
following values were selected:");
// Use an HTML un-ordered list to display
the values
Sb.Append("<ul>");
// Loop through the selections
foreach(string
check in CategorizedCheckBoxList1.Selections)
{
// Add this item to our HTML list
Sb.Append("<li>");
Sb.Append(check);
Sb.Append("</li>");
}
// End the list
Sb.Append("</ul>");
// Set the text of our label
Label1.Text =
Sb.ToString();
}
else
{
// Use our label to tell the user that
nothing was picked.
Label1.Text =
"No checkboxes were selected.";
}
}
When the method executes, the values of the selected checkboxes are listed:
I'm almost finished covering the nuts and bolts of the CategorizedCheckBoxList, but we still haven't talked about how to specify default selections. Our control makes it easy to specify pre-selected options, by simply referencing the public property, Selections, which is an ArrayList:
// If the page has not posted-back, or if it has but the
"Show List" checkbox is checked,
// get the data for our CategorizedCheckBoxList.
if(!IsPostBack || chkShowList.Checked == true)
{
// Get the data
GetMdbData();
// Select all of the Audi models
CategorizedCheckBoxList1.Selections.Add("37");
CategorizedCheckBoxList1.Selections.Add("38");
CategorizedCheckBoxList1.Selections.Add("39");
CategorizedCheckBoxList1.Selections.Add("40");
CategorizedCheckBoxList1.Selections.Add("41");
}
Just remember that you need to put string values into the ArrayList, and you'll be all set.
