Class ListBox

A scrollable list control.

Inheritance
object
ControlBase
CompositeControl
ListBox
FileDirectoryListbox
Implements
Inherited Members
Namespace: SadConsole.UI.Controls
Assembly: SadConsole.dll
Syntax
[DataContract]
public class ListBox : CompositeControl, IContainer, IList<ControlBase>, ICollection<ControlBase>, IEnumerable<ControlBase>, IEnumerable

Constructors

ListBox(int, int)

Creates a new instance of the listbox control with the default theme for the items.

Declaration
public ListBox(int width, int height)
Parameters
Type Name Description
int width

The width of the listbox.
int height

The height of the listbox.

ListBox(int, int, ListBoxItemTheme)

Creates a new instance of the listbox control with the specified item theme.

Declaration
public ListBox(int width, int height, ListBoxItemTheme itemTheme)
Parameters
Type Name Description
int width

The width of the listbox.
int height

The height of the listbox.
ListBoxItemTheme itemTheme

The theme to use with rendering the listbox items.

Fields

_reconfigureScrollBar

Internal flag to indicate the scroll bar needs to be reconfigured.

Declaration
protected bool _reconfigureScrollBar
Field Value
Type Description
bool

Properties

BorderLineStyle

The line style for the border when DrawBorder is true.

Declaration
[DataMember]
public int[] BorderLineStyle { get; set; }
Property Value
Type Description
int[]

BorderTheme

The drawing theme for the border when DrawBorder is true.

Declaration
public ThemeStates BorderTheme { get; protected set; }
Property Value
Type Description
ThemeStates

CompareByReference

When the SelectedItem changes, and this property is true, objects will be compared by reference. If false, they will be compared by value.

Declaration
[DataMember]
public bool CompareByReference { get; set; }
Property Value
Type Description
bool

DrawBorder

If false the border will not be drawn.

Declaration
[DataMember]
public bool DrawBorder { get; set; }
Property Value
Type Description
bool

IsScrollBarVisible

Internal use only; used in rendering.

Declaration
public bool IsScrollBarVisible { get; set; }
Property Value
Type Description
bool

ItemIndexMouseOver

Used in rendering.

Declaration
public int ItemIndexMouseOver { get; }
Property Value
Type Description
int

ItemTheme

The appearance of the items displayed by the listbox control.

Declaration
[DataMember]
public ListBoxItemTheme ItemTheme { get; set; }
Property Value
Type Description
ListBoxItemTheme

Items

The items in the listbox.

Declaration
[DataMember]
public ObservableCollection<object> Items { get; }
Property Value
Type Description
ObservableCollection<object>

ItemsArea

The area on the control where items are drawn.

Declaration
public Rectangle ItemsArea { get; set; }
Property Value
Type Description
Rectangle

ScrollBar

The scroll bar control used with this list box.

Declaration
[DataMember(Name = "ScrollBar")]
public ScrollBar ScrollBar { get; protected set; }
Property Value
Type Description
ScrollBar

SelectedIndex

Gets or sets the index of the selected item.

Declaration
public int SelectedIndex { get; set; }
Property Value
Type Description
int

SelectedItem

Gets or sets the selected item.

Declaration
public object? SelectedItem { get; set; }
Property Value
Type Description
object

SingleClickItemExecute

When set to true, the SelectedItemExecuted event will fire when an item is single-clicked instead of double-clicked.

Declaration
[DataMember]
public bool SingleClickItemExecute { get; set; }
Property Value
Type Description
bool

VisibleItemsMax

The maximum amount of items that can be shown in the listbox.

Declaration
public int VisibleItemsMax { get; set; }
Property Value
Type Description
int

VisibleItemsTotal

The total items visible in the listbox.

Declaration
public int VisibleItemsTotal { get; set; }
Property Value
Type Description
int

Methods

GetItemAndIndexUnderMouse(ControlMouseState)

