Show / Hide Table of Contents

# Class ListView

ListView View renders a scrollable list of data where each item can be activated to perform an action.

##### Inheritance

System.Object
Responder
View
ListView

##### Implements

System.IDisposable
System.ComponentModel.ISupportInitializeNotification
System.ComponentModel.ISupportInitialize

##### Inherited Members

View.Added
View.Removed
View.Enter
View.Leave
View.MouseEnter
View.MouseLeave
View.MouseClick
View.HotKey
View.HotKeySpecifier
View.Data
View.Driver
View.Subviews
View.TabIndexes
View.TabIndex
View.TabStop
View.CanFocus
View.Id
View.IsCurrentTop
View.WantMousePositionReports
View.WantContinuousButtonPressed
View.Frame
View.LayoutStyle
View.Bounds
View.X
View.Y
View.Width
View.Height
View.SuperView
View.SetNeedsDisplay()
View.SetNeedsDisplay(Rect)
View.ChildNeedsDisplay()
View.Add(View)
View.Add(View[])
View.RemoveAll()
View.Remove(View)
View.BringSubviewToFront(View)
View.SendSubviewToBack(View)
View.SendSubviewBackwards(View)
View.BringSubviewForward(View)
View.Clear()
View.Clear(Rect)
View.ScreenToView(Int32, Int32)
View.ClipToBounds()
View.SetClip(Rect)
View.DrawFrame(Rect, Int32, Boolean)
View.DrawHotString(ustring, Attribute, Attribute)
View.DrawHotString(ustring, Boolean, ColorScheme)
View.Move(Int32, Int32)
View.HasFocus
View.OnAdded(View)
View.OnRemoved(View)
View.Focused
View.MostFocused
View.ColorScheme
View.AddRune(Int32, Int32, Rune)
View.ClearNeedsDisplay()
View.DrawContent
View.OnDrawContent(Rect)
View.SetFocus()
View.KeyPress
View.ProcessHotKey(KeyEvent)
View.ProcessColdKey(KeyEvent)
View.KeyDown
View.OnKeyDown(KeyEvent)
View.KeyUp
View.OnKeyUp(KeyEvent)
View.EnsureFocus()
View.FocusFirst()
View.FocusLast()
View.FocusPrev()
View.FocusNext()
View.LayoutStarted
View.LayoutComplete
View.Initialized
View.LayoutSubviews()
View.Text
View.TextAlignment
View.IsInitialized
View.ToString()
View.OnMouseEnter(MouseEvent)
View.OnMouseLeave(MouseEvent)
View.OnMouseEvent(MouseEvent)
View.OnMouseClick(View.MouseEventArgs)
View.Dispose(Boolean)
View.BeginInit()
View.EndInit()
View.Visible
Responder.Dispose()
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)

###### Namespace: Terminal.Gui

###### Assembly: Terminal.Gui.dll

##### Syntax

    public class ListView : View, IDisposable, ISupportInitializeNotification, ISupportInitialize

##### Remarks

The ListView displays lists of data and allows the user to scroll through the data. Items in the can be activated firing an event (with the ENTER key or a mouse double-click). If the AllowsMarking property is true, elements of the list can be marked by the user.

By default ListView uses System.Object.ToString() to render the items of any System.Collections.IList object (e.g. arrays, System.Collections.Generic.List<T>, and other collections). Alternatively, an object that implements the IListDataSource interface can be provided giving full control of what is rendered.

ListView can display any object that implements the System.Collections.IList interface. System.String values are converted into NStack.ustring values before rendering, and other values are converted into System.String by calling System.Object.ToString() and then converting to NStack.ustring .

To change the contents of the ListView, set the Source property (when providing custom rendering via IListDataSource) or call SetSource(IList) an System.Collections.IList is being used.

When AllowsMarking is set to true the rendering will prefix the rendered items with [x] or [ ] and bind the SPACE key to toggle the selection. To implement a different marking style set AllowsMarking to false and implement custom rendering.

### Constructors

#### ListView()

Initializes a new instance of ListView. Set the Source property to display something.

##### Declaration

    public ListView()

#### ListView(IList)

Initializes a new instance of ListView that will display the contents of the object implementing the System.Collections.IList interface, with relative positioning.

##### Declaration

    public ListView(IList source)

##### Parameters

Type | Name | Description
--- | --- | ---
System.Collections.IList | source | An System.Collections.IList data source, if the elements are strings or ustrings, the string is rendered, otherwise the ToString() method is invoked on the result.

