wijjit.elements.display.progress.ProgressBar

class wijjit.elements.display.progress.ProgressBar(id=None, classes=None, value=0, max_value=100, width=40, style='filled', bar_style='block', color=None, show_percentage=None, fill_char=None, empty_char=None, bind=True)

Progress bar element for displaying progress of operations.

This element provides a visual progress indicator with support for: - Multiple display styles (filled bar, percentage only, gradient, custom) - Multiple bar styles (block, thin, thick, equals, arrow, dots, ascii, etc.) - Optional coloring - Customizable fill and empty characters - Percentage display

Parameters:

• id (str, optional) – Element identifier

• value (float, optional) – Current progress value (default: 0)

• max_value (float, optional) – Maximum progress value (default: 100)

• width (int, optional) – Display width in columns (default: 40)

• style (str, optional) – Display style: “filled”, “percentage”, “gradient”, “custom” (default: “filled”)

• bar_style (str, optional) – Visual bar style preset: “block”, “thin”, “thick”, “equals”, “arrow”, “dots”, “ascii”, “hash”, “pipe”, “square” (default: “block”). Sets default fill_char and empty_char values.

• color (str, optional) – Color name for the progress bar (default: None)

• show_percentage (bool, optional) – Whether to show percentage text (default: True for filled/gradient, False for percentage style)

• fill_char (str, optional) – Character for filled portion. Overrides bar_style if specified.

• empty_char (str, optional) – Character for empty portion. Overrides bar_style if specified.

• classes (str | list[str] | set[str] | None)

• bind (bool | str)

Variables:

• value (float) – Current progress value

• max_value (float) – Maximum progress value

• width (int) – Display width

• style (str) – Display style

• bar_style (str) – Visual bar style preset

• color (str or None) – Color name

• show_percentage (bool) – Whether to show percentage

• fill_char (str) – Fill character

• empty_char (str) – Empty character

__init__(id=None, classes=None, value=0, max_value=100, width=40, style='filled', bar_style='block', color=None, show_percentage=None, fill_char=None, empty_char=None, bind=True)

Parameters:

• id (str | None)

• classes (str | list[str] | set[str] | None)

• value (float)

• max_value (float)

• width (int)

• style (Literal['filled', 'percentage', 'gradient', 'custom'])

• bar_style (Literal['block', 'thin', 'thick', 'equals', 'arrow', 'dots', 'ascii', 'hash', 'pipe', 'square'])

• color (str | None)

• show_percentage (bool | None)

• fill_char (str | None)

• empty_char (str | None)

• bind (bool | str)

Return type:

None

Methods

__init__([id, classes, value, max_value, ...])
add_class(class_name)	Add a CSS class to this element.
apply_props(props)	Apply props from a VNode, skipping ephemeral props.
get_ephemeral_state()	Get ephemeral state that should survive reconciliation.
get_hardware_cursor_position()	Absolute screen cell where the hardware terminal cursor should park.
get_height_for_width(width)	Return the height this element needs when laid out at width.
get_intrinsic_size()	Get the intrinsic (preferred) size of the element.
get_percentage()	Get current progress as percentage.
handle_key(key)	Handle a key press.
handle_mouse(event)	Handle a mouse event.
has_class(class_name)	Check if element has a CSS class.
on_blur()	Called when element loses focus.
on_focus()	Called when element gains focus.
on_hover_enter()	Called when mouse enters element.
on_hover_exit()	Called when mouse exits element.
on_mount()	Called when element is first added to the element tree.
on_unmount()	Called when element is removed from the element tree.
on_update(changed_props)	Called when element props are updated during reconciliation.
remove_class(class_name)	Remove a CSS class from this element.
render_signature()	Paint memo for the skip-unchanged fast path.
render_to(ctx)	Render the progress bar using cell-based rendering (NEW API).
restore_ephemeral_state(state)	Restore ephemeral state after reconciliation.
set_bounds(bounds)	Set the element's screen bounds.
set_progress(value)	Update progress value.
toggle_class(class_name)	Toggle a CSS class on this element.

Attributes

captures_tab	Whether this element wants the Tab key instead of focus movement.
max_value	Upper bound of the progress range.
parent_frame	Get the parent Frame if this element is inside a scrollable frame.
supports_dynamic_sizing	Whether this element supports dynamic sizing.

property max_value: float

Upper bound of the progress range.

set_progress(value)

Update progress value.

Parameters:

value (float) – New progress value

Return type:

None

get_percentage()

Get current progress as percentage.

Returns:

Progress percentage (0-100)

Return type:

float

render_signature()

Paint memo for the skip-unchanged fast path.

Captures the value and range (the percentage is a pure function of those), the display and bar characters, whether the percentage text is shown, and the style-affecting state. The color prop is not read by this cell-based render_to (coloring comes from theme styles). See wijjit.elements.base.Element.render_signature().

Return type:

Any

render_to(ctx)

Render the progress bar using cell-based rendering (NEW API).

Parameters:

ctx (PaintContext) – Paint context with buffer, style resolver, and bounds

Return type:

None

Notes

This is the new cell-based rendering method that uses theme styles instead of hardcoded ANSI colors. It supports all progress bar styles: filled, percentage, gradient, and custom.

Theme styles:

This element uses the following theme style classes: - progress: Base progress bar style - progress.fill: Filled portion style - progress.empty: Empty portion style - progress.text: Progress percentage text style - progress.gradient.low: Gradient color for 0-33% (gradient style only) - progress.gradient.medium: Gradient color for 33-66% (gradient style only) - progress.gradient.high: Gradient color for 66-100% (gradient style only)