wijjit.elements.display.gauge.Gauge

class wijjit.elements.display.gauge.Gauge(id=None, classes=None, value=0, min_value=0, max_value=100, width=20, height=None, style='linear', show_value=True, show_minmax=False, show_ticks=False, color_mode='threshold', color_scale='green', thresholds=None, label=None, unit='', border_style='none', bind=True)[source]

Gauge element for value indicator visualization.

This element displays a value as a gauge with support for: - Linear (horizontal bar) style - Arc (semi-circular) style - Threshold-based coloring (green/yellow/red) - Gradient coloring - Optional tick marks and labels

Parameters:

id (str, optional) – Element identifier
classes (str or list of str, optional) – CSS class names for styling
value (float, optional) – Current value (default: 0)
min_value (float, optional) – Minimum value (default: 0)
max_value (float, optional) – Maximum value (default: 100)
width (int, optional) – Display width in columns (default: 20)
height (int, optional) – Display height in rows (default: 3 for linear, 5 for arc)
style (str, optional) – Gauge style: “linear”, “arc” (default: “linear”)
show_value (bool, optional) – Show current value text (default: True)
show_minmax (bool, optional) – Show min/max labels (default: False)
show_ticks (bool, optional) – Show tick marks (default: False)
color_mode (str, optional) – Color mode: “default”, “gradient”, “threshold” (default: “threshold”)
color_scale (str, optional) – Color scale for gradient mode (default: “green”)
thresholds (list of tuples, optional) – Custom thresholds: [(value_fraction, (r,g,b)), …]
label (str, optional) – Label text displayed above gauge (default: None)
unit (str, optional) – Unit suffix for value display (default: “”)
border_style (str, optional) – Border style drawn around the gauge: “none”, “single”, “double”, “rounded”, “heavy”, “ascii” (default: “none”). When a visible border is set, it is drawn within the element’s width/height and content is inset one cell on every side.
bind (bool | str)

Variables:

value (float) – Current value
min_value (float) – Minimum value
max_value (float) – Maximum value
width (int) – Display width
height (int) – Display height

Examples

Simple linear gauge:

>>> gauge = Gauge(value=75, max_value=100)

Arc gauge with label:

>>> gauge = Gauge(value=60, style="arc", label="CPU Usage", unit="%")

Custom thresholds:

>>> gauge = Gauge(value=50, thresholds=[
...     (0.5, (0, 200, 0)),    # Green up to 50%
...     (0.8, (200, 200, 0)),  # Yellow 50-80%
...     (1.0, (200, 0, 0))     # Red above 80%
... ])

__init__(id=None, classes=None, value=0, min_value=0, max_value=100, width=20, height=None, style='linear', show_value=True, show_minmax=False, show_ticks=False, color_mode='threshold', color_scale='green', thresholds=None, label=None, unit='', border_style='none', bind=True)[source]

Parameters:

id (str | None)
classes (str | list[str] | set[str] | None)
value (float)
min_value (float)
max_value (float)
width (int)
height (int | str | None)
style (Literal['linear', 'arc'])
show_value (bool)
show_minmax (bool)
show_ticks (bool)
color_mode (Literal['default', 'gradient', 'threshold'])
color_scale (str)
thresholds (list[tuple[float, tuple[int, int, int]]] | None)
label (str | None)
unit (str)
border_style (str)
bind (bool | str)

Return type:

None

Methods

`__init__`([id, classes, value, min_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 size of the gauge.
`get_normalized`()	Get current value normalized to 0-1 range.
`get_percentage`()	Get current value 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 gauge using cell-based rendering.
`restore_ephemeral_state`(state)	Restore ephemeral state after reconciliation.
`set_bounds`(bounds)	Set the element's screen bounds.
`set_value`(value)	Update gauge 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.
`parent_frame`	Get the parent Frame if this element is inside a scrollable frame.
`supports_dynamic_sizing`	Whether this element supports dynamic sizing.

set_value(value)[source]

Update gauge value.

Parameters:: value (float) – New value
Return type:: None

get_percentage()[source]

Get current value as percentage.

Returns:: Percentage (0-100)
Return type:: float

get_normalized()[source]

Get current value normalized to 0-1 range.

Returns:: Normalized value (0-1)
Return type:: float

get_intrinsic_size()[source]

Get the intrinsic size of the gauge.

Returns:: (width, height) in characters
Return type:: tuple of int

render_signature()[source]

Paint memo for the skip-unchanged fast path.

Captures the value and range (the normalized value/percentage is a pure function of those), the gauge style and dimensions, the value/minmax/ tick toggles, the coloring inputs (mode, scale, thresholds), the label and unit text, the border style, and the style-affecting state. See wijjit.elements.base.Element.render_signature().

Return type:: Any

render_to(ctx)[source]

Render the gauge using cell-based rendering.

Parameters:: ctx (PaintContext) – Paint context with buffer, style resolver, and bounds
Return type:: None

Notes

Theme styles:

This element uses the following theme style classes: - gauge: Base gauge style - gauge.fill: Filled portion style - gauge.empty: Empty portion style - gauge.label: Label text style - gauge.value: Value text style - gauge.border: Border style (when border is set)