User Interface for .NET / User's Guide / Custom Controls / ListBox

ListBox
 Overview

Nevron User Interface overrides and extends the standard Windows Forms ListBox greatly. Together with full appearance customization features, the NListBox control also encapsulates the functionality of a CheckedListBox. Simply assign a boolean value and the listbox will have checkboxes and expose functionality of a checked listbox.

 

This topic will focus on using the custom functionality of the control such as checkboxes and custom items.

 Using The NListBoxItem Object

In order to provide image and checkbox support per item, Nevron UI uses a custom object that stores basic information such as image index, text, checked, image size and tag. Internally, any added object is converted to a NListBox item, which holds the specified object as a tag. For example if you add some object directly to the Items collection of the list box, this object will be boxed within a NListBoxItem and you will have access to it via the Tag property of the item.

 

The following example demonstrates how to add items to a NListBox:

C#
Copy Code
NListBox listBox = new NListBox();
//create a NListBoxItem and assign its properties
NListBoxItem item = new NListBoxItem();
item.Tag = myData;
item.ImageIndex = 1;
item.Checked = true;
item.Text = "Test Item";
listBox.Items.Add(item);

//add object directly to the Items collection
//in this case internally a NListBoxItem will be created and its tag will be the object itself
//for item's text is used the object.ToString() method
listBox.Items.Add(this.nTextBox1);

//note that the SelectedItem will always return a NListBoxItem
//use the SelectedItemTag instead if you want to retrieve the tag
NTextBox textBox = listBox.SelectedItemTag as NTextBox;

//or you may get the item and use its Tag value
NListBoxItem item = listBox.SelectedItem;
textBox = item.Tag as NTextBox;
Visual Basic
Copy Code
Dim listBox As NListBox = New NListBox()
'create a NListBoxItem and assign its properties
Dim item As NListBoxItem = New NListBoxItem()
item.Tag = myData
item.ImageIndex = 1
item.Checked = True
item.Text = "Test Item"
listBox.Items.Add(item)

'add object directly to the Items collection
'in this case internally a NListBoxItem will be created and its tag will be the object itself
'for item's text is used the object.ToString() method
listBox.Items.Add(Me.nTextBox1)

'note that the SelectedItem will always return a NListBoxItem
'use the SelectedItemTag instead if you want to retrieve the tag
Dim textBox As NTextBox = TryCast(listBox.SelectedItemTag, NTextBox)

'or you may get the item and use its Tag value
Dim item As NListBoxItem = listBox.SelectedItem
textBox = TryCast(item.Tag, NTextBox)
 Using The Check Boxes Functionality

 

In order to display check boxes, the CheckBoxes property must be set to true. A checkbox will appear on the left side of all items. Using the left mouse button (or programmatically, by specifying item's property Checked) you can toggle the checked state of an item. A CheckedChanged event is fired whenever an item's checked state has changed. You can track all the checked items via the CheckedItems property of the listbox. There are two check styles - standard and radio. The difference is that in standard mode multiple items can be selected while in radio only one may be checked at a time.

 

The following example demonstrates how to create and use the ckeckboxes functionality of a NListBox control:

C#
Copy Code
NListBox listBox = new NListBox();
listBox.CheckBoxes = true;
listBox.CheckStyle = CheckStyle.Radio;
listBox.ImageList = this.imageList1;
//specify the default image index for all items
listBox.DefaultImageIndex = 1;

//add some items to the listbox
NListBoxItem item;
for(int i = 0; i < 10; i++)
{
    item = new NListBoxItem(i, "Item " + i.ToString(), false);
    listBox.Items.Add(item);
}

//hook to the CheckedChanged event
listBox.CheckedChanged += new NListBoxItemCheckedEventHandler(OnListBoxCheckedChanged);

...

private void OnListBoxCheckedChanged(object sender, NListBoxItemCheckEventArgs e)
{
    MessageBox.Show(e.Item.Checked.ToString());
}
Visual Basic
Copy Code
Dim listBox As NListBox = New NListBox()
listBox.CheckBoxes = True
listBox.CheckStyle = CheckStyle.Radio
listBox.ImageList = Me.imageList1
'specify the default image index for all items
listBox.DefaultImageIndex = 1

'add some items to the listbox
Dim item As NListBoxItem
For i As Integer = 0 To 10 Step 1
    item = New NListBoxItem(i, "Item " + i.ToString(), False)
    listBox.Items.Add(item)
Next

'hook to the CheckedChanged event
AddHandler CheckedChanged, AddressOf OnListBoxCheckedChanged

...

Private Sub OnListBoxCheckedChanged(ByVal sender As Object, ByVal e As NListBoxItemCheckEventArgs) Handles listBox.CheckedChanged
    MessageBox.Show(e.Item.Checked.ToString())
End Sub