ListView Tutorial: Windows Forms

ListView provides a useful view of items with icons.

This view is similar to those found in file system managers such as Windows Explorer. By providing functionality built-in, we avoid complex layout routines.

Tutorial. Let's begin by adding a ListView control to our Windows Forms. Please open the Toolbox and then double-click on the ListView entry. Next, you will want to set the important properties and event handlers.

Tip: Right-click on the ListBox in Visual Studio and select Properties to open this dialog.

Overview: In the following sections, we first explore the View property, and then investigate how to add items.

View. There are many different settings for the View property on the ListView. This property determines how the icons in the control are displayed. In the top screenshot, the setting is LargeIcon. Next we see the SmallIcon setting.

Next, we see the List setting on the View property. You can see that the icons are arranged in a vertical line on the left of the control region. Lists are good for sequential data (numbered items).

Finally, there is a Tile setting. Similar to the tile setting in Windows Explorer, this setting adds whitespace, which may help the visual appearance of the control. Be careful not to add too much.

Items. The Items property is the most important one on the ListView. It enables you to add the data entries. You can add to Items by double-clicking on the Items entry and adding Items one-by-one in the ListViewItem Collection Editor.

However: More useful, you can add elements dynamically through C# code, as in the Load event handler on the enclosing form.

CheckBoxes. We can add CheckBox controls to every item. To do this, please set the CheckBoxes property to true. The user will then be able to check or uncheck various items in the ListBox through the user interface.

Checked: You can set this to true or false to mutate the check programmatically, or read it to see if the user checked the item.

LabelEdit. Similar to Windows Explorer, the ListView allows you to change the text of items. You can do this by setting the LabelEdit property to true. The user can then select the text and wait to get an edit cursor in the ListView.

And: You can access this changed text programmatically through the Text property as well.

ImageList, icons. When you are using the ListView, you will probably want to add icons to every item. To do this, you must first create an ImageList control. Please double-click on this control in the Toolbox in Visual Studio to create one.

Next: Add images to the ImageList by right-clicking on it and selecting properties. Then open the Images Collection Editor dialog box.

SmallImageList and LargeImageList. Now that you have an ImageList control, you must reference it from the ListView. Please set the SmallImageList or LargeImageList properties to reference your ImageList instance.

Then: Whenever you want a certain image on an item in the ListView, you can simply reference an index to an image inside the ImageList.

ImageList

HoverSelection. The HoverSelection property allows you to specify that an item becomes selected whenever the user hovers the mouse over it. This selection will also trigger the SelectedIndexChanged event handler.

Note: This behavior is not standard for most types of controls, but may be useful for some programs.

Using HotTracking. Another similar property on the ListView is the HotTracking property. The term "hot tracking" refers to a visual effect that underlines the text of an item when the user hovers over it with the mouse.

Activation. The term "activation" refers to how an item is chosen by the user. In other words, double-clicking or pressing Enter are ways of activating an item. With the Activation property, you can specify how the activation event is triggered.

Tip: You can select Standard or TwoClick to get the default behavior, or OneClick to trigger activation events on every single click.

Alignment. Another useful property on the ListView control is the Alignment property. You specify Left here to have all the items aligned to the left edge of the enclosed region. The values Default and Top are equal.

Columns. The Columns property is useful only when you are using the Details view. As with other Columns properties in Windows Forms, such as those upon the DataGridView, these items serve as a template to drive the display of the data.

DataGridView Columns

HeaderStyle: The HeaderStyle property is useful when the View property is set to "Details". This affects header appearance.

Groups. The Groups property in the ListView provides a way to visually separate distinct classes of items. You can add GroupItems to the ListView and then change the items to reference specific groupings.

And: Fortunately, Windows Forms handles the display characteristics automatically.

SelectedIndexChanged. It is possible to listen for when the selection changes. This occurs when the user clicks the mouse or pressed another key such as up, down, left, right, or tab. Please add the SelectedIndexChanged event handler.

However: We create a method body. This implementation detects when the selection is empty.

Example that listens for changed selections: C#

using System;
using System.Windows.Forms;

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
	public Form1()
	{
	    InitializeComponent();
	}

	private void listView1_SelectedIndexChanged(object sender, EventArgs e)
	{
	    // Acquire SelectedItems reference.
	    var selectedItems = listView1.SelectedItems;
	    if (selectedItems.Count > 0)
	    {
		// Display text of first item selected.
		this.Text = selectedItems[0].Text;
	    }
	    else
	    {
		// Display default string.
		this.Text = "Empty";
	    }
	}
    }
}

ItemActivate. How can you listen for when an item was clicked or the return key was pressed when an item was selected? You can use the ItemActivate event handler. Right-click on the ListView and then click on the lightning bolt.

Finally: Double-click on the ItemActivate to create a stub method. This example implementation is simplistic but demonstrative.

Example that acts upon clicks: C#

using System;
using System.Windows.Forms;

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
	public Form1()
	{
	    InitializeComponent();
	}

	private void listView1_ItemActivate(object sender, EventArgs e)
	{
	    // Determine which item was clicked/activated.
	    MessageBox.Show("You clicked " + listView1.SelectedItems[0].Text);
	}
    }
}

Add. Next, we add items in code. With the ListView control, it is possible to dynamically add Items to the enclosing region instead of setting them at design time in Visual Studio through the interface.

To do this, you can add the Load event to your containing form and then invoke the listView1.Items.Add method upon your control instance. There are more elaborate overloads to this method, which are probably more useful.

Example that populates Items: C#

using System;
using System.Windows.Forms;

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
	public Form1()
	{
	    InitializeComponent();
	}

	private void Form1_Load(object sender, EventArgs e)
	{
	    // When the enclosing form loads, add three string items to the ListView.
	    // ... Use an array of strings.
	    string[] array = { "cat", "dog", "mouse" };
	    var items = listView1.Items;
	    foreach (var value in array)
	    {
		items.Add(value);
	    }
	}
    }
}

Summary. The ListView control in Windows Forms displays a file system manager-style interface. Through the many properties, you can change the display and interactive behavior of the control.

Review: By providing a rich list control without unnecessary complexity, the ListView can improve many programs.

Related Links