Table of Contents

Class DropDownList

Namespace
Terminal.Gui.Views
Assembly
Terminal.Gui.dll

A dropdown/combo-box control that combines a TextField with a popover ListView for selecting from a list of items.

public class DropDownList : TextField, IDisposable, ISupportInitializeNotification, ISupportInitialize, IDesignable, IValue<string>, IValue
Inheritance
DropDownList
Implements
Derived
Inherited Members
Extension Methods

Remarks

DropDownList demo

DropDownList provides a modern dropdown control that can operate in two modes:

  • ReadOnly mode (ReadOnly = true): Acts like a traditional dropdown where clicking anywhere opens the list. The text field is not editable.
  • Editable mode (ReadOnly = false): Acts like a combo box where the user can type text or select from the list.

Key Features:

  • Toggle dropdown with button click, F4, or Alt+Down
  • Pre-selects matching item in list when opening
  • Returns focus to text field when closed
  • Supports IValue<TValue> interface for data binding
  • Auto-registers popover on first use

Usage Example: 

<pre><code class="lang-csharp">var dropdown = new DropDownList

{ Source = new ListWrapper<string> (["Option 1", "Option 2", "Option 3"]), ReadOnly = true, Text = "Option 1" }; dropdown.ValueChanged += (s, e) => MessageBox.Query ("Selected", dropdown.Text, "Ok");

<p>
    Default key bindings are defined in <xref href="Terminal.Gui.Views.DropDownList.DefaultKeyBindings" data-throw-if-not-resolved="false"></xref> (in addition to
    <xref href="Terminal.Gui.Views.TextField" data-throw-if-not-resolved="false"></xref> bindings):
</p>
<table><thead><tr><th class="term">Key</th><th class="description">Action</th></tr></thead><tbody><tr><td class="term">F4</td><td class="description">Toggles the dropdown list open or closed.</td></tr><tr><td class="term">Alt+Down</td><td class="description">Toggles the dropdown list open or closed.</td></tr><tr><td class="term">Space</td><td class="description">Toggles the dropdown list open or closed.</td></tr><tr><td class="term">Up</td><td class="description">Selects the previous item in the list (when closed).</td></tr><tr><td class="term">Down</td><td class="description">Selects the next item in the list (when closed).</td></tr></tbody></table>
<p>Default mouse bindings:</p>
<table><thead><tr><th class="term">Mouse Event</th><th class="description">Action</th></tr></thead><tbody><tr><td class="term">Click</td><td class="description">Activates the dropdown (<xref href="Terminal.Gui.Input.Command.Activate" data-throw-if-not-resolved="false"></xref>).</td></tr></tbody></table>

Constructors

DropDownList()

Initializes a new instance of the DropDownList class.

Properties

DefaultKeyBindings

Gets or sets the view-specific default key bindings for DropDownList. Contains only bindings unique to this view; shared bindings come from DefaultKeyBindings.

IMPORTANT: This is a process-wide static property. Change with care. Do not set in parallelizable unit tests.

KeystrokeNavigator

Gets the IListCollectionNavigator that searches the Source collection as the user types when the dropdown is closed.

Source

Gets or sets the data source for the dropdown list.

Methods

Dispose(bool)

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

EnableForDesign()
EndInit()

Signals the View that initialization is ending. See ISupportInitialize.

GetDemoKeyStrokes()

Returns a tuirec-format keystroke string for recording a demo GIF of this view. The string uses tuirec token syntax (e.g. "wait:500,Enter,wait:800,Escape"). This is a new API added in v2 to support automated documentation generation.

OnAccepted(ICommandContext?)

Called when the View has been accepted. This is called after Accepting has been raised and not cancelled.

OnActivated(ICommandContext?)

Called when the View has been activated. This is called after Accepting has been raised and not cancelled.

OnGettingAttributeForRole(in VisualRole, ref Attribute)

Overrides attribute retrieval to ensure that in ReadOnly mode, the control uses the Normal or Focus attributes

OnHasFocusChanging(bool, bool, View?, View?)

Invoked when HasFocus is about to change. This method is called before the HasFocusChanging event is raised.

OnKeyDown(Key)

Called when the user presses a key, allowing subscribers to pre-process the key down event. Called before key bindings are invoked and KeyDownNotHandled is raised. Set Handled to true to stop the key from being processed further.

OnMouseEvent(Mouse)

Called when a mouse event occurs within the view's Viewport.

Edit this page