Skip to content

operations.md

Latest commit

 

History

History
177 lines (127 loc) · 6.71 KB

operations.md

File metadata and controls

177 lines (127 loc) · 6.71 KB
Raw
PromptPlus

PromptPlus

KeyPress — Operations

NuGet License: MIT .NET

← Back to Home • Next: KeyPress — Styles →

How the KeyPress control behaves while it is running: the single-keystroke wait, how valid keys are matched, the invalid-key message, the tooltip, and aborting.

Anatomy of the control

Press a valid key                        ← prompt
A, Ctrl+B, N(Off), Y(On)                 ← description (optional)
Esc:Abort.Ctrl+F1:Show/hide tooltip      ← tooltip — does NOT list the valid keys, only hints
Invalid key 'Z'. Try A, Ctrl+B, N or Y. ← error line, only after a rejected key (renders AFTER the tooltip)

Every region can be recolored — see Styles.

The single-keystroke wait

Unlike text controls, KeyPress does not wait for Enter. It returns the instant an accepted key is pressed:

  • With no valid keys registered, the very first key the user presses ends the wait and is returned in .Content.
  • With one or more valid keys registered, only an accepted key ends the wait; every other key is rejected (see below) and the control keeps waiting.
// "Press any key to continue" — any key ends the wait
PromptPlus.Controls.KeyPress("Press any key to continue").Run();

Valid-key restriction

Each AddValidKey call accumulates one accepted combination. A key is accepted only when both its ConsoleKey and the required modifiers match a registered entry:

PromptPlus.Controls.KeyPress("Press a valid key", "A, Ctrl+B, N(Off), Y(On)")
    .AddValidKey(ConsoleKey.A)                              // A alone
    .AddValidKey(ConsoleKey.B, ConsoleModifiers.Control)   // requires Ctrl held
    .AddValidKey(ConsoleKey.N, null, "Off")                // N, labelled "Off"
    .AddValidKey(ConsoleKey.Y, null, "On")                 // Y, labelled "On"
    .Run();
  • No AddValidKey calls → any key is accepted. This is the "press any key" mode.
  • With a modifier requirement, the modifier must be held: AddValidKey(ConsoleKey.B, ConsoleModifiers.Control) accepts Ctrl+B, not a bare B.
  • The optional displayText changes what's shown on the Answer line once that key is pressed (not the tooltip — the tooltip never lists the valid keys at all, see Tooltip below). The returned .Content.Value.Key is still the real ConsoleKey either way.

💡 To branch on the result, compare .Content.Value.Key to the ConsoleKey you registered, e.g. if (result.Content is { } k && k.Key == ConsoleKey.Y).

Invalid-key message

When valid keys are registered and the user presses one that is not accepted:

  1. The control stays open (the wait continues).
  2. If a message callback is configured, its text is shown on the error line, styled with KeyPressStyles.Error.
  3. The message clears when the next key is pressed.

Set the text synchronously with ShowMessage or asynchronously with ShowMessageAsync; both receive the rejected ConsoleKeyInfo:

PromptPlus.Controls.KeyPress("Press a valid key")
    .AddValidKey(ConsoleKey.A)
    .AddValidKey(ConsoleKey.Y, null, "On")
    .ShowMessage(key => $"Invalid key '{key.Key}'. Try A or Y.")
    .Run();

If no message callback is set, a rejected key is simply ignored and the control keeps waiting silently.

Tooltip

⚠️ The tooltip line does not list the accepted keys — it only ever shows the abort hint and the show/hide-tooltip hint (e.g. Esc:Abort.Ctrl+F1:Show/hide tooltip), regardless of how many keys you registered with AddValidKey or what displayText you gave them. Toggle it per instance with Options(o => o.ShowTooltip(...)) or globally via PromptPlus.Config.

Key Action
F1 Cycle tooltip content
Ctrl+F1 Show / hide the tooltip

Abort

When the abort key is enabled (the default), pressing Esc cancels the wait:

  • .IsAborted is true.
  • .Content does have a value — the real Escape key's ConsoleKeyInfo (.Content.Value.Key == ConsoleKey.Escape). .Content is only genuinely null/no-value when the wait ends via the CancellationToken passed to Run(...), not via Esc.
  • The Answer line switches to a localized "Canceled" label (instead of whatever key text would normally show) when ShowMessageAbortKey is true (the default).
var result = PromptPlus.Controls.KeyPress("Press a key").Run();
if (result.IsAborted)
    PromptPlus.Console.WriteLine("Cancelled.");
else
    PromptPlus.Console.WriteLine($"Pressed {result.Content!.Value.Key}");

Disable Esc with Options(o => o.EnabledAbortKey(false)) to force the user to press a valid key.

Options that change behavior

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

Option Effect on KeyPress
EnabledAbortKey(false) Removes Esc — the user must press a valid key
HideAfterFinish(true) Erases the prompt after a key is pressed
HideOnAbort(true) Erases the prompt after Esc
ShowTooltip(false) Hides the key-hint line
Prompt(...) / Description(...) Overrides the prompt / description text

The showresult factory parameter is the sibling switch for whether the pressed-key answer line remains visible after the control finishes.

Edge cases & gotchas

  • .Content is nullable, but an Esc-abort still populates it with the real Escape ConsoleKeyInfo — only a CancellationToken cancel leaves it null. Branch on .IsAborted, not on .Content.HasValue, to detect an abort.
  • Modifiers matter. A registered Ctrl+B will not match a bare B, and vice versa.
  • Message callbacks block the UI thread — see the warning under ShowMessageAsync.

See also