Skip to content

methods.md

Latest commit

 

History

History
504 lines (355 loc) · 12.5 KB

methods.md

File metadata and controls

504 lines (355 loc) · 12.5 KB
Raw
PromptPlus

PromptPlus

ChartBar — Methods

NuGet License: MIT .NET

← Back to Home • Next: ChartBar — Operations →

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

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

Quick jump: AddItem · Interaction · Layout · BarType · Width · Title · Culture · FractionalDigits · MaxLengthLabel · OrderBy · ShowLegends · HideElements · PageSize · EnableLayoutSwitcher · EnableOrderingSwitcher · PredicateSelected · PredicateSelectedAsync · ChangeDescription · ChangeDescriptionAsync · Styles · Options · Run

Adding items

AddItem

IChartBarControl AddItem(string label, double value, Color? colorBar = null, string? id = null)

Adds one bar. label is required; value drives the bar length and percentage. colorBar sets the bar color — omit it and colors are auto-assigned in a rotating sequence. id is an optional identifier carried through to the returned ChartItem. When you omit id, a sequential id is generated from the insertion order ("0", "1", "2", …), so every item always has a stable, unique id you can match on in PredicateSelected.

using PromptPlusLibrary;
using ConsolePlusLibrary;   // Color lives here

PromptPlus.Controls.ChartBar("Select item")
    .AddItem("North", 120, Color.Green, id: "n")
    .AddItem("South", 80)   // auto color
    .Run();

Throws ArgumentException if label is null or empty.

There is no AddItems — add many bars with a loop or with Interaction.

Interaction

IChartBarControl Interaction<T>(IEnumerable<T> items, Action<T, IChartBarControl> interactionaction)

Iterates a source collection and lets you add bars programmatically — the equivalent of calling AddItem inside a loop.

PromptPlus.Controls.ChartBar("Select item")
    .Interaction(regions, (row, ctrl) => ctrl.AddItem(row.Name, row.Total))
    .Run();

Throws ArgumentNullException if items or interactionaction is null.

Chart layout & bars

Layout

IChartBarControl Layout(ChartBarLayout layout = ChartBarLayout.Standard)

Sets the initial layout.

ChartBarLayout Renders
Standard One horizontal bar per item, with its own label (default)
Stacked All items in a single continuous bar 
PromptPlus.Controls.ChartBar("Select item")
    .AddItem("CPU", 45).AddItem("Memory", 70).AddItem("Disk", 30)
    .Layout(ChartBarLayout.Stacked)
    .Run();

Switching to Stacked needs enough console width to render every item. If the console is too narrow the switch is silently prevented. Users can also toggle layout at runtime with F2 unless disabled — see EnableLayoutSwitcher.

BarType

IChartBarControl BarType(ChartBarType type = ChartBarType.Fill)

Chooses the glyph used to draw the bars.

ChartBarType Renders
Fill Solid filled bar using background color (default)
Light Light shade character (░)
Square Medium shade character (▪) 
PromptPlus.Controls.ChartBar("Select item")
    .BarType(ChartBarType.Light)
    .AddItem("Product 1", 55).AddItem("Product 2", 90)
    .Run();

Width

IChartBarControl Width(byte value)

Sets the drawing width of the chart in characters. Default is 80.

PromptPlus.Controls.ChartBar("Select item").Width(70).AddItem("A", 45).Run();

Throws ArgumentOutOfRangeException if value is less than 10.

Title

IChartBarControl Title(string title, TextAlignment alignment = TextAlignment.Center)

Adds a title line above the chart, aligned Left, Center (default), or Right.

PromptPlus.Controls.ChartBar("Select item")
    .Title("Sales by Region", TextAlignment.Center)
    .AddItem("North", 120).AddItem("South", 80)
    .Run();

Throws ArgumentException if title is null or empty. Hide an already-set title at runtime with HideElements(HideChart.Title).

Values & labels

Culture

IChartBarControl Culture(CultureInfo culture)
IChartBarControl Culture(string cultureName)

Sets the culture used to format numeric values. Defaults to the current PromptPlus culture.

PromptPlus.Controls.ChartBar("Select item")
    .Culture("en-US")
    .AddItem("A", 45.678)
    .Run();

The CultureInfo overload throws ArgumentNullException if culture is null; the string overload throws ArgumentException if cultureName is null or empty.

FractionalDigits

IChartBarControl FractionalDigits(byte value)

Number of fractional digits shown for values. Default is 2.

PromptPlus.Controls.ChartBar("Select item")
    .FractionalDigits(2)
    .AddItem("Value A", 45.678).AddItem("Value B", 82.123)
    .Run();

Throws ArgumentOutOfRangeException if value is greater than 5.

MaxLengthLabel

IChartBarControl MaxLengthLabel(byte value = 0)

Maximum number of characters shown for each label. 0 (default) shows labels in full with no truncation.

PromptPlus.Controls.ChartBar("Select item").MaxLengthLabel(12).AddItem("A really long label", 40).Run();

Ordering & legend

OrderBy

IChartBarControl OrderBy(ChartBarOrder order)

Sets the initial sort order of the bars.

ChartBarOrder Sorts by
None Insertion order (default)
Highest Value, descending (highest first)
Smallest Value, ascending (smallest first)
LabelAsc Label, A → Z
LabelDesc Label, Z → A 
PromptPlus.Controls.ChartBar("Select item")
    .AddItem("Low", 20).AddItem("High", 90).AddItem("Medium", 50)
    .OrderBy(ChartBarOrder.Highest)
    .Run();