#### ListView(IListDataSource)

Initializes a new instance of ListView that will display the provided data source, using relative positioning.

##### Declaration

    public ListView(IListDataSource source)

##### Parameters

Type | Name | Description
--- | --- | ---
IListDataSource | source | IListDataSource object that provides a mechanism to render the data. The number of elements on the collection should not change, if you must change, set the "Source" property to reset the internal settings of the ListView.

#### ListView(Rect, IList)

Initializes a new instance of ListView that will display the contents of the object implementing the System.Collections.IList interface with an absolute position.

##### Declaration

    public ListView(Rect rect, IList source)

##### Parameters

Type | Name | Description
--- | --- | ---
Rect | rect | Frame for the listview.
System.Collections.IList | source | An IList data source, if the elements of the IList are strings or ustrings, the string is rendered, otherwise the ToString() method is invoked on the result.

#### ListView(Rect, IListDataSource)

Initializes a new instance of ListView with the provided data source and an absolute position

##### Declaration

    public ListView(Rect rect, IListDataSource source)

##### Parameters

Type | Name | Description
--- | --- | ---
Rect | rect | Frame for the listview.
IListDataSource | source | IListDataSource object that provides a mechanism to render the data. The number of elements on the collection should not change, if you must change, set the "Source" property to reset the internal settings of the ListView.

### Properties

#### AllowsMarking

Gets or sets whether this ListView allows items to be marked.

##### Declaration

    public bool AllowsMarking { get; set; }

##### Property Value

Type | Description
--- | ---
System.Boolean | `true` if allows marking elements of the list; otherwise, `false`.

##### Remarks

If set to true, ListView will render items marked items with "[x]", and unmarked items with "[ ]" spaces. SPACE key will toggle marking.

#### AllowsMultipleSelection

If set to true allows more than one item to be selected. If false only allow one item selected.

##### Declaration

    public bool AllowsMultipleSelection { get; set; }

##### Property Value

Type | Description
--- | ---
System.Boolean |

#### SelectedItem

Gets or sets the index of the currently selected item.

##### Declaration

    public int SelectedItem { get; set; }

##### Property Value

Type | Description
--- | ---
System.Int32 | The selected item.

#### Source

Gets or sets the IListDataSource backing this ListView, enabling custom rendering.

##### Declaration

    public IListDataSource Source { get; set; }

##### Property Value

Type | Description
--- | ---
IListDataSource | The source.

##### Remarks

Use SetSource(IList) to set a new System.Collections.IList source.

#### TopItem

Gets or sets the item that is displayed at the top of the ListView.

##### Declaration

    public int TopItem { get; set; }

##### Property Value

Type | Description
--- | ---
System.Int32 | The top item.

### Methods

#### AllowsAll()

Prevents marking if it's not allowed mark and if it's not allows multiple selection.

##### Declaration

    public virtual bool AllowsAll()

##### Returns

Type | Description
--- | ---
System.Boolean |

#### MarkUnmarkRow()

Marks an unmarked row.

##### Declaration

    public virtual bool MarkUnmarkRow()

##### Returns

Type | Description
--- | ---
System.Boolean |

#### MouseEvent(MouseEvent)

Method invoked when a mouse event is generated

##### Declaration

    public override bool MouseEvent(MouseEvent me)

##### Parameters

Type | Name | Description
--- | --- | ---
MouseEvent | me |

##### Returns

Type | Description
--- | ---
System.Boolean | `true`, if the event was handled, `false` otherwise.

##### Overrides

Responder.MouseEvent(MouseEvent)

#### MoveDown()

Moves the selected item index to the next row.

##### Declaration

    public virtual bool MoveDown()

##### Returns

Type | Description
--- | ---
System.Boolean |

#### MoveEnd()

Moves the selected item index to the last row.

##### Declaration

    public virtual bool MoveEnd()

##### Returns

Type | Description
--- | ---
System.Boolean |

#### MoveHome()

Moves the selected item index to the first row.

##### Declaration

    public virtual bool MoveHome()

##### Returns

Type | Description
--- | ---
System.Boolean |

#### MovePageDown()

Moves the selected item index to the previous page.

##### Declaration

    public virtual bool MovePageDown()

##### Returns

Type | Description
--- | ---
System.Boolean |

#### MovePageUp()

Moves the selected item index to the next page.

##### Declaration

    public virtual bool MovePageUp()

##### Returns

Type | Description
--- | ---
System.Boolean |

