Class ListView

ListView View renders a scrollable list of data where each item can be activated to perform an action.
Inheritance
object
Responder
View
ListView
Implements
Inherited Members
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 ToString() to render the items of any IList object (e.g. arrays, List<T>, and other collections). Alternatively, an object that implements IListDataSource can be provided giving full control of what is rendered.

ListView can display any object that implements the IList interface. string values are converted into NStack.ustring values before rendering, and other values are converted into string by calling 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 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.

Searching the ListView with the keyboard is supported. Users type the first characters of an item, and the first item that starts with what the user types will be selected.

Constructors

| Edit this page View Source

ListView()

Initializes a new instance of ListView. Set the Source property to display something.
Declaration
public ListView()
| Edit this page View Source

ListView(IList)

Initializes a new instance of ListView that will display the contents of the object implementing the IList interface, with relative positioning.
Declaration
public ListView(IList source)
Parameters
Type Name Description
IList source An IList data source, if the elements are strings or ustrings, the string is rendered, otherwise the ToString() method is invoked on the result.
| Edit this page View Source

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.
| Edit this page View Source

ListView(Rect, IList)

Initializes a new instance of ListView that will display the contents of the object implementing the IList interface with an absolute position.
Declaration
public ListView(Rect rect, IList source)
Parameters
Type Name Description
Rect rect Frame for the listview.
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.
| Edit this page View Source

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

| Edit this page View Source

AllowsMarking

Gets or sets whether this ListView allows items to be marked.
Declaration
public bool AllowsMarking { get; set; }
Property Value
Type Description
bool Set to true to allow marking elements of the list.
Remarks
If set to true, ListView will render items marked items with "[x]", and unmarked items with "[ ]" spaces. SPACE key will toggle marking. The default is false.
| Edit this page View Source

AllowsMultipleSelection

If set to true more than one item can be selected. If false selecting an item will cause all others to be un-selected. The default is false.
Declaration
public bool AllowsMultipleSelection { get; set; }
Property Value
Type Description
bool
| Edit this page View Source

KeystrokeNavigator

Gets the CollectionNavigator that searches the Source collection as the user types.
Declaration
public CollectionNavigator KeystrokeNavigator { get; }
Property Value
Type Description
CollectionNavigator
| Edit this page View Source

LeftItem

Gets or sets the leftmost column that is currently visible (when scrolling horizontally).
Declaration
public int LeftItem { get; set; }
Property Value
Type Description
int The left position.
| Edit this page View Source

Maxlength

Gets the widest item in the list.
Declaration
public int Maxlength { get; }
Property Value
Type Description
int
| Edit this page View Source

SelectedItem

Gets or sets the index of the currently selected item.
Declaration
public int SelectedItem { get; set; }
Property Value
Type Description
int The selected item.
| Edit this page View Source

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 IList source.
| Edit this page View 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
int The top item.

Methods

| Edit this page View Source

AllowsAll()

If AllowsMarking and AllowsMultipleSelection are both true, unmarks all marked items other than the currently selected.
Declaration
public virtual bool AllowsAll()
Returns
Type Description
bool true if unmarking was successful.
| Edit this page View Source

EnsureSelectedItemVisible()

Ensures the selected item is always visible on the screen.
Declaration
public void EnsureSelectedItemVisible()
| Edit this page View Source

MarkUnmarkRow()

Marks the SelectedItem if it is not already marked.
Declaration
public virtual bool MarkUnmarkRow()
Returns
Type Description
bool true if the SelectedItem was marked.
| Edit this page View Source

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
bool true, if the event was handled, false otherwise.
Overrides
| Edit this page View Source

MoveDown()

Changes the SelectedItem to the next item in the list, scrolling the list if needed.
Declaration
public virtual bool MoveDown()
Returns
Type Description
bool
| Edit this page View Source

MoveEnd()

Changes the SelectedItem to last item in the list, scrolling the list if needed.
Declaration
public virtual bool MoveEnd()
Returns
Type Description
bool
| Edit this page View Source

