PromptPlus

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

← Back to Home • Next: ProgressBar — Operations →

---

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

The factory is PromptPlus.Controls.ProgressBar(string prompt = "", string? description = null), which returns IProgressBarControl.

Quick jump: UpdateHandler · UpdateHandlerAsync · Range · Default · FractionalDigits · Width · Fill · Spinner · ChangeColor · ChangeGradient · HideElements · Finish · ChangeDescription · ChangeDescriptionAsync · Culture · Styles · Options · Run

---

The work loop

The progress value is not something you set once — it is driven by a handler that loops while the work runs. Register exactly one handler (sync or async). Inside it you receive a ProgressBarEvent whose Update(value) moves the bar. See Operations for the full event surface.

UpdateHandler

IProgressBarControl UpdateHandler(
    Action<ProgressBarEvent, CancellationToken> value,
    IDictionary<string, object?>? context = null)

Registers a synchronous work loop.

Parameter	Meaning
value	The loop. Receives the ProgressBarEvent and the run’s CancellationToken. Cannot be null.
context	Optional input key/value data made available to the handler via evt.InputParam<T>(...).

PromptPlus.Controls.ProgressBar("Wait Progress: ")
    .UpdateHandler((bar, token) =>
    {
        while (!token.IsCancellationRequested && !bar.Finish)
        {
            token.WaitHandle.WaitOne(80);
            bar.Update(bar.Value + 2);
        }
    })
    .Run();

Throws ArgumentNullException if value is null.

---

UpdateHandlerAsync

IProgressBarControl UpdateHandlerAsync(
    Func<ProgressBarEvent, CancellationToken, Task> value,
    IDictionary<string, object?>? context = null)

Asynchronous counterpart of UpdateHandler, for loops that await I/O.

PromptPlus.Controls.ProgressBar("Wait Progress: ")
    .UpdateHandlerAsync(async (bar, token) =>
    {
        while (!token.IsCancellationRequested && !bar.Finish)
        {
            await Task.Delay(80, token).ConfigureAwait(false);
            bar.Update(bar.Value + 2);
        }
    })
    .Run();

Throws ArgumentNullException if value is null.

---

Range & value

Range

IProgressBarControl Range(double minvalue, double maxvalue)

Sets the numeric bounds of the bar. The default range is 0 to 100. bar.Finish becomes true once the value reaches maxvalue.

PromptPlus.Controls.ProgressBar("Wait Progress: ")
    .Range(-30, 30)
    .Default(-30)
    .UpdateHandler(Work)
    .Run();

Throws ArgumentOutOfRangeException when minvalue is strictly greater than maxvalue. minvalue == maxvalue does not throw here — but it does throw a separate ArgumentException (“the minimum value must be less than the maximum value”) when the control actually starts running, so it still fails, just later and with a different exception type.

---

Default

IProgressBarControl Default(double value)

Sets the initial value the bar starts at. If never called, it falls back to whatever Range’s minvalue is (0 only because that’s the default range) — not a literal 0 independent of the range. Must be inside the configured range.

PromptPlus.Controls.ProgressBar("Wait Progress: ")
    .Range(-30, 30)
    .Default(-30)
    .UpdateHandler(Work)
    .Run();

The setter itself validates nothing. The out-of-range check happens later, when the control actually starts running, and throws InvalidOperationException (not ArgumentOutOfRangeException).

---

FractionalDigits

IProgressBarControl FractionalDigits(byte value)

Sets how many fractional digits are shown for the value. Default 0 (whole numbers); maximum 5.

PromptPlus.Controls.ProgressBar("Wait Progress: ")
    .FractionalDigits(2)
    .UpdateHandler(Work)
    .Run();

Throws ArgumentOutOfRangeException when value is greater than 5.

---

Width

IProgressBarControl Width(byte value)

Sets the rendered width of the bar track, in characters. Default 40; minimum 10.

PromptPlus.Controls.ProgressBar("Wait Progress: ")
    .Width(30)
    .UpdateHandler(Work)
    .Run();

Throws ArgumentOutOfRangeException when value is less than 10.

---

Appearance

Fill

IProgressBarControl Fill(ProgressBarType type)

Chooses the visual fill style of the track. Default ProgressBarType.Fill.

ProgressBarType	Look
Fill	Solid filled bar (default)
Bar	A simple bar
Square	Square blocks
Light	Light-weight blocks
DoubleLight	Double light blocks
Dot	Dots

PromptPlus.Controls.ProgressBar("Wait Progress: ")
    .Fill(ProgressBarType.Square)
    .UpdateHandler(Work)
    .Run();

---

Spinner

IProgressBarControl Spinner(SpinnersType spinnersType)

Shows an animated spinner alongside the bar while the operation is running. SpinnersType offers many styles across several families (common ones: Default, Dots, Line, Star, Arc); 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.ProgressBar("Wait Progress: ")
    .Spinner(SpinnersType.Dots)
    .UpdateHandler(Work)
    .Run();