#### MoveUp()

Moves the selected item index to the previous row.

##### Declaration

    public virtual bool MoveUp()

##### Returns

Type | Description
--- | ---
System.Boolean |

#### OnEnter(View)

Method invoked when a view gets focus.

##### Declaration

    public override bool OnEnter(View view)

##### Parameters

Type | Name | Description
--- | --- | ---
View | view | The view that is losing focus.

##### Returns

Type | Description
--- | ---
System.Boolean | `true`, if the event was handled, `false` otherwise.

##### Overrides

View.OnEnter(View)

#### OnLeave(View)

Method invoked when a view loses focus.

##### Declaration

    public override bool OnLeave(View view)

##### Parameters

Type | Name | Description
--- | --- | ---
View | view | The view that is getting focus.

##### Returns

Type | Description
--- | ---
System.Boolean | `true`, if the event was handled, `false` otherwise.

##### Overrides

View.OnLeave(View)

#### OnOpenSelectedItem()

Invokes the OnOpenSelectedItem event if it is defined.

##### Declaration

    public virtual bool OnOpenSelectedItem()

##### Returns

Type | Description
--- | ---
System.Boolean |

#### OnSelectedChanged()

Invokes the SelectedChanged event if it is defined.

##### Declaration

    public virtual bool OnSelectedChanged()

##### Returns

Type | Description
--- | ---
System.Boolean |

#### PositionCursor()

Positions the cursor in the right position based on the currently focused view in the chain.

##### Declaration

    public override void PositionCursor()

##### Overrides

View.PositionCursor()

#### ProcessKey(KeyEvent)

If the view is focused, gives the view a chance to process the keystroke.

##### Declaration

    public override bool ProcessKey(KeyEvent kb)

##### Parameters

Type | Name | Description
--- | --- | ---
KeyEvent | kb |

##### Returns

Type | Description
--- | ---
System.Boolean |

##### Overrides

View.ProcessKey(KeyEvent)

##### Remarks

Views can override this method if they are interested in processing the given keystroke. If they consume the keystroke, they must return true to stop the keystroke from being processed by other widgets or consumed by the widget engine. If they return false, the keystroke will be passed using the ProcessColdKey method to other views to process.

The View implementation does nothing but return false, so it is not necessary to call base.ProcessKey if you derive directly from View, but you should if you derive other View subclasses.

#### Redraw(Rect)

Redraws this view and its subviews; only redraws the views that have been flagged for a re-display.

##### Declaration

    public override void Redraw(Rect bounds)

##### Parameters

Type | Name | Description
--- | --- | ---
Rect | bounds | The bounds (view-relative region) to redraw.

##### Overrides

View.Redraw(Rect)

##### Remarks

Always use Bounds (view-relative) when calling Redraw(Rect), NOT Frame (superview-relative).

Views should set the color that they want to use on entry, as otherwise this will inherit the last color that was set globally on the driver.

Overrides of Redraw(Rect) must ensure they do not set `Driver.Clip` to a clip region larger than the `region` parameter.

#### SetSource(IList)

Sets the source of the ListView to an System.Collections.IList.

##### Declaration

    public void SetSource(IList source)

##### Parameters

Type | Name | Description
--- | --- | ---
System.Collections.IList | source |

##### Remarks

Use the Source property to set a new IListDataSource source and use custome rendering.

#### SetSourceAsync(IList)

Sets the source to an System.Collections.IList value asynchronously.

##### Declaration

    public Task SetSourceAsync(IList source)

##### Parameters

Type | Name | Description
--- | --- | ---
System.Collections.IList | source |

##### Returns

Type | Description
--- | ---
System.Threading.Tasks.Task | An item implementing the IList interface.

##### Remarks

Use the Source property to set a new IListDataSource source and use custome rendering.

### Events

#### OpenSelectedItem

This event is raised when the user Double Clicks on an item or presses ENTER to open the selected item.

##### Declaration

    public event Action<ListViewItemEventArgs> OpenSelectedItem

##### Event Type

Type | Description
--- | ---
System.Action<ListViewItemEventArgs> |

#### SelectedItemChanged

This event is raised when the selected item in the ListView has changed.

##### Declaration

    public event Action<ListViewItemEventArgs> SelectedItemChanged

##### Event Type

Type | Description
--- | ---
System.Action<ListViewItemEventArgs> |

### Implements

System.IDisposable
System.ComponentModel.ISupportInitializeNotification
System.ComponentModel.ISupportInitialize