ListView Class

A 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 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 ListViewItem class represents an item within a 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. 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 ListBox control. Additionally, the user can activate selected items to perform a task. For example, you could use a 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 ListView can also display check boxes, using the CheckBoxes property, to allow the user to check the items that they want to perform an action on. You can use the 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 ListView can also be used to obtain information from the user, such as selecting a set of files to process.

ListView provides a large number of properties that provide flexibility in appearance and behavior. The View property allows you to change the way in which items are displayed. The LargeImageList, SmallImageList, and StateImageList properties allow you to specify the ImageList objects that contain the images displayed for items and, in the case of the StateImageList, the check boxes that are displayed when the CheckBoxes property is set to true. To determine which items are checked, you can use the CheckedItems property to access the ListView.CheckedListViewItemCollection collection. The Columns property allows access to the ListView.ColumnHeaderCollection, which stores the column headers that are displayed when the View property of the control is set to Details. Items are added and removed from the ListView through the Items property. The Items property allows you to access the 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 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 Sorting property to sort the items alphabetically. You can also completely customize the appearance of a ListView control. To do this, set the OwnerDraw property to true and handle one or more of the following events: DrawItem, DrawSubItem, DrawColumnHeader.

Many of the properties of the ListView control are used when the View property of the control is set to Details. The AllowColumnReorder property allows the user of your ListView control to reconfigure the order of columns at run time. The 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 ListView, you can use the GridLines property. The HeaderStyle property allows you to specify the type of column headers to display.

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

In addition to the many properties that are available for a ListView control, there are methods and events that your application can use to provide additional capabilities to the ListView. The BeginUpdate and EndUpdate methods allow you to improve performance when you add many items to a ListView by preventing the control from repainting every time that an item is added. If your 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 GetItemAt 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 EnsureVisible method can be called to ensure that the specific item is in the visible area of the control.

If the 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 BeforeLabelEdit and AfterLabelEdit events. To perform tasks such as opening a file or displaying a dialog box to edit an item displayed in a ListView, you can create an event handler for the ItemActivate event. If you allow the user to sort the items in a ListView when they click a column header, you can create an event handler for the ColumnClick event to perform the sorting. When the CheckBoxes property is set to true, you can determine when a change in an item's check state has occurred by handling the ItemCheck event.

You can also set a background image for the ListView with the BackgroundImage property. Your application must have the STAThreadAttribute on its Main method to correctly display the background image for the ListView control. In addition, if a 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.

Note
Setting the Cursor property for a ListView control has no affect on the appearance of the cursor in .NET Framework versions 1.1 and earlier.

Windows XP and Windows Server 2003 provide three features that enhance the 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 View property to View.Tile to enable this behavior.

The grouping feature lets you visually group items into related categories. Use the Groups property to add ListViewGroup objects to the ListView control when you want to enable this feature. To temporarily disable the feature, set the 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 ListViewInsertionMark object retrieved through the 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 ListView members and the views they are valid in.

The following code example creates a ListView control with three ListViewItem objects specified and three ListViewItem.ListViewSubItem objects specified for each item. The example also creates ColumnHeader objects to display the subitems in details view. Two ImageList objects are also created in the code example to provide images for the ListViewItem objects. These ImageList objects are added to the LargeImageList and SmallImageList properties. The example uses the following properties in creating the ListView control:

• View

• LabelEdit

• AllowColumnReorder

• CheckBoxes

• FullRowSelect

• GridLines

• Sorting

This example requires that you have added the code to a Form and call the method created in the example from the constructor or another method on the form. The example also requires that images named MySmallImage1, MySmallImage2, MyLargeImage1, and MyLargeImage2 are located in the root directory of drive C.

		private void CreateMyListView()
		{
			// Create a new ListView control.
			ListView listView1 = new ListView();
			listView1.Bounds = new Rectangle(new Point(10,10), new Size(300,200));

			// Set the view to show details.
			listView1.View = View.Details;
			// Allow the user to edit item text.
			listView1.LabelEdit = true;
			// Allow the user to rearrange columns.
			listView1.AllowColumnReorder = true;
			// Display check boxes.
			listView1.CheckBoxes = true;
			// Select the item and subitems when selection is made.
			listView1.FullRowSelect = true;
			// Display grid lines.
			listView1.GridLines = true;
			// Sort the items in the list in ascending order.
			listView1.Sorting = SortOrder.Ascending;
            			
			// Create three items and three sets of subitems for each item.
			ListViewItem item1 = new ListViewItem("item1",0);
			// Place a check mark next to the item.
			item1.Checked = true;
			item1.SubItems.Add("1");
			item1.SubItems.Add("2");
			item1.SubItems.Add("3");
			ListViewItem item2 = new ListViewItem("item2",1);
			item2.SubItems.Add("4");
			item2.SubItems.Add("5");
			item2.SubItems.Add("6");
			ListViewItem item3 = new ListViewItem("item3",0);
			// Place a check mark next to the item.
			item3.Checked = true;
			item3.SubItems.Add("7");
			item3.SubItems.Add("8");
			item3.SubItems.Add("9");

			// Create columns for the items and subitems.
			// Width of -2 indicates auto-size.
			listView1.Columns.Add("Item Column", -2, HorizontalAlignment.Left);
			listView1.Columns.Add("Column 2", -2, HorizontalAlignment.Left);
			listView1.Columns.Add("Column 3", -2, HorizontalAlignment.Left);
			listView1.Columns.Add("Column 4", -2, HorizontalAlignment.Center);

			//Add the items to the ListView.
            		listView1.Items.AddRange(new ListViewItem[]{item1,item2,item3});

			// Create two ImageList objects.
			ImageList imageListSmall = new ImageList();
			ImageList imageListLarge = new ImageList();

			// Initialize the ImageList objects with bitmaps.
			imageListSmall.Images.Add(Bitmap.FromFile("C:\\MySmallImage1.bmp"));
			imageListSmall.Images.Add(Bitmap.FromFile("C:\\MySmallImage2.bmp"));
			imageListLarge.Images.Add(Bitmap.FromFile("C:\\MyLargeImage1.bmp"));
			imageListLarge.Images.Add(Bitmap.FromFile("C:\\MyLargeImage2.bmp"));

			//Assign the ImageList objects to the ListView.
			listView1.LargeImageList = imageListLarge;
			listView1.SmallImageList = imageListSmall;

			// Add the ListView to the control collection.
			this.Controls.Add(listView1);
		}

.NET Framework

.NET Framework Client Profile

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

Reference