ListView | .NET Windows Forms in a Nutshell

ListView

marshal by reference, disposable

System. Windows .Forms (system. windows .forms.dll)

class

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()