ListView

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 a lot of functionality built-in, we avoid complex layout routines.

ListView with LargeIcon

Tutorial

Steps

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 on the ListView instance you created. Right-click on it 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 in this article, the setting is LargeIcon. Next we see the SmallIcon setting.

ListView with SmallIcon

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.

ListView with List

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.

ListView with Tile

Items

The Items property is the most important one on the ListView, as it enables you to add the data entries to the ListBox. You can add to the Items property by double-clicking on the Items entry and adding Items one-by-one in the ListViewItem Collection Editor. More useful, you can add elements dynamically through C# code, as in the Load event handler on the enclosing form.

Note:Please see the section below on this topic for an example.

CheckBoxes

Another option with the ListBox is the ability to add CheckBox controls to every item in the control. 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. Every ListViewItem has a public Checked property.

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

ListView with CheckBoxes

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. You can access this changed text programmatically through the Text property as well.

ListView with LabelEdit

ImageList for 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, and then opening 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 that is stored inside the ImageList.

ImageList

HoverSelection

The HoverSelection property on the ListView 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. 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. Older Windows operating systems such as Windows 95 used this visual effect much more than newer ones such as Windows Vista or Windows 7.

Activation

With the ListView, 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. You can select Standard or TwoClick to get the default behavior, or OneClick to trigger activation events on every single click.

Alignment

Property

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 of the ListView. As with other Columns properties in the Windows Forms platform, such as those upon the DataGridView, these items serve as a template to drive the display of the data.

DataGridView Columns, Edit Columns Dialog

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.

HeaderStyle

The HeaderStyle property is only for when you have the View property set to the value "Details". The options in the HeaderStyle property give you some control over the exact functionality of the header when clicked upon.

Tip:Please experiment on your own to get the ideal effect here.

SelectedIndexChanged

Lightning bolt

It is possible to listen for when the selection in the ListView control 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 and then add a method implementation. This implementation detects when the selection is empty.

Example that listens for changed selections: C#

using System;
using System.Windows.Forms;

namespace WindowsFormsApplication19
{
    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

Question and answer

How can you listen for when an item in the ListView was clicked or the return key was pressed when an item was selected? You can use the ItemActivate event handler. Please add this event by right-clicking on the ListView and then clicking 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 WindowsFormsApplication19
{
    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

Plus

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 WindowsFormsApplication19
{
    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 C# programming language

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.


C#: Windows