Part - 1: ListBox basics

In this series of ListBox control, we would cover basics to advanced usage of ListBox control.

Part - 1: ListBox basics - Adding Items manually to ListBox and understanding properties of ListBox

Part - 2: Data Binding in ListBox (Binding ListBox to data source)

Part - 3: Binding ListBox to XML

Part - 4: Applying style to ListBox

Part - 5: Applying style to ListBox, Continued

Part - 6: ListBox custom ControlTemplate

 

Part - 1: ListBox Basics

ListBox control in WPF falls in category of Items Controls and used to to display list of related items. Below is the basic syntax of ListBox control.

<ListBox Name="lstFruits">
    <ListBoxItem Content="Apple"></ListBoxItem>
    <ListBoxItem Content="Oranges"></ListBoxItem>
    <ListBoxItem Content="Mango"></ListBoxItem>
    <ListBoxItem Content="Grapes"></ListBoxItem>
    <ListBoxItem Content="Banana"></ListBoxItem>
</ListBox>

In above code, ListBox is a control and contains list of ListBoxItem. ListBoxItem is a specialized type of ContentControl for ListBox control. Run the application to see your ListBox in action.

Output:

To examine the properties of ListBox control, I have added Button control, handled click event of control, put the breakpoint in button click event in code, added multiple properties to watch in watch window, run the application, select “Oranges” item, breakpoint is hit and here is what I see in my properties watch window.

Tip: QuickWatch window can be used to quickly examine  value of any property at runtime. Watch window can be to add multiple properties to watch and examine their properties when they are available.

Watch window has 3 columns. Name is name of the property to watch. Value is the current value in that property. Type is the type of the value that property returns.

1. lstFruits.Items.Count = 5 = number of items in ListBox control.

2. lstFruits.SelectedIndex = 1 = As we have selected Oranges. Note: Index starts by 0.

3. lstFruits.SelectedItem: This is interesting. We would expect “Oranges” string. But if we look at the Type returned by this property, it is object and not string. As we have added ListBoxItem in ListBox, it is returning object of type ListBoxItem corresponding to “Oranges”. We can get “Oranges” text by using Content property as ListBoxItem is a ContentControl and every ContentControl has Content property. Check 4th point for the syntax.

4. ((ListBoxItem)lstFruits.SelectedItem).Content: lstFruits.SelectedItem will return object. Hence we need to type cast to “ListBoxItem” and then we can access “Content” property which would be our “Oranges” string.

5. lstFruits.SelectedValue: This is same as SelectedItem property. In this case, both are some value but we can provide different values for both, which we would cover when we DataBind to custom objects.

6. lstFruits.SelectedItems: returns collection of items that are selected in ListBox. Type column shows type returned by this property which is “SelectedItemCollection”.  Value shows says “Count = 1”, because Count is the default property when no property is specified. We can enumerate this collection to get individual selected items.

Syntax for enumeration:

foreach (ListBoxItem item in lstFruits.SelectedItems)
{
                
}

By default, “SelectionMode” property of ListBox control is set to “Single”. Below are the possible values for “SelectionMode” property.

SelectionMode:

Single (Default): Single means only one value can be selected.
Multiple: Multiple means multiple values can be selected.
Extended. Extended allows selection of multiple values in combination with CTRL or SHIFT key. Use CTRL key to select/de-select individual random items and SHIFT key to select consecutive items.

SelectedItems property is more meaningful when SelectionMode is set to Multiple or Extended. In this case we can select multiple items in ListBox control and access those selected items using SelectedItems property.

7. lstFruits.Items: returns collection of all items in ListBox control. This is useful when we want to enumerate all items or we want to perform other possible operations on collection.

I hope this would provide a good insight into some useful properties of ListBox control.

In ListBox control above we added ListBoxItem, but ListBox is not just restricted to ListBoxItem, it can contain any ContentControl as items. See below image for different types of ContentControl added.

Note: I have made 2 changes:

Replaced ListBoxItem with CheckBox

Added HorizontalContentAlignment = “Stretch”. So that all CheckBox controls occupies entire horizontal space in ListBox control.

Now run the application.

We select 3 items “Oranges”, “Grapes” and “Banana”. So SelectionMode property of ListBox control (“Single”) does not affect because we are not selecting items but we are using CheckBox to check/select them. As we are not selecting the items, hence all properties we examined above for selection would not be useful. Let examine the Watch.

Interesting, so how do I get the checked items. Simple loop through the items, type case each item to CheckBox and use Checked property.

private void Button_Click(object sender, RoutedEventArgs e)
{
    List<string> selectedItems = new List<string>();
    foreach (CheckBox chkCurrentItem in lstFruits.Items)
    {
        if (chkCurrentItem.IsChecked.Value)
        {
            selectedItems.Add(chkCurrentItem.Content.ToString());
        }
    }
}

It is also possible to add combination of items in ListBox control. See below image. Any control derived from ContentControl can be added as individual item to ListBox.

Dynamically adding items to ListBox in Code

lstFruits.Items.Add("Apple");
lstFruits.Items.Add("Oranges");
lstFruits.Items.Add("Mango");
lstFruits.Items.Add("Grapes");
lstFruits.Items.Add("Banana");

Above code will add 5 items to ListBox and each item would be implicitly converted to ListBoxItem.

lstFruits.Items.Add(new CheckBox() { Content = "Apple" });
lstFruits.Items.Add(new CheckBox() { Content = "Oranges" });
lstFruits.Items.Add(new CheckBox() { Content = "Mango" });
lstFruits.Items.Add(new CheckBox() { Content = "Grapes" });
lstFruits.Items.Add(new CheckBox() { Content = "Banana" });

Here we add 5 CheckBox control to ListBox.

I hope this introduction would help you to understand basics ListBox control and some important properties. In next article we would look at Data Binding in ListBox control.