This control wraps the ubiquitous and multifunctional Win32 ListView common control. You will be very familiar with this from the Windows Explorer icon, list, and details views.

To choose the general appearance of the control, you can use the View property, switching between two icon views (View.LargeIcon and View.SmallIcon), the basic View.List and the View.Details report format.

To control what is actually displayed in the list, you can add or remove ListViewItem objects from the Items list. See the ListViewItem class for more information about this.

In all views, you can choose the item Activation style (see ItemActivation for more details).

You can also determine whether CheckBoxes appear next to the items. To find out which items are checked, you can refer to the CheckedIndices or CheckedItems properties. Similarly, the selected items can be retrieved through the SelectedIndices and SelectedItems properties. The item that currently has the focus can be obtained through the FocusedItem property. You can enable or disable multiple selection with the MultiSelect property.

Items can be selected automatically just by hovering over them. The HoverSelection property controls this.

By default, the selection will not be rendered (but still maintained) when the control loses the focus. You can set HideSelection to false if you want the selection to be visible all the time.

Items can be sorted in the list by calling the Sort() method. To specify how the items should be sorted (a lexicographical compare of the labels is the default), you can set a ListViewItemSorter, which is a class derived from the System.Collections.IComparer interface. You can also choose the SortOrder with the Sorting property. The default is None, but you can choose Ascending or Descending.

It is possible to allow the user to edit the label text on items by setting the LabelEdit property. You can handle the BeforeLabelEdit and AfterLabelEdit events to if you want special handling such as validation (see LabelEditEventArgs for more information). Unfortunately, this only allows you to edit the primary label of the item, not any subitem text (such as you would display in a details view). You should consider the DataGrid if you want this more complex behavior.

There are two methods related to the item bounds. You can call GetItemAt() to determine which item is to be found at a particular pixel location. GetItemRect() will return you the bounding rectangle of an item. You can refine this to a particular part of the imagery of an item (see ItemBoundsPortion).

Several features apply only to the icon views. You can set the Alignment of the icons within the container and AutoArrange them. To see how this works, play with the Explorer view "Arrange Icons By..." menu. To programmatically force a rearrangement, you can call ArrangeIcons(). You can also choose whether the LabelWrap feature is enabled, automatically wrapping the icon label text rather than cropping it.

To support the details view, there are a number of additional members. You can Add() (or Remove()) ColumnHeader items to the collection of Columns that will be displayed in the report. The first ColumnHeader corresponds to the root ListViewItem objects in the Items collection. Each subsequent column requires another ListViewItem.ListViewSubItem to be added to each item object's ListViewItem.SubItems collection to build the full row.

The columns can be either fixed in place, or you can AllowColumnReorder, which permits them to be dragged around by the user. You can also change the column HeaderStyle. While the default is ColumnHeaderStyle.Clickable (to support Sorting behavior), you can choose Nonclickable or None, to hide the header altogether.

When you select an item, normally you are only permitted to click on imagery representing the parent item (i.e., the first column in the collection). This can sometimes be awkward, so you can enable FullRowSelect to give users a larger target to stab at with the mouse.

You can also show GridLines between the rows and columns. As with all the common controls wrappers, ListView only supports pre-Windows XP features, so you have to derive your own Control to take advantage of XP supported views such as groups.