Users can cycle the order at runtime with F4 unless disabled — see EnableOrderingSwitcher. The method is OrderBy (not Order).

ShowLegends

IChartBarControl ShowLegends(bool value = true)

Shows a legend section listing each item with its value and percentage after the chart. Default is false (hidden).

PromptPlus.Controls.ChartBar("Select item")
    .AddItem("Q1", 100).AddItem("Q2", 120)
    .ShowLegends()
    .Run();

Users can toggle the legend at runtime with F3. The method is ShowLegends (not ShowLegend).

Hiding & paging

HideElements

IChartBarControl HideElements(HideChart value)

Hides one or more chart elements. HideChart is a [Flags] enum, so combine values with |.

HideChart Hides
None Nothing (default — all elements shown)
Title The chart title
Values The numeric values on bars
Percentage The percentage values on bars 
PromptPlus.Controls.ChartBar("Select item")
    .AddItem("Data 1", 40).AddItem("Data 2", 75)
    .HideElements(HideChart.Title | HideChart.Percentage)
    .Run();

PageSize

IChartBarControl PageSize(byte value)

Maximum number of bars shown per page. Default 0 does not disable pagination — it auto-computes a page size that fits the terminal height instead of showing every item on one screen.

PromptPlus.Controls.ChartBar("Select item")
    .Interaction(manyRows, (r, c) => c.AddItem(r.Name, r.Value))
    .PageSize(10)
    .Run();

Runtime switchers

EnableLayoutSwitcher

IChartBarControl EnableLayoutSwitcher(bool value = true)

Enables or disables the F2 hotkey that toggles between Standard and Stacked layouts at runtime. Default enabled.

PromptPlus.Controls.ChartBar("Select item")
    .AddItem("A", 40).AddItem("B", 85)
    .EnableLayoutSwitcher(false)   // F2 no longer switches layout
    .Run();

EnableOrderingSwitcher

IChartBarControl EnableOrderingSwitcher(bool value = true)

Enables or disables the F4 hotkey that cycles through sort orders at runtime. Default enabled.

PromptPlus.Controls.ChartBar("Select item")
    .AddItem("Low", 20).AddItem("High", 90)
    .EnableOrderingSwitcher(false)   // F4 no longer cycles order
    .Run();

Validating the confirmed item

Validation runs on Enter. On failure the chart stays open and shows an error.

PredicateSelected

IChartBarControl PredicateSelected(Func<ChartItem, bool> validselect)
IChartBarControl PredicateSelected(Func<ChartItem, (bool, string?)> validselect)
Overload Return Behavior
Func<ChartItem, bool> true = valid Generic error on failure
Func<ChartItem, (bool, string?)> (isValid, message) Custom message on failure 
PromptPlus.Controls.ChartBar("Select item")
    .AddItem("Valid", 80).AddItem("Invalid", 30).AddItem("Valid", 60)
    .PredicateSelected(item => item.Value < 50
        ? (false, "Value must be >= 50")
        : (true, null))
    .Run();

Throws ArgumentNullException if validselect is null.

PredicateSelectedAsync

IChartBarControl PredicateSelectedAsync(Func<ChartItem, Task<bool>> validselect)
IChartBarControl PredicateSelectedAsync(Func<ChartItem, Task<(bool, string?)>> validselect)

Asynchronous counterparts.

⚠️ The async predicate is awaited synchronously (blocking) on the UI thread — keep it fast.

Dynamic description

ChangeDescription

IChartBarControl ChangeDescription(Func<ChartItem, string> value)

Recomputes the description from the currently highlighted item as the user navigates.

PromptPlus.Controls.ChartBar("Select item")
    .AddItem("Option 1", 55).AddItem("Option 2", 75)
    .ChangeDescription(item => $"Selected: {item.Label} ({item.Percent:F1}%)")
    .Run();

Throws ArgumentNullException if value is null.

ChangeDescriptionAsync

IChartBarControl ChangeDescriptionAsync(Func<ChartItem, Task<string>> value)

Asynchronous version of ChangeDescription, awaited synchronously each frame.

Appearance & behavior

Styles

IChartBarControl Styles(ChartBarStyles styleType, Style style)

Recolors one visual region of this control. See the region list and examples on the Styles page.

using PromptPlusLibrary;
using ConsolePlusLibrary;   // Color, Style live here
PromptPlus.Controls.ChartBar("Select item").AddItem("A", 40)
    .Styles(ChartBarStyles.ChartTitle, new Style(Color.Yellow, Color.Default))
    .Run();

Options

IChartBarControl Options(Action<IControlOptions> options)

Overrides global behaviors for this one control (prompt/description text, abort key, tooltip, hide-after-finish). See Global Behaviors → Per-Control Override.

Throws ArgumentNullException if options is null.

Running the control

Run

ResultPrompt<ChartItem?> Run(CancellationToken token = default)

Renders the chart and blocks until the user confirms (Enter) or aborts (Esc). Returns ResultPrompt<ChartItem?> carrying the highlighted ChartItem.

var result = PromptPlus.Controls.ChartBar("Select item").AddItem("A", 40).Run();

See also

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