Skip to content

operations.md

Latest commit

 

History

History
175 lines (128 loc) · 6.02 KB

operations.md

File metadata and controls

175 lines (128 loc) · 6.02 KB
Raw
PromptPlus

PromptPlus

Timer — Operations

NuGet License: MIT .NET

← Back to Home • Next: Timer — Styles →

How the Timer control behaves while it runs: the required duration, count-down vs. count-up display, formatting, cancellation, and the details that matter in real apps.

Anatomy of the control

Please wait  00:00:03  ⠹                   ← prompt + time value + spinner (optional)
Remaining: 3 second(s)                     ← ChangeDescription output (optional)
Done!                                       ← Finish text (at the end)
Esc: cancel                               ← tooltip

The Timer control is non-interactive: there is nothing to type or select. The only user action is Esc to abort (when enabled). Each region can be recolored — see Styles.

Duration is required

There is no default length — you must call Duration with a value greater than zero, as seconds or a TimeSpan:

PromptPlus.Controls.Timer("Starting in").Duration(3).Run();                     // 3 seconds
PromptPlus.Controls.Timer("Cooling down").Duration(TimeSpan.FromSeconds(10)).Run();

A zero or negative duration throws ArgumentOutOfRangeException from Duration(...) itself. Never calling Duration(...) at all throws InvalidOperationException from Run() instead.

Count down or count up

DisplayMode controls only what the on-screen number shows:

  • Countdown (default) — the number starts at the duration and ticks toward 00:00:00.
  • Elapsed — the number starts at zero and ticks up to the duration.

The value passed to the ChangeDescription callback follows DisplayMode, same as the on-screen number: remaining time in Countdown mode, elapsed time in Elapsed mode. In Elapsed mode, derive the remainder yourself if you need it:

var totalDuration = TimeSpan.FromSeconds(5);

PromptPlus.Controls.Timer("Running")
    .Duration(totalDuration)
    .DisplayMode(TimerDisplayMode.Elapsed)
    .ChangeDescription(elapsed =>
    {
        var remaining = totalDuration - elapsed;
        if (remaining < TimeSpan.Zero) remaining = TimeSpan.Zero;
        return $"Remaining: {remaining.TotalSeconds:0} second(s)";
    })
    .Run();

Regardless of display mode, Run() returns the elapsed TimeSpan in .Content.

Formatting

Format is a standard TimeSpan format string; the default is hh\:mm\:ss. Combine it with Culture for locale-specific rendering.

PromptPlus.Controls.Timer("Countdown")
    .Duration(5)
    .Format(@"mm\:ss\:fff")     // show milliseconds
    .Run();

Cancellation

The countdown ends early — reporting IsAborted == true — when the user presses Esc (abort key enabled) or the Run(token) token fires. On abort, .Content holds the time elapsed so far, not the full duration.

using (var sw = new CancellationTokenSource(TimeSpan.FromSeconds(2)))
{
    var result = PromptPlus.Controls.Timer("Cancelable countdown")
        .Duration(10)
        .Run(sw.Token);
    // result.IsAborted == true; result.Content ≈ 2 seconds
}

Spinners

Spinner(SpinnersType) shows a looping animation next to the countdown while it runs. SpinnersType spans several families — braille/dots, lines/bars, shapes, toggles, arrows/motion, and emoji. On a terminal without Unicode support it automatically falls back to the Ascii spinner (- \ | /).

See Spinners for usage and the fallback rules, and the Spinner catalog for every spinner's frames.

Options that change behavior

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

Option Effect on Timer
EnabledAbortKey(true/false) Enables/removes Esc as a way to end the countdown early
ShowMessageAbortKey(true) Shows the abort-key hint
HideAfterFinish(true) Erases the control after the countdown ends
HideOnAbort(true) Erases the control after Esc
ShowTooltip(false) Hides the keyboard-hint line
Prompt(...) / Description(...) Overrides the prompt / description text 
PromptPlus.Controls.Timer("Please wait")
    .Duration(4)
    .Options(opt =>
    {
        opt.Description("Press ESC to abort the countdown");
        opt.ShowTooltip(false);
        opt.ShowMessageAbortKey(true);
        opt.EnabledAbortKey(true);
        opt.HideAfterFinish(false);
        opt.HideOnAbort(false);
    })
    .Run();

Edge cases & gotchas

  • Not a picker. Timer waits and displays a clock; it does not collect a time value. To enter a time, use a MaskEdit date/time control.
  • Duration is mandatory. Forgetting it (or passing 0) throws.
  • Description follows DisplayMode — it receives elapsed time in Elapsed mode, not remaining time; compute the counterpart yourself if you need it.
  • Async description refresh is awaited synchronously — keep ChangeDescriptionAsync fast.
  • A blank prompt is fine: PromptPlus.Controls.Timer().Duration(5)... renders just the countdown.

See also