Everything you need to know about ListBoxAdv control for WinForms

Categories: DotNetBar for Windows Forms

ListBoxAdv control included with DotNetBar for WinForms is an replacement for the system ListBox and CheckedListBox controls.

When you add ListBoxAdv control to your form you have 3 easy ways to add content to it.

You can use ListBoxAdv Tasks menu to add ListBoxItem objects to it as shown in image below:

Adding items like this allows you to assign Image or Symbol to the item or use the text-markup in Text property. Simply select each item in list-box and set its properties in VS.NET Property window.

You can add plain text as items by going to VS.NET Property window, and clicking the button next to the Items property:

This will open the dialog where you simply enter items as one item per line of text…

Third way to add items to the ListBoxAdv is through data-binding. Simply set DataSource property to your data, which can be pretty much anything, an array, an list or data-table. Then set the DisplayMember property to the name of the property on data object which holds the value that you want displayed in list-box. Optionally you can also set the ValueMember property to the name of the property on data object which holds the object ID. When ValueMember is set the SelectedValue property on ListBoxAdv will return the property value of selected object as specified by ValueMember.

To bind the check-box state for each item set CheckStateMember property to the property name on bound object which holds the check-state value. The value can be bool type or any of the number types and control will automatically convert that to CheckState. You can also handle the CheckStateConvert event to handle conversion of the bound value to CheckState yourself.

Selection

SelectionMode property controls the selection of the items inside of the list-box. By default SelectionMode is set to One which means only single item can be selected. For multiple item selection you can set SelectionMode to either MultiSimple or MultiExtended. To disable selection set SelectionMode to None.

As selection changes the SelectedIndexChanged event is fired. For single item selection mode you use SelectedIndex, SelectedItem and SelectedValue properties to get currently selected item. For multi-selection mode use SelectedItems collection. SelectedItems collection is a collection of currently selected items and it always contains the instances of ListBoxItem. If you are using data-binding then for each bound object one ListBoxItem is created. ListBoxItem.Tag property in that case will hold reference to the data-object represented by that item.

Do not modify the SelectedItems collection using code since that will not be reflected in list-box. Instead use ListBoxAdv.SetSelected method or you can use ListBoxItem.SetIsSelected method.

Check-Boxes

To display check-boxes for each item simply set CheckBoxesVisible property to true. This will cause the check-box to appear next to each item:

To get list of checked items use CheckedItems property which will return collection of checked items. As is the case with SelectedItems collection, this collection always holds the instances of ListBoxItem and should never be modified directly. Instead to set checked state of an item use ListBoxAdv.SetItemCheckState method. As each item check-state changes the ItemCheck event is fired.

Hit-Testing

To get the item in the list-box at specific location use method HitTest which accepts client coordinates for the control and returns either item at that location or null/nothing if there is no item at given coordinates.

DevComponents Knowledge Base