methods.md

PromptPlus

Switch — Methods

← Back to Home • Next: Switch — Operations →

---

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

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

Quick jump: Default · OnValue · OffValue · EnableHistory · ChangeDescription · ChangeDescriptionAsync · Styles · Options · Run

---

Starting value

Default

ISwitchControl Default(bool value, bool useDefaultHistory = true)

Sets the initial state shown when the control opens. Default is false (off).

Parameter	Meaning
value	The initial state: true for on, false for off.
useDefaultHistory	When true (default) and history is enabled via EnableHistory, the last confirmed value in history is used instead of value.

PromptPlus.Controls.Switch("Enable feature?")
    .Default(true)
    .Run();

---

State labels

By default the two states show the localized Yes/No text. Override either state with plain text or with an emoji plus a fallback.

OnValue

Two overloads set the label for the on (true) state.

ISwitchControl OnValue(string value)
ISwitchControl OnValue(EmojiName emojiName, string fallbacktext)

Overload	Meaning
OnValue(string)	Plain-text label for the on state. Cannot be null.
OnValue(EmojiName, string)	Emoji label, with fallbacktext used when the terminal cannot render emoji. fallbacktext cannot be null.

// Plain text
PromptPlus.Controls.Switch("Environment")
    .OnValue("Production")
    .Run();

// Emoji with fallback
using PromptPlusLibrary;

PromptPlus.Controls.Switch("Power")
    .OnValue(EmojiName.GreenCircle, "ON")
    .Run();

Throws ArgumentNullException if value (or fallbacktext) is null.

---

OffValue

Two overloads set the label for the off (false) state.

ISwitchControl OffValue(string value)
ISwitchControl OffValue(EmojiName emojiName, string fallbacktext)

Overload	Meaning
OffValue(string)	Plain-text label for the off state. Cannot be null.
OffValue(EmojiName, string)	Emoji label, with fallbacktext used when the terminal cannot render emoji. fallbacktext cannot be null.

PromptPlus.Controls.Switch("Power")
    .OnValue(EmojiName.GreenCircle, "ON")
    .OffValue(EmojiName.RedCircle, "OFF")
    .Run();

Throws ArgumentNullException if value (or fallbacktext) is null.

---

History

EnableHistory

ISwitchControl EnableHistory(string filename, Action<IHistoryOptions>? options = null)

Persists the confirmed boolean to a file under filename so it can be reloaded as the default on the next run.

Parameter	Meaning
filename	A stable, unique key for this switch's history store. Cannot be null, empty, or whitespace.
options	Optional IHistoryOptions configuration (expiration, max items, and so on).

PromptPlus.Controls.Switch("Use default from history?")
    .Default(false, true)             // fall back to the last history value
    .EnableHistory("switch-history")
    .Run();

Throws ArgumentException if filename is empty or whitespace (ArgumentNullException if null).

💡 Pair Default(value, useDefaultHistory: true) with EnableHistory(...) to pre-load the last state the user confirmed. See Operations → History for runtime behavior.

---

Dynamic description

ChangeDescription

ISwitchControl ChangeDescription(Func<bool, string> value)

Recomputes the description line as the state changes. The callback receives the current boolean and returns the description to display.

PromptPlus.Controls.Switch("Notifications")
    .ChangeDescription(current => current
        ? "Notifications are enabled"
        : "Notifications are disabled")
    .Run();

Throws ArgumentNullException if value is null.

---

ChangeDescriptionAsync

ISwitchControl ChangeDescriptionAsync(Func<bool, Task<string>> value)

Asynchronous version of ChangeDescription, for a description sourced asynchronously.

PromptPlus.Controls.Switch("Telemetry")
    .ChangeDescriptionAsync(async current =>
    {
        await Task.Delay(1).ConfigureAwait(false);
        return current ? "Telemetry will be sent" : "Telemetry will stay local";
    })
    .Run();

Throws ArgumentNullException if value is null.

---

Appearance & behavior

Styles

ISwitchControl Styles(SwitchStyles 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 PromptPlusLibrary;
using ConsolePlusLibrary;   // Color, Style live here

PromptPlus.Controls.Switch("Use cache")
    .Styles(SwitchStyles.SwitchOn, new Style(Color.Black, Color.Darkgreen))
    .Styles(SwitchStyles.SwitchOff, new Style(Color.Black, Color.Darkred))
    .Run();

Throws ArgumentNullException if style is null.

---

Options

ISwitchControl Options(Action<IControlOptions> options)

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

PromptPlus.Controls.Switch("Verbose mode")
    .Options(opt =>
    {
        opt.Description("Toggle using Left/Right arrows or Space");
        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<bool?> Run(CancellationToken token = default)

Renders the toggle and blocks until the user confirms (Enter) or aborts (Esc). Returns a ResultPrompt<bool?> whose .Content is null when the prompt is cancelled.

Parameter	Meaning
token	A CancellationToken that cancels the prompt while it waits for input.

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
var result = PromptPlus.Controls.Switch("Cancelable switch").Run(cts.Token);

---

See also

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