CheckedListBoxControl Class

Namespace: DevExpress.XtraEditors

Assembly: DevExpress.XtraEditors.v20.1.dll

Declaration

[CheckedListBoxControl.CheckedListBoxControlCustomBindingProperties]
public class CheckedListBoxControl :
    BaseCheckedListBoxControl,
    IBehaviorPropertiesFilter

<CheckedListBoxControl.CheckedListBoxControlCustomBindingProperties>
Public Class CheckedListBoxControl
    Inherits BaseCheckedListBoxControl
    Implements IBehaviorPropertiesFilter

Remarks

By default, the CheckedListBoxControl renders its items as text strings with built-in check boxes that reflect item check states.

The Item Templates feature helps you render each listbox item as your needs dictate. Each item can display multiple text and image elements arranged in any manner, and painted using different appearance settings. There are no built-in check boxes when listbox items are rendered from a template. Instead, item check states are indicated with check marks.

An end-user can switch between item check states by double-clicking or clicking an item with the mouse (see BaseCheckedListBoxControl.CheckOnClick) or by pressing the keyboard SPACE bar.

The control's main members include:

• BaseCheckedListBoxControl.Items - Allows you to populate the control with items in unbound mode.
• BaseListBoxControl.DataSource - Use this property to populate the control with items from a data source.
• BaseListBoxControl.Templates - This property supports the item templates feature. See Templated ListBox Items to learn more.
• BaseListBoxControl.CustomizeItem - Allows you to dynamically customize templated items.
• BaseListBoxControl.CustomItemTemplate - Allows you to provide a custom template for listbox items.
• BaseListBoxControl.ValueMember - Gets or sets the field name in the bound data source whose contents are assigned to item values.
• BaseListBoxControl.DisplayMember - Gets or sets the name of the data source field that provides display text for listbox items. This property is not supported when listbox items are rendered based on Item Templates
• BaseListBoxControl.MultiColumn - Gets or sets whether listbox items can be arranged across multiple columns.
• BaseListBoxControl.SelectionMode - Gets or sets whether a single or multiple items can be selected.
• BaseListBoxControl.ContextButtons - Provides access to the collection of context buttons displayed in the control.
• BaseListBoxControl.SelectedIndexChanged - Allows you to respond to item selection.
• BaseListBoxControl.ItemHeight - Gets or sets an item's height.
• BaseCheckedListBoxControl.GetItemEnabled - Enables you to disable specific items, in bound mode.

Checked States vs. Selection vs. Hot-Tracking

Make note of the difference between an item's checked, selected and hot-tracked states. An item's checked state is visually indicated by the item's check box. Item hot-tracking (disabled by default) is highlighting an item on a mouse hover. Once the mouse cursor leaves an item's bounds, the item loses its hot-tracked state. Item selection is the capability to select (visually highlight) an item (or multiple items) and keep this highlighting after the mouse cursor leaves the control's bounds.

The following image demonstrates a CheckedListBoxControl, in which the 'Beijing' item is checked, and the two items ('Seoul' and 'Hong Kong') are selected.

When one or more items are selected, you can toggle the check states of all selected items at once by pressing the SPACE key or clicking a check box of any selected item.

An end-user can select an item using the keyboard navigation keys, by clicking an item with the mouse, and optionally by hovering (hot-tracking) the item. Multiple item selection can be enabled with the BaseListBoxControl.SelectionMode property. See this topic to know how items can be selected by end-users in multi-selection modes.

The item hot-tracking feature is initially disabled, and can be enabled with the BaseListBoxControl.HotTrackItems property. The BaseListBoxControl.HotTrackSelectMode property allows you to specify whether an item is immediately selected once it is hot-tracked, or not. Item hot-tracking is not supported in multi-selection modes.

Item Checking API

The table below shows members related to the item checking functionality.

Item Selection API

The following members support the item selection feature:

Search & Filtering

You can provide end-users with the ability to filter items in a CheckedListBoxControl. For this purpose, attach the CheckedListBoxControl to a SearchControl by using the SearchControl.Client property.

searchControl1.Client = listBoxControl1;

searchControl1.Client = listBoxControl1

When an end-user types a search request into the SearchControl, the CheckedListBoxControl automatically filters its items, and highlights the requested string in the filtered items.

Examples

The following sample code demonstrates how to create and populate a CheckedListBoxControl at runtime. The image below illustrates the control's look & feel after sample code execution.

using DevExpress.XtraEditors;
using DevExpress.XtraEditors.Controls;
// ...
CheckedListBoxItem[] items = {
                                 new CheckedListBoxItem("January", false),
                                 new CheckedListBoxItem("February", false),
                                 new CheckedListBoxItem("March", true),
                                 new CheckedListBoxItem("April", false),
                                 new CheckedListBoxItem("May", false),
                                 new CheckedListBoxItem("June", true),
                                 new CheckedListBoxItem("July", true),
                                 new CheckedListBoxItem("August", false),
                                 new CheckedListBoxItem("September", false),
                                 new CheckedListBoxItem("October", false),
                                 new CheckedListBoxItem("November", false),
                                 new CheckedListBoxItem("December", false)
                              };
private void CreateCheckedListBoxControl(CheckedListBoxItem[] items){
   CheckedListBoxControl checkedListBoxControl = new CheckedListBoxControl();
   Controls.Add(checkedListBoxControl);
   checkedListBoxControl.Left = 20;
   checkedListBoxControl.Top = 20;
   checkedListBoxControl.Width = 200;
   checkedListBoxControl.Height = 150;
   checkedListBoxControl.Items.AddRange(items);
}
// ...
CreateCheckedListBoxControl(items);

Imports DevExpress.XtraEditors
Imports DevExpress.XtraEditors.Controls
' ...
Dim items() As CheckedListBoxItem = { _
  New CheckedListBoxItem("January", False), New CheckedListBoxItem("February", False), _
  New CheckedListBoxItem("March", True), New CheckedListBoxItem("April", False), _
  New CheckedListBoxItem("May", False), New CheckedListBoxItem("June", True), _
  New CheckedListBoxItem("July", True), New CheckedListBoxItem("August", False), _
  New CheckedListBoxItem("September", False), New CheckedListBoxItem("October", False), _
  New CheckedListBoxItem("November", False), New CheckedListBoxItem("December", False)}
Private Sub CreateCheckedListBoxControl(ByVal items() As CheckedListBoxItem)
   Dim checkedListBoxControl As New CheckedListBoxControl()
   Controls.Add(checkedListBoxControl)
   checkedListBoxControl.Left = 20
   checkedListBoxControl.Top = 20
   checkedListBoxControl.Width = 200
   checkedListBoxControl.Height = 150
   checkedListBoxControl.Items.AddRange(items)
End Sub
' ...
CreateCheckedListBoxControl(items)