MoveHome()

Changes the SelectedItem to the first item in the list, scrolling the list if needed.
Declaration
public virtual bool MoveHome()
Returns
Type Description
bool
| Edit this page View Source

MovePageDown()

Changes the SelectedItem to the item just below the bottom of the visible list, scrolling if needed.
Declaration
public virtual bool MovePageDown()
Returns
Type Description
bool
| Edit this page View Source

MovePageUp()

Changes the SelectedItem to the item at the top of the visible list.
Declaration
public virtual bool MovePageUp()
Returns
Type Description
bool
| Edit this page View Source

MoveUp()

Changes the SelectedItem to the previous item in the list, scrolling the list if needed.
Declaration
public virtual bool MoveUp()
Returns
Type Description
bool
| Edit this page View Source

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
bool true, if the event was handled, false otherwise.
Overrides
| Edit this page View Source

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
bool true, if the event was handled, false otherwise.
Overrides
| Edit this page View Source

OnOpenSelectedItem()

Invokes the OpenSelectedItem event if it is defined.
Declaration
public virtual bool OnOpenSelectedItem()
Returns
Type Description
bool
| Edit this page View Source

OnRowRender(ListViewRowEventArgs)

Virtual method that will invoke the RowRender.
Declaration
public virtual void OnRowRender(ListViewRowEventArgs rowEventArgs)
Parameters
Type Name Description
ListViewRowEventArgs rowEventArgs
| Edit this page View Source

OnSelectedChanged()

Invokes the SelectedItemChanged event if it is defined.
Declaration
public virtual bool OnSelectedChanged()
Returns
Type Description
bool
| Edit this page View Source

PositionCursor()

Positions the cursor in the right position based on the currently focused view in the chain.
Declaration
public override void PositionCursor()
Overrides
| Edit this page View Source

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
bool
Overrides
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.

| Edit this page View Source

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
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 parameter, as this will cause the driver to clip the entire region.

| Edit this page View Source

ScrollDown(int)

Scrolls the view down by items items.
Declaration
public virtual bool ScrollDown(int items)
Parameters
Type Name Description
int items Number of items to scroll down.
Returns
Type Description
bool
| Edit this page View Source

ScrollLeft(int)

Scrolls the view left.
Declaration
public virtual bool ScrollLeft(int cols)
Parameters
Type Name Description
int cols Number of columns to scroll left.
Returns
Type Description
bool
| Edit this page View Source

ScrollRight(int)

Scrolls the view right.
Declaration
public virtual bool ScrollRight(int cols)
Parameters
Type Name Description
int cols Number of columns to scroll right.
Returns
Type Description
bool
| Edit this page View Source

ScrollUp(int)

Scrolls the view up by items items.
Declaration
public virtual bool ScrollUp(int items)
Parameters
Type Name Description
int items Number of items to scroll up.
Returns
Type Description
bool
| Edit this page View Source

SetSource(IList)

Sets the source of the ListView to an IList.
Declaration
public void SetSource(IList source)
Parameters
Type Name Description
IList source
Remarks
Use the Source property to set a new IListDataSource source and use custome rendering.
| Edit this page View Source

SetSourceAsync(IList)

Sets the source to an IList value asynchronously.
Declaration
public Task SetSourceAsync(IList source)
Parameters
Type Name Description
IList source
Returns
Type Description
Task An item implementing the IList interface.
Remarks
Use the Source property to set a new IListDataSource source and use custom rendering.

Events

| Edit this page View Source

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
Action<ListViewItemEventArgs>
| Edit this page View Source

RowRender

This event is invoked when this ListView is being drawn before rendering.
Declaration
public event Action<ListViewRowEventArgs> RowRender
Event Type
Type Description
Action<ListViewRowEventArgs>
| Edit this page View Source

SelectedItemChanged

This event is raised when the selected item in the ListView has changed.
Declaration
public event Action<ListViewItemEventArgs> SelectedItemChanged
Event Type
Type Description
Action<ListViewItemEventArgs>

Implements