Class PromptControl

Namespace

SharpConsoleUI.Controls

Assembly

SharpConsoleUI.dll

A text input control with optional prompt text.

Single-line by default: it measures one row and scrolls horizontally when the text outgrows the field. Set Multiline to let it soft-wrap and grow between MinRows and MaxRows instead — the value stays one string either way, so callers binding to Input are unaffected by the mode.

Split across partial files: .Content (the value, selection, history, clipboard), .Keyboard (the key table and completion), .Mouse (pointer and drag selection), and .Rendering (measure, paint, caret mapping).

public class PromptControl : BaseControl, IDOMPaintable, INotifyPropertyChanged, IInteractiveControl, IFocusableControl, IMouseAwareControl, IWindowControl, IDisposable, ILogicalCursorProvider, ICursorShapeProvider, IPasteTarget, IColorRoleableControl

Inheritance

object

BaseControl

PromptControl

Implements

IDOMPaintable

INotifyPropertyChanged

IInteractiveControl

IFocusableControl

IMouseAwareControl

IWindowControl

IDisposable

ILogicalCursorProvider

ICursorShapeProvider

IPasteTarget

IColorRoleableControl

Inherited Members

BaseControl.PropertyChanged

BaseControl.GotFocus

BaseControl.LostFocus

BaseControl.Bindings

BaseControl.OnPropertyChanged(string)

BaseControl.SubscribeToFocusManager()

BaseControl.SetProperty<T>(ref T, T, string)

BaseControl.SetProperty<T>(ref T, T, Func<T, T>, string)

BaseControl.ActualX

BaseControl.ActualY

BaseControl.ActualWidth

BaseControl.ActualHeight

BaseControl.HorizontalAlignment

BaseControl.VerticalAlignment

BaseControl.Container

BaseControl.Margin

BaseControl.StickyPosition

BaseControl.Name

BaseControl.Tag

BaseControl.Visible

BaseControl.Width

BaseControl.Height

BaseControl.Invalidate(Invalidation)

BaseControl.Invalidate()

BaseControl.Invalidate(bool)

BaseControl.SetActualBounds(LayoutRect)

BaseControl.Dispose()

BaseControl.ComputeHasFocus()

BaseControl.ComputeIsInFocusPath()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

WindowControlExtensions.RequestFocus(IFocusableControl, FocusReason)

WindowControlExtensions.GetParentWindow(IWindowControl)

WindowControlExtensions.GetPortalAncestor(IWindowControl)

