System.Windows.Forms.ListView Class

Represents a Windows list view control, which displays a collection of items that can be displayed using one of four different views.

See Also: ListView Members


[System.ComponentModel.Designer("System.Windows.Forms.Design.ListViewDesigner, System.Design, Version=, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.ComponentModel.Design.IDesigner")]
public class ListView : Control


A System.Windows.Forms.ListView control allows you to display a list of items with item text and, optionally, an icon to identify the type of item. For example, the Windows Explorer list of files is similar in appearance to a System.Windows.Forms.ListView control. It displays a list of the files and folders currently selected in the tree. Each file and folder displays an icon associated with it to help identify the type of file or folder. The System.Windows.Forms.ListViewItem class represents an item within a System.Windows.Forms.ListView control. The items that are displayed in the list can be shown in one of five different views. Items can be displayed as large icons, as small icons, or as small icons in a vertical list. Items can also have subitems which contain information that is related to the parent item. The details view allows you to display the item and its subitems in a grid with column headers that identify the information being displayed in a subitem. The tile view, which has limited availability as described below, allows you to display the item and its subitems as a tile that contains a large icon next to the textual information. System.Windows.Forms.ListView supports single or multiple selection. The multiple selection feature lets the user select from a list of items in a way similar to a System.Windows.Forms.ListBox control. Additionally, the user can activate selected items to perform a task. For example, you could use a System.Windows.Forms.ListView control to display a list of files that the application can then open and utilize. The user can select the files to open and then double-click them to activate the items and open the files in the application. The System.Windows.Forms.ListView can also display check boxes, using the ListView.CheckBoxes property, to allow the user to check the items that they want to perform an action on. You can use the System.Windows.Forms.ListView control in a variety of ways. The control can be used to display information from an application, a database, or a text file. The System.Windows.Forms.ListView can also be used to obtain information from the user, such as selecting a set of files to process.

System.Windows.Forms.ListView provides a large number of properties that provide flexibility in appearance and behavior. The ListView.View property allows you to change the way in which items are displayed. The ListView.LargeImageList, ListView.SmallImageList, and ListView.StateImageList properties allow you to specify the System.Windows.Forms.ImageList objects that contain the images displayed for items and, in the case of the ListView.StateImageList, the check boxes that are displayed when the ListView.CheckBoxes property is set to true. To determine which items are checked, you can use the ListView.CheckedItems property to access the System.Windows.Forms.ListView.CheckedListViewItemCollection collection. The ListView.Columns property allows access to the System.Windows.Forms.ListView.ColumnHeaderCollection, which stores the column headers that are displayed when the ListView.View property of the control is set to View.Details. Items are added and removed from the System.Windows.Forms.ListView through the ListView.Items property. The ListView.Items property allows you to access the System.Windows.Forms.ListView.ListViewItemCollection of the control, which provides methods for manipulating the items in the control. If you want to allow the user to edit the text of an item, you can use the ListView.LabelEdit property. When your control contains a large number of items, it is often easier for the user to see them in a sorted list. You can use the ListView.Sorting property to sort the items alphabetically. You can also completely customize the appearance of a System.Windows.Forms.ListView control. To do this, set the ListView.OwnerDraw property to true and handle one or more of the following events: ListView.DrawItem, ListView.DrawSubItem, ListView.DrawColumnHeader.

Many of the properties of the System.Windows.Forms.ListView control are used when the ListView.View property of the control is set to View.Details. The ListView.AllowColumnReorder property allows the user of your System.Windows.Forms.ListView control to reconfigure the order of columns at run time. The ListView.FullRowSelect property allows an item and its subitems to be selected instead of just the item. To display gridlines in the details view to identify the boundaries of items and subitems in the System.Windows.Forms.ListView, you can use the ListView.GridLines property. The ListView.HeaderStyle property allows you to specify the type of column headers to display.

A System.Windows.Forms.ListView control can operate in virtual mode, where System.Windows.Forms.ListViewItem objects are generated dynamically instead of being stored in the ListView.Items collection. This can be useful for dealing with very large lists or lists whose contents frequently change. To enable Virtual mode, set the ListView.VirtualMode property to true and handle the ListView.RetrieveVirtualItem, ListView.CacheVirtualItems, and ListView.SearchForVirtualItem events.