Returns the item under the mouse, and its array position.

Declaration
public (object? item, int itemIndex) GetItemAndIndexUnderMouse(ControlBase.ControlMouseState state)
Parameters
Type Name Description
ControlBase.ControlMouseState state

The mouse state.
Returns
Type Description
(object item, int itemIndex)

A tuple containing the item and the item's array position.
Exceptions
Type Condition
Exception

Thrown when the theme for the listbox isn't based on ListBoxTheme.

OnItemAction()

Invokes the SelectedItemExecuted event.

Declaration
protected virtual void OnItemAction()

OnLeftMouseClicked(ControlMouseState)

Called when the left mouse button is clicked. Raises the MouseButtonClicked event and calls the DetermineState() method.

Declaration
protected override void OnLeftMouseClicked(ControlBase.ControlMouseState state)
Parameters
Type Name Description
ControlBase.ControlMouseState state

The current mouse data
Overrides

OnMouseIn(ControlMouseState)

Called as the mouse moves around the control area. Raises the MouseMove event and calls the DetermineState() method.

Declaration
protected override void OnMouseIn(ControlBase.ControlMouseState state)
Parameters
Type Name Description
ControlBase.ControlMouseState state

The current mouse data
Overrides

OnResized()

Called when Resize(int, int) was called.

Declaration
protected override void OnResized()
Overrides

OnSelectedItemChanged()

Invokes the SelectedItemChanged event.

Declaration
protected virtual void OnSelectedItemChanged()

ProcessKeyboard(Keyboard)

Called when the keyboard is used on this control.

Declaration
public override bool ProcessKeyboard(Keyboard info)
Parameters
Type Name Description
Keyboard info
Returns
Type Description
bool
Overrides

RefreshThemeStateColors(Colors)

Updates the ThemeState by calling RefreshTheme(Colors) with the provided colors. Override this method to adjust how colors are used by the ThemeState.

Declaration
protected override void RefreshThemeStateColors(Colors colors)
Parameters
Type Name Description
Colors colors

The colors to apply to the theme state.
Overrides

ScrollToSelectedItem()

Scrolls the list to the item currently selected.

Declaration
public void ScrollToSelectedItem()

SetupScrollBar()

Sets up the scroll bar for the listbox.

Declaration
protected virtual void SetupScrollBar()

SetupScrollBar(Orientation, int, Point)

Configures the associated ScrollBar.

Declaration
public void SetupScrollBar(Orientation orientation, int sizeValue, Point position)
Parameters
Type Name Description
Orientation orientation

The orientation of the scrollbar.
int sizeValue

The size of the scrollbar.
Point position

The position of the scrollbar.

ShowHideScrollBar()

Shows the scroll bar when there are too many items to display; otherwise, hides it.

Declaration
protected void ShowHideScrollBar()

UpdateAndRedraw(TimeSpan)

Updates each control hosted by this control.

Declaration
public override void UpdateAndRedraw(TimeSpan time)
Parameters
Type Name Description
TimeSpan time

The game frame time delta.
Overrides

Events

SelectedItemChanged

An event that triggers when the SelectedItem property changes.

Declaration
public event EventHandler<ListBox.SelectedItemEventArgs>? SelectedItemChanged
Event Type
Type Description
EventHandler<ListBox.SelectedItemEventArgs>

SelectedItemExecuted

An event that triggers when an item is double clicked or the Enter key is pressed while the listbox has focus.

Declaration
public event EventHandler<ListBox.SelectedItemEventArgs>? SelectedItemExecuted
Event Type
Type Description
EventHandler<ListBox.SelectedItemEventArgs>

SelectedItemReselected

An event that triggers when the SelectedItem property is reselected by the mouse.

Declaration
public event EventHandler<ListBox.SelectedItemEventArgs>? SelectedItemReselected
Event Type
Type Description
EventHandler<ListBox.SelectedItemEventArgs>

Implements

Extension Methods