BindingExtensions.BindTwoWay<TControl, TSource, TValue>(TControl, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.BindTwoWay<TControl, TSource, TSrc, TTgt>(TControl, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>, Func<TTgt, TSrc>)

BindingExtensions.BindTwoWay<TBuilder, TControl, TSource, TValue>(TBuilder, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.BindTwoWay<TBuilder, TControl, TSource, TSrc, TTgt>(TBuilder, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>, Func<TTgt, TSrc>)

BindingExtensions.Bind<TControl, TSource, TValue>(TControl, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.Bind<TControl, TSource, TSrc, TTgt>(TControl, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>)

BindingExtensions.Bind<TBuilder, TControl, TSource, TValue>(TBuilder, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.Bind<TBuilder, TControl, TSource, TSrc, TTgt>(TBuilder, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>)

Properties

CanFocusWithMouse

Whether this control can receive focus via mouse clicks

public bool CanFocusWithMouse { get; }

Property Value

bool

CanReceiveFocus

Whether this control can receive focus

public bool CanReceiveFocus { get; }

Property Value

bool

ColorRole

The semantic color role. Default = no role (normal resolution).

public ColorRole ColorRole { get; set; }

Property Value

ColorRole

ColorRoleMode

Optional ThemeMode override for role-colour derivation. When non-null, the role's dark/light seed colours are resolved as if the theme were in this mode, regardless of the theme's own Mode. When null (the default), the active theme's mode is used.

public ThemeMode? ColorRoleMode { get; set; }

Property Value

ThemeMode?

ContentWidth

Gets the actual rendered width of the control content in characters.

public override int? ContentWidth { get; }

Property Value

int?

EnterBehavior

Gets or sets what the Enter key does. Defaults to Submit, so Enter means the same thing it always has regardless of Multiline, and a command line becomes a wrapping command line by setting one flag.

public EnterBehavior EnterBehavior { get; set; }

Property Value

EnterBehavior

HasFocus

public bool HasFocus { get; }

Property Value

bool

HasSelection

Gets whether there is an active text selection.

public bool HasSelection { get; }

Property Value

bool

History

The recorded history, oldest first.

public IReadOnlyList<string> History { get; }

Property Value

IReadOnlyList<string>

Remarks

Read-only, and a SNAPSHOT rather than a live view: the internal list is mutated on every submit and trimmed past MaxHistoryEntries, so handing out the list itself would let a caller observe it changing underneath them — or mutate it and desync the ↑/↓ index that walks it.

Exposed so history can outlive the control: an application that wants ↑ to reach what was typed in a PREVIOUS session has to be able to read what was typed in this one. RecordHistory(string) is the other half — read them out at shutdown, feed them back at startup.

HistoryEnabled

Gets or sets whether command history is enabled (Up/Down arrow recall).

public bool HistoryEnabled { get; set; }

Property Value

bool

Input

Gets or sets the current input text entered by the user.

public string Input { get; set; }

Property Value

string

InputBackgroundColor

Gets or sets the background color of the input area when not focused.

public Color? InputBackgroundColor { get; set; }

Property Value

Color?

InputFocusedBackgroundColor

Gets or sets the background color of the input area when focused.

public Color? InputFocusedBackgroundColor { get; set; }

Property Value

Color?

InputFocusedForegroundColor

Gets or sets the foreground color of the input text when focused.

public Color? InputFocusedForegroundColor { get; set; }

Property Value

Color?

InputForegroundColor

Gets or sets the foreground color of the input text when not focused.

public Color? InputForegroundColor { get; set; }

Property Value

Color?

InputWidth

Gets or sets the width of the input area in characters. When set, enables horizontal scrolling.

public int? InputWidth { get; set; }

Property Value

int?

IsEnabled

Gets or sets whether this control is enabled and can receive input.

public bool IsEnabled { get; set; }

Property Value

bool

MaskCharacter

Gets or sets a character to display instead of the actual input (for password fields). When null, the actual input is displayed.

public char? MaskCharacter { get; set; }

Property Value

char?

MaxHistoryEntries

Gets or sets how many entries the history keeps. The oldest are dropped past this bound, because a long-running command line would otherwise grow its history for the life of the process. Consecutive duplicates are not recorded at all.

public int MaxHistoryEntries { get; set; }

Property Value

int

MaxLength

Gets or sets the maximum length of the value in characters, or null for unlimited. Enforced on typing, on paste (the pasted text is truncated to fit rather than rejected), and on SetInput(string?). Counted the same way as MaxLength — in characters, not display columns.

public int? MaxLength { get; set; }

Property Value

int?

MaxRows

Gets or sets the maximum number of rows the control grows to when Multiline is set. Content taller than this scrolls vertically. Ignored in single-line mode.

public int MaxRows { get; set; }

Property Value

int

MinRows

Gets or sets the minimum number of rows the control measures when Multiline is set. Ignored in single-line mode, where the height is always one row.

public int MinRows { get; set; }

Property Value

int

Multiline

Gets or sets whether the value may contain newlines and wrap across rows.

Defaults to false, which is the historical behaviour in full: one row, horizontal scrolling, and newlines flattened to spaces on both SetInput(string?) and Paste(string). Turning it on makes the control soft-wrap at its content width and measure between MinRows and MaxRows rows.

public bool Multiline { get; set; }

Property Value

bool

Outline

When true and a role is set, renders outline style (role color on text + border, surface fill).

public bool Outline { get; set; }

Property Value

bool

Placeholder

Gets or sets text shown in place of an empty value, to say what belongs in the field. Rendered dimmed, and only while the value is empty; it is never part of Input and never submitted.

public string? Placeholder { get; set; }

Property Value

string

PreferredCursorShape

Gets the preferred cursor shape - always VerticalBar for text input

public CursorShape? PreferredCursorShape { get; }

Property Value

CursorShape?

Prompt

Gets or sets the prompt text displayed before the input area.

public string? Prompt { get; set; }

Property Value

string

ReadOnly

Gets or sets whether the text can be edited. A read-only prompt still takes focus, moves its cursor, selects and copies — it only refuses the operations that would change the value. Distinct from IsEnabled, which refuses everything and paints disabled.

public bool ReadOnly { get; set; }

Property Value

bool

SelectedText

Gets the selected text, or null if no selection.

public string? SelectedText { get; }

Property Value

string

TabCompleter

Gets or sets the tab completion delegate. When set, Tab key triggers completion. The delegate receives (input, cursorPosition) and returns completion candidates. When no completions match, Tab passes through to focus traversal.

public Func<string, int, IEnumerable<string>?>? TabCompleter { get; set; }

Property Value

Func<string, int, IEnumerable<string>>

UnfocusOnEnter

Gets or sets whether the control loses focus when Enter is pressed.

public bool UnfocusOnEnter { get; set; }

Property Value

bool

WantsMouseEvents

Whether this control wants to receive mouse events

public bool WantsMouseEvents { get; }

Property Value

bool

WantsTabKey

Whether this control wants Tab key events (for tab completion).

public bool WantsTabKey { get; }

Property Value

bool

Methods

ClearHistory()

Clears the command history.

public void ClearHistory()

GetLogicalContentSize()

Gets the logical size of the control's content without rendering.

public override Size GetLogicalContentSize()

Returns

Size

The size representing the content's natural dimensions.

GetLogicalCursorPosition()

Gets the logical cursor position within the control's content coordinate system. This should be the raw position without any visual adjustments for margins, scrolling, etc.

public Point? GetLogicalCursorPosition()

Returns

Point?

Logical cursor position or null if no cursor.

MeasureDOM(LayoutConstraints)

Measures the control's desired size given the available constraints.

public override LayoutSize MeasureDOM(LayoutConstraints constraints)

Parameters

constraints LayoutConstraints

The layout constraints (min/max width/height).

Returns

LayoutSize

The desired size of the control.

OnDisposing()

Called during Dispose() before Container is set to null. Override to perform control-specific cleanup (null events, close portals, clear data, etc.).

protected override void OnDisposing()

PaintDOM(CharacterBuffer, LayoutRect, LayoutRect, Color, Color)

Paints the control's content directly to a CharacterBuffer.

public override void PaintDOM(CharacterBuffer buffer, LayoutRect bounds, LayoutRect clipRect, Color defaultFg, Color defaultBg)

Parameters

buffer CharacterBuffer

The buffer to paint to.

bounds LayoutRect

The absolute bounds where the control should paint.

clipRect LayoutRect

The clipping rectangle (visible area).

defaultFg Color

defaultBg Color

Paste(string)

Inserts pasted text (IPasteTarget).

public void Paste(string text)

Parameters

text string

Remarks

In single-line mode newlines are flattened to spaces, as they always have been. In multiline mode the text is inserted verbatim, which is the point of the mode: a pasted block keeps its shape.

ProcessKey(ConsoleKeyInfo)

Processes a keyboard input event.

public bool ProcessKey(ConsoleKeyInfo key)

Parameters

key ConsoleKeyInfo

The key information for the pressed key.

Returns

bool

True if the key was handled by this control; otherwise, false.

ProcessMouseEvent(MouseEventArgs)

Processes a mouse event for this control

public bool ProcessMouseEvent(MouseEventArgs args)

Parameters

args MouseEventArgs

Mouse event arguments with control-relative coordinates

Returns

bool

True if the event was handled and should not propagate further

RecordHistory(string)

Records a value in the history as though it had been submitted here.

public void RecordHistory(string value)

Parameters

value string

The value to record.

Remarks

For an application that submits on its OWN terms rather than through this control's Enter — one that intercepts the key upstream (a window-level PreviewKeyPressed, say, to give Enter a meaning the control cannot know) and then reads Input itself. Submit() is never reached on that path, so nothing was ever recorded and ↑/↓ recalled an empty history: the control offered the feature and only its own key could feed it.

Same rules as an ordinary submit — empty values and consecutive duplicates are ignored, and the oldest entries drop past MaxHistoryEntries.

SetInput(string?)

Sets the input text and positions the cursor at the end.

public void SetInput(string? input)

Parameters

input string

The text to set as input.

SetLogicalCursorPosition(Point)

Sets the logical cursor position within the control's content coordinate system.

public void SetLogicalCursorPosition(Point position)

Parameters

position Point

Events

Entered

Event fired when Enter is pressed (modern standardized event)

public event EventHandler<string>? Entered

Event Type

EventHandler<string>

EnteredAsync

Async counterpart of Entered.

public event AsyncEventHandler<string>? EnteredAsync

Event Type

AsyncEventHandler<string>

InputChanged

Event fired when input text changes (modern standardized event)

public event EventHandler<string>? InputChanged

Event Type

EventHandler<string>

MouseClick

Event fired when the control is clicked

public event EventHandler<MouseEventArgs>? MouseClick

Event Type

EventHandler<MouseEventArgs>

MouseDoubleClick

Event fired when the control is double-clicked

public event EventHandler<MouseEventArgs>? MouseDoubleClick

Event Type

EventHandler<MouseEventArgs>

MouseEnter

Event fired when the mouse enters the control area

public event EventHandler<MouseEventArgs>? MouseEnter

Event Type

EventHandler<MouseEventArgs>

MouseLeave

Event fired when the mouse leaves the control area

public event EventHandler<MouseEventArgs>? MouseLeave

Event Type

EventHandler<MouseEventArgs>

MouseMove

Event fired when the mouse moves over the control

public event EventHandler<MouseEventArgs>? MouseMove

Event Type

EventHandler<MouseEventArgs>

MouseRightClick

Event fired when the control is right-clicked (Button3)

public event EventHandler<MouseEventArgs>? MouseRightClick

Event Type

EventHandler<MouseEventArgs>