PromptPlus

# PromptPlus ## **Timer — Methods** [](https://www.nuget.org/packages/PromptPlus) [](https://opensource.org/licenses/MIT) [](https://dotnet.microsoft.com/)

← Back to Home • Next: Timer — Operations →

---

Every fluent method on ITimerControl. Each returns the same control instance, so calls chain in any order. Call Run last.

The factory is PromptPlus.Controls.Timer(string prompt = "", string? description = null), which returns ITimerControl. Duration is required — without it there is no length to count.

Quick jump: Duration · DisplayMode · Format · Spinner · Finish · ChangeDescription · ChangeDescriptionAsync · Culture · Styles · Options · Run

---

Length

Duration

ITimerControl Duration(TimeSpan duration)
ITimerControl Duration(int seconds)

Sets how long the control waits while showing the count. Required; must be greater than zero.

Overload	Use when
Duration(int seconds)	You have a whole number of seconds
Duration(TimeSpan duration)	You need sub-second or larger precision

// seconds
PromptPlus.Controls.Timer("Starting in").Duration(3).Run();

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

Both overloads throw ArgumentOutOfRangeException when the value is less than or equal to zero. If Duration is never called at all, Run() throws InvalidOperationException instead — omitting the call is not silently treated as “no wait.”

---

Display

DisplayMode

ITimerControl DisplayMode(TimerDisplayMode mode)

Chooses whether the on-screen number counts down or up. Default TimerDisplayMode.Countdown.

TimerDisplayMode	Shows
Countdown	The remaining time, counting down to zero (default)
Elapsed	The elapsed time, counting up from zero to the duration

PromptPlus.Controls.Timer("Running")
    .Duration(5)
    .DisplayMode(TimerDisplayMode.Elapsed)
    .Run();

Either way, Run() still returns the elapsed time in .Content.

---

Format

ITimerControl Format(string format)

Sets the TimeSpan format string used to render the number. Default hh\:mm\:ss.

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

Use verbatim strings (@"…") or escape the separators (\:) as TimeSpan formatting requires.

---

Spinner

ITimerControl Spinner(SpinnersType spinnersType)

Shows an animated spinner next to the time value while the countdown runs. SpinnersType offers many styles across several families (common ones: Default, Dots, Line, Star); on non-Unicode terminals it automatically falls back to the Ascii spinner. See Spinners and the Spinner catalog for the full list and frames.

PromptPlus.Controls.Timer("Please wait")
    .Duration(5)
    .Spinner(SpinnersType.Default)
    .Run();

---

Finish

ITimerControl Finish(string finishtext)

Sets the text shown when the countdown finishes. When not set, the elapsed time is shown.

PromptPlus.Controls.Timer("Please wait")
    .Duration(3)
    .Finish("Done!")
    .Run();

---

Text & culture

ChangeDescription

ITimerControl ChangeDescription(Func<TimeSpan, string> value)

Recomputes the description line as the countdown runs. The value passed follows DisplayMode — remaining time in Countdown mode (the default shown below), elapsed time in Elapsed mode.

PromptPlus.Controls.Timer("Please wait")
    .Duration(5)
    .ChangeDescription(remaining => $"Remaining: {remaining.TotalSeconds:0} second(s)")
    .Run();

Throws ArgumentNullException if value is null. In Elapsed display mode the callback receives elapsed, not remaining, time; compute the remainder yourself (duration - elapsed) if you need it.

---

ChangeDescriptionAsync

ITimerControl ChangeDescriptionAsync(Func<TimeSpan, Task<string>> value)

Asynchronous version of ChangeDescription.

PromptPlus.Controls.Timer("Please wait")
    .Duration(5)
    .ChangeDescriptionAsync(async remaining =>
    {
        await Task.Delay(1).ConfigureAwait(false);
        return $"Async remaining: {remaining:ss} s";
    })
    .Run();

Throws ArgumentNullException if value is null.

---

Culture

ITimerControl Culture(CultureInfo culture)

Sets the culture used to format the countdown value.

using System.Globalization;

PromptPlus.Controls.Timer("Aguarde")
    .Duration(4)
    .Culture(new CultureInfo("pt-BR"))
    .Run();

Throws ArgumentNullException if culture is null.

---

Styling & behavior

Styles

ITimerControl Styles(TimerStyles styleType, Style style)

Overrides the color of one visual region of this control instance. See the full region list and examples on the Styles page.

using ConsolePlusLibrary;
using PromptPlusLibrary;

PromptPlus.Controls.Timer("Please wait")
    .Duration(5)
    .Styles(TimerStyles.Prompt, new Style(Color.Yellow, Color.Black))
    .Styles(TimerStyles.Answer, new Style(Color.Green, Color.Black))
    .Run();

---

Options

ITimerControl Options(Action<IControlOptions> options)

Overrides global behaviors (PromptPlus.Config) for this one control — prompt/description text, tooltip, abort key, and hide-after-finish.

PromptPlus.Controls.Timer("Please wait")
    .Duration(4)
    .Options(opt =>
    {
        opt.Description("Press ESC to abort the countdown");
        opt.ShowTooltip(false);
        opt.EnabledAbortKey(true);
        opt.HideAfterFinish(false);
    })
    .Run();

See Global Behaviors → Per-Control Override for the complete IControlOptions list.

Throws ArgumentNullException if options is null.

---

Running the control

Run

ResultPrompt<TimeSpan> Run(CancellationToken token = default)

Displays the countdown and blocks until it completes or is cancelled. Returns a ResultPrompt<TimeSpan> whose .Content is the elapsed time.

Parameter	Meaning
token	A CancellationToken that ends the countdown early.

using (var sw = new CancellationTokenSource(TimeSpan.FromSeconds(2)))
{
    var result = PromptPlus.Controls.Timer("Cancelable countdown", "Runs with a CancellationToken")
        .Duration(10)
        .Run(sw.Token);
    // result.IsAborted == true; result.Content is the ~2s elapsed
}

---

See also

• Operations — how these methods behave at runtime
• Styles — the TimerStyles regions
• Index — overview and method map

This site is open source. Improve this page.