Skip to content

operations.md

Latest commit

 

History

History
194 lines (137 loc) · 7.77 KB

operations.md

File metadata and controls

194 lines (137 loc) · 7.77 KB
Raw
PromptPlus

PromptPlus

TableSelect<T> — Operations

NuGet License: MIT .NET

← Back to Home • Next: TableSelect — Styles →

How the TableSelect<T> control behaves while it is running: keyboard, columns, filtering, horizontal scrolling, paging, validation, history, and view-only mode.

Anatomy of the control

Select a product                         ← prompt
Category: Electronics                     ← description (optional / dynamic)
┌──────┬───────────────┬────────────┐
│  Id  │ Name          │   Price    │    ← header row
├──────┼───────────────┼────────────┤
│    1 │ Notebook Pro  │  $ 1299.99 │    ← focused row (SelectedCell)
│    2 │ Wireless Mouse│  $   29.90 │
└──────┴───────────────┴────────────┘
Filter: note                              ← live filter text (when filtering)
Page 1/2                                  ← pagination
Enter: confirm  Esc: cancel               ← tooltip

Every region can be recolored — see Styles.

Keyboard

Key Action
↑ / ↓ Move focus up / down (rows)
Page Up / Page Down Jump one page
Ctrl+Home / Ctrl+End First / last row
Tab / Shift+Tab Move the focused column; wraps around at the first/last column
Enter Confirm the focused row (runs validation)
Esc Abort → IsAborted == true
Any printable character Type to filter (when Filter is not Disabled)
Backspace Edit the filter text
F1 Cycle tooltip content
Ctrl+F1 Show / hide the tooltip

Disabled rows are skipped automatically as you move.

Columns

  • AddColumn is header-first: header text, then a Func<T, object> selector, then optional formatter, width, alignment, and filterable flag.
  • Width is either fixed (width: n) or auto-sized from the header and all cell values at Run time.
  • Content that exceeds the column width is truncated with an ellipsis; the full row is still returned in .Content.Value.

Column alignment

ColumnAlignment sets per-column horizontal alignment:

Value Effect
Left Align cell content to the left (default)
Right Align cell content to the right (typical for numbers)
Center Center cell content

Horizontal scrolling

Tab / Shift+Tab always move the focused column, wrapping around at the first/last column — this works even when every column already fits on screen and nothing needs to scroll; the focused column is always highlighted and reported in the pagination line as Col X/Y. HorizontalScroll only changes what happens once scrolling is actually needed (the columns don't all fit within the console width):

  • Full (default) — shifts the visible viewport as a full column window.
  • Column — focuses one column at a time.

The focused column's index is returned as .Content.ColumnIndex.

Layout & border regions

  • LayoutMode picks the box-drawing character set: SingleBox (default), DoubleBox, SingleASCII, DoubleASCII, or None (no borders).
  • HideElements hides individual regions — RowSeparator, Header, ColumnSeparator, OuterBorder — and combines with | to strip several at once. HideTable.None (default) shows everything.

Filtering

When Filter is Contains or StartsWith, typing narrows the visible rows in real time:

  • The match is case-insensitive.
  • FilterTableMode.Answer matches against the answer text (TextSelector).
  • FilterTableMode.ColumnFilters matches against the concatenated text of every column declared with isFilterable: true.
  • Matching resets paging to the first page of results.
  • Clearing the filter (Backspace) restores the full list.

Disabled (the default) turns typing off entirely — arrow keys only.

Confirmation & validation flow

Pressing Enter on the focused row:

  1. Validation runs — PredicateSelected / PredicateSelectedAsync, if configured.
  2. Valid → the control closes and returns the row inside a TableSelectResult<T>. Invalid → the table stays open and shows the error line.

Disabled rows cannot be focused for confirmation, so validation typically guards business rules rather than availability.

Initial selection & history

View-only mode

ViewOnly() renders the table for display only:

  • Arrow and column keys still navigate, but the selection cannot change.
  • On Enter the control returns the item highlighted at startup (from Default or the first row), regardless of where the user browsed.
  • Selection predicates and disabled-row restrictions are not enforced.

Options that change behavior

Set per instance via Options(...), or globally on PromptPlus.Config:

Option Effect on TableSelect<T>
EnabledAbortKey(false) Removes Esc — the user must choose
HideAfterFinish(true) Erases the table after confirm — the whole control is erased, not just the interactive part
ShowTooltip(false) Hides the keyboard hint line
Prompt(...) / Description(...) Overrides the prompt / description text

PageSize can be set per control (PageSize) or globally (PromptPlus.Config.PageSize).

Edge cases & gotchas

  • Configuration is required. Run throws ValidationException unless at least one column and one row have been added.
  • Aborted results carry .Content == default (a TableSelectResult<T> with default(T)). Always branch on IsAborted.
  • Custom types need equality. Without DefaultMatchBy, Default on a record/class may not match the intended row.
  • Async callbacks block the UI thread — keep validators, selectors, and description callbacks fast.
  • Long cells are truncated with …; the full row is still returned in .Content.Value.

See also