celina/widgets/progress

Search:
Group by:

Progress bar widget for displaying task progress

This module provides progress bar widgets with customizable styles, labels, and visual representations.

Usage Example:

var progress = newProgressBar(0.0, "Processing")

# Update progress
progress.setValue(0.5)
progress.label = "Half complete"
let percentage = progress.getPercentageText()

Types

ProgressBar = ref object of Widget
  ## Current progress value (0.0 to 1.0)
  ## Optional label text
  ## Show percentage text
  ## Show progress bar visual
  ## Visual style
  ## Style for filled portion
  ## Style for unfilled portion
  ## Style for text/label
  ## Style for percentage text
  ## Character for filled portion (custom style)
  ## Character for empty portion (custom style)
  ## Character for partial fill (custom style)
  ## Minimum bar width
  ## Called when value changes
  ## Show brackets for Hash style [####--]
Progress bar widget 
ProgressStyle = enum
  Block,                    ## Block characters: ███░░░
  Line,                     ## Line characters: ━━━── or [━━━──]
  Arrow,                    ## Arrow style: ══════> or [═════>]
  Hash,                     ## Hash characters: ####-- or [####--]
  Custom                     ## Custom characters
Progress bar visual styles

Procs

proc backgroundStyle=(widget: ProgressBar; style: Style) {....raises: [], tags: [],
    forbids: [].}
Set the style for unfilled portion 
proc barStyle=(widget: ProgressBar; style: Style) {....raises: [], tags: [],
    forbids: [].}
Set the style for filled portion 
proc coloredProgressBar(value: float = 0.0; label: string = "";
                        color: Color = Green; style: ProgressStyle = Block): ProgressBar {.
    ...raises: [], tags: [], forbids: [].}
Create a progress bar with a specific color theme 
proc complete(widget: ProgressBar) {....raises: [Exception], tags: [RootEffect],
                                     forbids: [].}
Set progress to 100% 
proc decrement(widget: ProgressBar; amount: float = 0.01) {....raises: [Exception],
    tags: [RootEffect], forbids: [].}
Decrement the progress by a given amount 
proc downloadProgressBar(current, total: int64; label: string = "Downloading"): ProgressBar {.
    ...raises: [], tags: [], forbids: [].}
Create a progress bar for download tracking 
proc formatBytes(bytes: int64): string {....raises: [], tags: [], forbids: [].}
Format bytes as human-readable string (for download progress bars) 
proc formatTime(seconds: float): string {....raises: [], tags: [], forbids: [].}
Format seconds as human-readable time (for ETA display) 
proc getBackgroundStyle(widget: ProgressBar): Style {....raises: [], tags: [],
    forbids: [].}
Get the background style 
proc getLabelWithPercentage(widget: ProgressBar): string {....raises: [], tags: [],
    forbids: [].}
Get combined label and percentage text 
proc getPercentageText(widget: ProgressBar): string {....raises: [], tags: [],
    forbids: [].}
Get the formatted percentage text 
proc getProgressChars(widget: ProgressBar): tuple[filled, empty, partial: string] {.
    ...raises: [], tags: [], forbids: [].}
Get the characters to use for rendering based on style 
proc getValue(widget: ProgressBar): float {....raises: [], tags: [], forbids: [].}
Get the current progress value 
proc increment(widget: ProgressBar; amount: float = 0.01) {....raises: [Exception],
    tags: [RootEffect], forbids: [].}
Increment the progress by a given amount 
proc indeterminateProgressBar(label: string = "Loading..."): ProgressBar {.
    ...raises: [], tags: [], forbids: [].}
Create an indeterminate progress bar (for unknown duration tasks) Note: Animation would need to be handled externally by updating the value 
proc isComplete(widget: ProgressBar): bool {....raises: [], tags: [], forbids: [].}
Check if progress is at 100% 
proc label=(widget: ProgressBar; label: string) {....raises: [], tags: [],
    forbids: [].}
Set the label text 
proc minimalProgressBar(value: float = 0.0): ProgressBar {....raises: [], tags: [],
    forbids: [].}
Create a minimal progress bar (no label, just bar and percentage) 
proc minWidth=(widget: ProgressBar; width: int) {....raises: [], tags: [],
    forbids: [].}
Set the minimum bar width 
proc newProgressBar(value: float = 0.0; label: string = "";
                    showPercentage: bool = true; showBar: bool = true;
                    style: ProgressStyle = Block;
                    barStyle: Style = defaultStyle();
                    backgroundStyle: Style = style(BrightBlack, Reset);
                    textStyle: Style = defaultStyle();
                    percentageStyle: Style = style(Cyan, Reset);
                    filledChar: string = "█"; emptyChar: string = "░";
                    fillChar: string = "▒"; minWidth: int = 10;
                    onUpdate: proc (value: float) = nil;
                    showBrackets: bool = true): ProgressBar {....raises: [],
    tags: [], forbids: [].}
Create a new progress bar widget 
proc onUpdate=(widget: ProgressBar; callback: proc (value: float)) {....raises: [],
    tags: [], forbids: [].}
