Source code for pdwidgets.widgets.number_stepper

# SPDX-FileCopyrightText: 2024 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Numeric stepper widget."""

import events

from .._constants import ALIGN, ICON_SIZE, PAD
from .._themes import icon_theme
from ..widget import Widget
from .icon_button import IconButton
from .text_box import TextBox


[docs] class NumberStepper(Widget): """Bounded numeric stepper with ``-`` / ``+`` buttons.""" def __init__( # noqa: PLR0913 self, parent: Widget, x=0, y=0, w=None, h=None, align=None, align_to=None, fg=None, bg=None, visible=True, value=0, padding=None, step=1, minimum=None, maximum=None, number_format="{}", ): """ Initialize a NumberStepper: a ``-`` button, a value display and a ``+`` button for adjusting a bounded number. This generalizes the ad-hoc ``+``/``-`` `IconButton` pattern into a reusable widget. Pressing a button changes ``value`` by ``step``, clamped to ``[minimum, maximum]`` when those are given, and fires the change callback. Args: parent (Widget): The parent widget or screen that contains this stepper. x (int): The x-coordinate of the stepper. y (int): The y-coordinate of the stepper. w (int): The width of the stepper. h (int): The height of the stepper. align (int): The alignment of the stepper. align_to (Widget): The widget to align to. fg (int): The value-text color; defaults to ``on_surface``. bg (int): The background color; defaults to ``surface_variant``. visible (bool): The visibility of the stepper. value (int | float): The initial value (default 0). padding (tuple): The padding on each side of the stepper. step (int | float): Amount added/subtracted per press (default 1). minimum (int | float): Lower clamp bound, or ``None`` for unbounded. maximum (int | float): Upper clamp bound, or ``None`` for unbounded. number_format (str): ``str.format`` spec for the value display. Usage: temp = NumberStepper(card, value=20, minimum=15, maximum=30) temp.set_change_cb(lambda s: print("set", s.value)) """ h = h or ICON_SIZE.LARGE + 2 * PAD w = w or ICON_SIZE.LARGE * 4 bg = bg if bg is not None else parent.color_theme.surface_variant fg = fg if fg is not None else parent.color_theme.on_surface self.step = step self.minimum = minimum self.maximum = maximum self._number_format = number_format super().__init__(parent, x, y, w, h, align, align_to, fg, bg, visible, value, padding) btn_w = self.padded_area.h btn_h = self.padded_area.h self.neg_button = IconButton( self, w=btn_w, h=btn_h, align=ALIGN.LEFT, icon_file=icon_theme.remove(ICON_SIZE.SMALL), fg=parent.color_theme.on_primary, bg=parent.color_theme.primary_variant, ) self.pos_button = IconButton( self, w=btn_w, h=btn_h, align=ALIGN.RIGHT, icon_file=icon_theme.add(ICON_SIZE.SMALL), fg=parent.color_theme.on_primary, bg=parent.color_theme.primary_variant, ) self.box = TextBox( self, w=self.width - 2 * btn_w, align=ALIGN.CENTER, value=number_format.format(value), fg=fg, bg=bg, format="^", ) self.neg_button.add_event_cb(events.MOUSEBUTTONDOWN, lambda d, e: self._step(-1)) self.pos_button.add_event_cb(events.MOUSEBUTTONDOWN, lambda d, e: self._step(1)) def _step(self, direction): """Adjust the value by ``step`` in the given direction (+1 / -1).""" self.value = self._value + self.step * direction
[docs] def changed(self): """Clamp the value to the configured bounds and refresh the display.""" v = self._value if self.minimum is not None and v < self.minimum: v = self.minimum if self.maximum is not None and v > self.maximum: v = self.maximum self._value = v self.box.value = self._number_format.format(v) super().changed()