In addition to the many properties that are available for a System.Windows.Forms.ListView control, there are methods and events that your application can use to provide additional capabilities to the System.Windows.Forms.ListView. The ListView.BeginUpdate and ListView.EndUpdate methods allow you to improve performance when you add many items to a System.Windows.Forms.ListView by preventing the control from repainting every time that an item is added. If your System.Windows.Forms.ListView control is displaying items and subitems, you may want to provide functionality when the user right-clicks a subitem. To determine the item whose subitem is being clicked, you can use the ListView.GetItemAt(int, int) method. When performing validation of the items after the user has edited them, you may want to display a specific item to the user to change. The ListView.EnsureVisible(int) method can be called to ensure that the specific item is in the visible area of the control.

If the ListView.LabelEdit property set to true, you can perform tasks such as validating the text being edited before and after the text changed by creating an event handler for the ListView.BeforeLabelEdit and ListView.AfterLabelEdit events. To perform tasks such as opening a file or displaying a dialog box to edit an item displayed in a System.Windows.Forms.ListView, you can create an event handler for the ListView.ItemActivate event. If you allow the user to sort the items in a System.Windows.Forms.ListView when they click a column header, you can create an event handler for the ListView.ColumnClick event to perform the sorting. When the ListView.CheckBoxes property is set to true, you can determine when a change in an item's check state has occurred by handling the ListView.ItemCheck event.

You can also set a background image for the System.Windows.Forms.ListView with the Control.BackgroundImage property. Your application must have the STAThreadAttribute on its Main method to correctly display the background image for the System.Windows.Forms.ListView control. In addition, if a System.Windows.Forms.ListView control with a background image is hosted in Internet Explorer, specify comctl32.dll version 6.0 as a dependent assembly in the application manifest file to ensure the background image is property displayed.


Setting the Control.Cursor property for a System.Windows.Forms.ListView control has no affect on the appearance of the cursor in dnprdnshort versions 1.1 and earlier.

Windows XP and Windows Server 2003 provide three features that enhance the System.Windows.Forms.ListView control when your application calls the Application.EnableVisualStyles method: tile view, grouping, and the insertion mark.

The tile view lets you balance graphical and textual information by displaying item and subitem text next to large icons. Set the ListView.View property to View.Tile to enable this behavior.

The grouping feature lets you visually group items into related categories. Use the ListView.Groups property to add System.Windows.Forms.ListViewGroup objects to the System.Windows.Forms.ListView control when you want to enable this feature. To temporarily disable the feature, set the ListView.ShowGroups property to false.

The insertion mark feature lets you provide drag-and-drop item repositioning with visual feedback to indicate drop locations. Use the System.Windows.Forms.ListViewInsertionMark object retrieved through the ListView.InsertionMark property to display the insertion mark.

These features are available only under Windows XP and Windows Server 2003. On earlier operating systems, the code that relate to these features has no effect, the tile view appears as the large icon view, and the insertion mark and groups do not display. In some cases, you might want to include code that determines whether these features are available, and provide alternate functionality when they are unavailable. These features are provided by the same library that provides the operating system themes feature. To check for the availability of this library, call the FeatureSupport.IsPresent(object) method overload and pass in the OSFeature.Themes value.

The following table shows some of the System.Windows.Forms.ListView members and the views they are valid in.

ListView.Alignment property

View.SmallIcon or View.LargeIcon

ListView.AutoArrange property

View.SmallIcon or View.LargeIcon

ListView.AutoResizeColumn(int, ColumnHeaderAutoResizeStyle) method


ListView.Columns property

View.Details or View.Tile

ListView.DrawSubItem event


erload:System.Windows.Forms.ListView.FindItemWithText method

View.Details, View.List, or View.Tile

erload:System.Windows.Forms.ListView.FindNearestItem method

View.SmallIcon or View.LargeIcon

ListView.GetItemAt(int, int) method

View.Details or View.Tile

ListView.Groups property

All views except View.List

ListView.HeaderStyle property


ListView.InsertionMark property

View.LargeIcon, View.SmallIcon, or View.Tile


Namespace: System.Windows.Forms
Assembly: System.Windows.Forms (in System.Windows.Forms.dll)
Assembly Versions: 1.0.5000.0,