Set the update callback 
proc percentageStyle=(widget: ProgressBar; style: Style) {....raises: [], tags: [],
    forbids: [].}
Set the style for percentage text 
proc progressBar(value: float = 0.0; label: string = "";
                 showPercentage: bool = true; showBar: bool = true;
                 style: ProgressStyle = Block): ProgressBar {....raises: [],
    tags: [], forbids: [].}
Convenience constructor for progress bar with defaults 
proc reset(widget: ProgressBar) {....raises: [Exception], tags: [RootEffect],
                                  forbids: [].}
Reset progress to 0 
proc setColors(widget: ProgressBar; barStyle: Style = defaultStyle();
               backgroundStyle: Style = defaultStyle();
               textStyle: Style = defaultStyle();
               percentageStyle: Style = defaultStyle()) {....raises: [], tags: [],
    forbids: [].}
Set multiple colors at once 
proc setCustomChars(widget: ProgressBar; filled, empty, partial: string) {.
    ...raises: [], tags: [], forbids: [].}
Set custom characters for the progress bar 
proc setProgress(widget: ProgressBar; current, total: float) {.
    ...raises: [Exception], tags: [RootEffect], forbids: [].}
Set progress based on current and total values 
proc setValue(widget: ProgressBar; value: float) {....raises: [Exception],
    tags: [RootEffect], forbids: [].}
Set the progress value (0.0 to 1.0) 
proc showBar=(widget: ProgressBar; show: bool) {....raises: [], tags: [],
    forbids: [].}
Set whether to show the progress bar 
proc showBrackets=(widget: ProgressBar; show: bool) {....raises: [], tags: [],
    forbids: [].}
Set whether to show brackets for Hash style 
proc showPercentage=(widget: ProgressBar; show: bool) {....raises: [], tags: [],
    forbids: [].}
Set whether to show percentage 
proc simpleProgressBar(value: float = 0.0; label: string = ""): ProgressBar {.
    ...raises: [], tags: [], forbids: [].}
Create a simple progress bar with default styling 
proc style=(widget: ProgressBar; style: ProgressStyle) {....raises: [], tags: [],
    forbids: [].}
Set the visual style 
proc taskProgressBar(completed, total: int; label: string = "Progress"): ProgressBar {.
    ...raises: [], tags: [], forbids: [].}
Create a progress bar for task completion tracking 
proc textOnlyProgressBar(value: float = 0.0; label: string = ""): ProgressBar {.
    ...raises: [], tags: [], forbids: [].}
Create a text-only progress indicator (no bar visual) 
proc textStyle=(widget: ProgressBar; style: Style) {....raises: [], tags: [],
    forbids: [].}
Set the style for text/label 
proc withColors(widget: ProgressBar; barStyle: Style = defaultStyle();
                backgroundStyle: Style = defaultStyle();
                textStyle: Style = defaultStyle();
                percentageStyle: Style = defaultStyle()): ProgressBar {.
    ...raises: [], tags: [], forbids: [].}
Set colors and return self for chaining 
proc withCustomChars(widget: ProgressBar; filled, empty, partial: string): ProgressBar {.
    ...raises: [], tags: [], forbids: [].}
Set custom characters and return self for chaining 
proc withLabel(widget: ProgressBar; label: string): ProgressBar {....raises: [],
    tags: [], forbids: [].}
Set label and return self for chaining 
proc withMinWidth(widget: ProgressBar; minWidth: int): ProgressBar {....raises: [],
    tags: [], forbids: [].}
Set minimum width and return self for chaining 
proc withOnUpdate(widget: ProgressBar; callback: proc (value: float)): ProgressBar {.
    ...raises: [], tags: [], forbids: [].}
Set update callback and return self for chaining 
proc withShowBar(widget: ProgressBar; show: bool): ProgressBar {....raises: [],
    tags: [], forbids: [].}
Set bar display and return self for chaining 
proc withShowBrackets(widget: ProgressBar; show: bool): ProgressBar {.
    ...raises: [], tags: [], forbids: [].}
Set brackets display for Hash style and return self for chaining 
proc withShowPercentage(widget: ProgressBar; show: bool): ProgressBar {.
    ...raises: [], tags: [], forbids: [].}
Set percentage display and return self for chaining 
proc withStyle(widget: ProgressBar; style: ProgressStyle): ProgressBar {.
    ...raises: [], tags: [], forbids: [].}
Set style and return self for chaining 
proc withValue(widget: ProgressBar; value: float): ProgressBar {.
    ...raises: [Exception], tags: [RootEffect], forbids: [].}
Set value and return self for chaining

Methods

method getMinSize(widget: ProgressBar): Size {....raises: [], tags: [], forbids: [].}
Get minimum size for progress bar widget 
method getPreferredSize(widget: ProgressBar; available: Size): Size {.
    ...raises: [Exception], tags: [RootEffect], forbids: [].}
Get preferred size for progress bar widget 
method render(widget: ProgressBar; area: Rect; buf: var Buffer) {....raises: [],
    tags: [], forbids: [].}
Render the progress bar widget

Made with Nim. Generated: 2025-09-16 21:40:20 UTC