---

ChangeColor

IProgressBarControl ChangeColor(Func<double, Style> value)

Recomputes the bar color from the current value, so it changes as the bar advances. The callback receives the value and returns the Style to paint.

using ConsolePlusLibrary;

PromptPlus.Controls.ProgressBar("Wait Progress: ")
    .ChangeColor(value =>
    {
        if (value <= 30) return new Style(Color.Red, Color.Red);
        if (value <= 70) return new Style(Color.Blue, Color.Blue);
        return new Style(Color.Darkgoldenrod, Color.Darkgoldenrod);
    })
    .UpdateHandler(Work)
    .Run();

Throws ArgumentNullException if value is null.

---

ChangeGradient

IProgressBarControl ChangeGradient(params Color[] colors)

Applies a gradient across the filled portion, interpolated over the configured range as the value advances. Pass two or more colors.

using ConsolePlusLibrary;

PromptPlus.Controls.ProgressBar("Wait Progress: ")
    .ChangeGradient(Color.Green, Color.Yellow, Color.Red)
    .UpdateHandler(Work)
    .Run();

Throws ArgumentNullException if colors is null or empty.

---

HideElements

IProgressBarControl HideElements(HideProgressBar value)

Hides one or more visual elements. HideProgressBar is a [Flags] enum — combine with |.

HideProgressBar	Hides
None	Nothing (default)
Delimit	The bar delimiters
Range	The min/max range text
PromptAnswer	The prompt + answer line
ElapsedTime	The elapsed-time display
ProgressbarAtFinish	The whole bar once it finishes

PromptPlus.Controls.ProgressBar("Wait Progress: ")
    .HideElements(HideProgressBar.PromptAnswer | HideProgressBar.Range | HideProgressBar.Delimit)
    .UpdateHandler(Work)
    .Run();

---

Text & culture

Finish

IProgressBarControl Finish(string finishtext)

Sets the text shown when the bar completes, exposed afterwards as StateProgress.FinishedText.

PromptPlus.Controls.ProgressBar("Wait Progress: ")
    .Finish("End progress")
    .UpdateHandler(Work)
    .Run();

---

ChangeDescription

IProgressBarControl ChangeDescription(Func<double, string> value)

Refreshes the description line every time the value changes. The callback receives the current value and returns the text to display.

PromptPlus.Controls.ProgressBar("Wait Progress: ")
    .ChangeDescription(value => $"Processed: {value:0}%")
    .UpdateHandler(Work)
    .Run();

Throws ArgumentNullException if value is null.

---

ChangeDescriptionAsync

IProgressBarControl ChangeDescriptionAsync(Func<double, Task<string>> value)

Asynchronous version of ChangeDescription. The task is awaited synchronously each time the description refreshes — keep it fast.

PromptPlus.Controls.ProgressBar("Wait Progress: ")
    .ChangeDescriptionAsync(async value =>
    {
        await Task.Delay(10);
        return $"Processed (async): {value:0}%";
    })
    .UpdateHandler(Work)
    .Run();

Throws ArgumentNullException if value is null.

---

Culture

IProgressBarControl Culture(CultureInfo culture)
IProgressBarControl Culture(string cultureName)

Sets the culture used to format numeric values. Pass a CultureInfo or a culture name such as "pt-BR".

PromptPlus.Controls.ProgressBar("Wait Progress: ", "Culture: pt-BR")
    .Culture("pt-BR")
    .FractionalDigits(2)
    .UpdateHandler(Work)
    .Run();

The string overload throws ArgumentNullException for a null name, resolves an empty string to the invariant culture (no throw), and throws CultureNotFoundException for an unrecognized name.

---

Styling & behavior

Styles

IProgressBarControl Styles(ProgressBarStyles 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.ProgressBar("Wait Progress: ")
    .Styles(ProgressBarStyles.Slider, new Style(Color.Green, Color.Default))
    .UpdateHandler(Work)
    .Run();

---

Options

IProgressBarControl Options(Action<IControlOptions> options)

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

PromptPlus.Controls.ProgressBar("Wait Progress: ")
    .Options(o => o
        .ShowTooltip(true)
        .HideAfterFinish(true))
    .UpdateHandler(Work)
    .Run();

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

Throws ArgumentNullException if options is null.

---

Running the control

Run

ResultPrompt<StateProgress> Run(CancellationToken token = default)

Renders the bar and blocks until the update handler returns (work finished) or token is cancelled. Returns a ResultPrompt<StateProgress> — see Index → Return value.

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
var result = PromptPlus.Controls.ProgressBar("Work").UpdateHandler(Work).Run(cts.Token);

---

See also

• Operations — the ProgressBarEvent, context, cancellation, and errors
• Styles — the ProgressBarStyles regions
• Index — overview and method map

This site is open source. Improve this page.