public class ListView : Control {
// Public Constructors
   public ListView();
// Public Instance Properties
   public ItemActivation Activation{set; get; }
   public ListViewAlignment Alignment{set; get; }
   public bool AllowColumnReorder{set; get; }
   public bool AutoArrange{set; get; }
   public override Color BackColor{set; get; }
// overrides Control
   public override Image BackgroundImage{set; get; }
// overrides Control
   public BorderStyle BorderStyle{set; get; }
   public bool CheckBoxes{set; get; }
   public CheckedIndexCollection CheckedIndices{get; }
   public CheckedListViewItemCollection CheckedItems{get; }
   public ColumnHeaderCollection Columns{get; }
   public ListViewItem FocusedItem{get; }
   public override Color ForeColor{set; get; }
// overrides Control
   public bool FullRowSelect{set; get; }
   public bool GridLines{set; get; }
   public ColumnHeaderStyle HeaderStyle{set; get; }
   public bool HideSelection{set; get; }
   public bool HoverSelection{set; get; }
   public ListViewItemCollection Items{get; }
   public bool LabelEdit{set; get; }
   public bool LabelWrap{set; get; }
   public ImageList LargeImageList{set; get; }
   public IComparer ListViewItemSorter{set; get; }
   public bool MultiSelect{set; get; }
   public bool Scrollable{set; get; }
   public SelectedIndexCollection SelectedIndices{get; }
   public SelectedListViewItemCollection SelectedItems{get; }
   public ImageList SmallImageList{set; get; }
   public SortOrder Sorting{set; get; }
   public ImageList StateImageList{set; get; }
   public override string Text{set; get; }
// overrides Control
   public ListViewItem TopItem{get; }
   public View View{set; get; }
// Protected Instance Properties
   protected override CreateParams CreateParams{get; }
// overrides Control
   protected override Size DefaultSize{get; }
// overrides Control
// Public Instance Methods
   public void ArrangeIcons();
   public void ArrangeIcons(ListViewAlignment value);
   public void BeginUpdate();
   public void Clear();
   public void EndUpdate();
   public void EnsureVisible(int index);
   public ListViewItem GetItemAt(int x, int y);
   public Rectangle GetItemRect(int index);
   public Rectangle GetItemRect(int index, ItemBoundsPortion portion);
   public void Sort();
   public override string ToString();  // overrides System.ComponentModel.Component
// Protected Instance Methods
   protected override void CreateHandle();  // overrides Control
   protected override void Dispose(bool disposing);  // overrides Control
   protected override bool IsInputKey(Keys keyData);  // overrides Control
   protected virtual void OnAfterLabelEdit(LabelEditEventArgs e);
   protected virtual void OnBeforeLabelEdit(LabelEditEventArgs e);
   protected virtual void OnColumnClick(ColumnClickEventArgs e);
   protected override void OnEnabledChanged(EventArgs e);  // overrides Control
   protected override void OnFontChanged(EventArgs e);  // overrides Control
   protected override void OnHandleCreated(EventArgs e);  // overrides Control
   protected override void OnHandleDestroyed(EventArgs e);  // overrides Control
   protected virtual void OnItemActivate(EventArgs e);
   protected virtual void OnItemCheck(ItemCheckEventArgs ice);
   protected virtual void OnItemDrag(ItemDragEventArgs e);
   protected virtual void OnSelectedIndexChanged(EventArgs e);
   protected override void OnSystemColorsChanged(EventArgs e);  // overrides Control
   protected void RealizeProperties();
   protected void UpdateExtendedStyles();
   protected override void WndProc(ref Message m);  // overrides Control
// Events
   public event LabelEditEventHandler AfterLabelEdit;
   public event LabelEditEventHandler BeforeLabelEdit;
   public event ColumnClickEventHandler ColumnClick;
   public event EventHandler ItemActivate;
   public event ItemCheckEventHandler ItemCheck;
   public event ItemDragEventHandler ItemDrag;
   public event PaintEventHandler Paint;
// overrides Control
   public event EventHandler SelectedIndexChanged;
}

Hierarchy

System.Object System.MarshalByRefObject System.ComponentModel.Component(System.ComponentModel.IComponen, System.IDisposable) Control(IOleContro, IOleObject, IOleInPlaceObject, IOleInPlaceActiveObject, IOleWindow, IViewObject, IViewObject2, IPersist, IPersistStreamInit, IPersistPropertyBag, IPersistStorage, IQuickActivate, System.ComponentModel.ISynchronizeInvoke, IWin32Window) ListView

Returned By

ColumnHeader.ListView, ListViewItem.ListView

Passed To

CheckedIndexCollection.CheckedIndexCollection(), CheckedListViewItemCollection.CheckedListViewItemCollection(), ColumnHeaderCollection.ColumnHeaderCollection(),ListViewItemCollection.ListViewItemCollection(), SelectedIndexCollection.SelectedIndexCollection(), SelectedListViewItemCollection.SelectedListViewItemCollection()