CheckedListBoxControl Class

Namespace: DevExpress.XtraEditors

Assembly: DevExpress.XtraEditors.v20.2.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 and 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.

Tooltips

DevExpress controls support regular and super tooltips. If the ShowToolTips option is enabled, tooltips are shown when the mouse pointer hovers the control.

Use the following properties to specify a regular tooltip's content:

• ToolTip — a regular tooltip's text. If the text is not specified, the tooltip is not displayed even if the title is specified. You can use line breaks in regular tooltips. Use the AllowHtmlTextInToolTip property to specify whether to parse HTML tags in the text. HTML tags allow you to format the text: size, style, hyperlinks, etc.
• ToolTipTitle — a regular tooltip's title. If the title is not specified, it is not displayed.

• ToolTipIconType — a regular tooltip's predefined icon. Use the controller's IconSize property to specify the image size.

  

  To display a custom image in all regular tooltips, use the controller's ImageList and ImageIndex properties.

  To display a custom image in a particular regular tooltip, handle the BeforeShow event. Use the ImageOptions event argument to assign a raster or vector image to the processed tooltip.

To assign a super tooltip to a control, use the SuperTip property. Enable the AllowHtmlText property to use HTML tags in the super tooltip.

To replace regular tooltips with super tooltips, set the ToolTipController.ToolTipType property to SuperTip. The controller automatically converts regular tooltips to super tooltips. To access this property, you can use the DefaultToolTipController component or a custom controller assigned to the ToolTipController property. See Tooltips for more information.

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)