Source code for pdwidgets.widgets.button
# SPDX-FileCopyrightText: 2024 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Button widget with optional icon and label."""
import events
from .._constants import ALIGN, ICON_SIZE, PAD, TEXT_SIZE, TEXT_WIDTH
from ..widget import Widget
from ._raised import fill_raised_round_rect, normalize_style, raised_face_colors
from .icon import Icon
from .label import Label
[docs]
class Button(Widget):
"""Clickable control with optional icon and text label."""
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=None,
padding=None,
radius=0,
pressed_offset=2,
pressed=False,
label=None,
text_color=None,
text_height=TEXT_SIZE.LARGE,
scale=1,
icon_file=None,
icon_color=None,
shadow=0,
style="flat",
bg_hi=None,
bg_lo=None,
rim=None,
backdrop=None,
):
"""
Initialize a Button widget to display an icon and/or text.
Args:
parent (Widget): The parent widget or screen that contains this widget.
x (int): The x-coordinate of the widget.
y (int): The y-coordinate of the widget.
w (int): The width of the widget.
h (int): The height of the widget.
align (int): The alignment of the widget.
align_to (Widget): The widget to align to.
fg (int): The foreground color of the widget.
bg (int): The background color of the widget.
visible (bool): The visibility of the widget (default is True).
value (Any): User-assigned value of the widget.
padding (tuple): The padding on each side of the widget.
radius (int): The corner radius of the widget (default is 0).
pressed_offset (int): The offset of the widget when pressed (default is 2).
pressed (bool): The state of the widget (default is False).
label (str): The text label of the widget.
text_color (int): The color of the text label.
text_height (int): The height of the text label (default is TEXT_SIZE.LARGE).
scale (int): Romfont scale factor passed to the label (default is 1).
icon_file (str): The icon file to display on the widget.
icon_color (int): The color of the icon.
shadow (int): Fake drop-shadow offset in pixels drawn behind the
button in ``color_theme.shadow`` (0 disables; the default).
style (str): ``\"flat\"`` (default solid fill + outline press) or
``\"raised\"`` (top-lit gradient + rim; press inverts lighting).
bg_hi (int): Optional raised highlight color; default shade of ``bg``.
bg_lo (int): Optional raised shade color; default shade of ``bg``.
rim (int): Optional raised rim stroke; default shade of ``bg``.
backdrop (int | None): When set, fill this button's axis-aligned
``area`` with ``backdrop`` before painting the face instead of
calling ``parent.draw(self.area)``. Use for raised round keys
that sit on a painted disc/chassis that is not the parent (same
role as filling a scratch buffer with the disc color before
blitting a circular key).
"""
self.pressed_offset = pressed_offset
self.shadow = shadow
self._style = normalize_style(style)
self._bg_hi = bg_hi
self._bg_lo = bg_lo
self._rim = rim
self._backdrop = backdrop
self._pressed = pressed
if w is None and label:
w = (len(label) + 1) * TEXT_WIDTH * scale + 2 * PAD
w = w or ICON_SIZE.LARGE + 2 * PAD
h = h or ICON_SIZE.LARGE + 2 * PAD
bg = bg if bg is not None else parent.color_theme.primary_variant
fg = fg if fg is not None else parent.color_theme.on_primary
super().__init__(
parent,
x,
y,
w,
h,
align,
align_to,
fg,
bg,
visible,
value,
padding,
radius=radius,
)
face_bg = parent.color_theme.transparent if self._style == "raised" else self.bg
if icon_file:
icon_align = ALIGN.CENTER if not label else ALIGN.LEFT
icon_color = (
icon_color if icon_color is not None else parent.color_theme.on_primary
)
self.icon = Icon(
self,
0,
0,
None,
None,
icon_align,
None,
icon_color,
face_bg,
True,
icon_file,
)
if label:
if text_height not in TEXT_SIZE:
raise ValueError("Text height must be 8, 14 or 16 pixels.")
label_align = ALIGN.CENTER if not icon_file else ALIGN.OUTER_RIGHT
label_align_to = self.icon if icon_file else self
text_color = (
text_color if text_color is not None else parent.color_theme.on_primary
)
self.label = Label(
self,
0,
0,
None,
None,
label_align,
label_align_to,
text_color,
face_bg,
True,
label,
None,
text_height,
scale,
)
else:
self.label = None
@property
def style(self):
"""Face style: ``\"flat\"`` or ``\"raised\"``."""
return self._style
def _register_callbacks(self):
self.add_event_cb(events.MOUSEBUTTONDOWN, self.press)
self.add_event_cb(events.MOUSEBUTTONUP, self.release)
def _draw_face(self, pressed=False):
pa = self.padded_area
if self._style == "raised":
pal = self.display.pal
hi, lo, rim = raised_face_colors(
self.bg, self._bg_hi, self._bg_lo, self._rim, pal=pal
)
fill_raised_round_rect(
self.display.framebuf,
pa.x,
pa.y,
pa.w,
pa.h,
self.radius,
hi,
lo,
rim,
pressed=pressed,
pal=pal,
)
return
if pressed and self.pressed_offset:
self.display.framebuf.round_rect(
pa.x + self.pressed_offset,
pa.y + self.pressed_offset,
pa.w,
pa.h,
self.radius,
self.bg,
f=True,
)
else:
self.display.framebuf.round_rect(*pa, self.radius, self.bg, f=True)
def _redraw_content(self):
"""Repaint face and visible children into the framebuffer (no flush)."""
self.draw()
for child in self.children:
if child.visible:
child.draw()
@property
def backdrop(self):
"""Clear color under the face, or ``None`` to erase via the parent."""
return self._backdrop
@backdrop.setter
def backdrop(self, value):
"""Set the clear color under the face, or ``None`` for parent erase.
Args:
value: Fill color for ``area`` before the face is painted, or
``None`` to call ``parent.draw(self.area)`` instead.
"""
self._backdrop = value
self.invalidate()
[docs]
def draw(self, _=None):
"""
Draw the button background and shape (with an optional drop shadow).
"""
if self._backdrop is not None:
# Match offscreen "fill then circle" (roku_graphics): corners of the
# AABB keep the disc/chassis color instead of the parent's fill.
self.display.framebuf.fill_rect(*self.area, self._backdrop)
else:
self.parent.draw(self.area)
pa = self.padded_area
if self.shadow and not self._pressed:
# Cheap fake drop shadow: a shape-colored round_rect offset behind
# the button. Two fills, no alpha blending.
self.display.framebuf.round_rect(
pa.x + self.shadow,
pa.y + self.shadow,
pa.w,
pa.h,
self.radius,
self.color_theme.shadow,
f=True,
)
self._draw_face(pressed=self._pressed)
[docs]
def press(self, data=None, event=None):
"""Mark pressed and dirty; flush via the display tick (not inline I80)."""
# Synchronous ``display.refresh`` from the input/service tick nested
# I80 blits under the soft timer and panicked the ESP32-S3 (HARD_RESET
# = ESP_RST_PANIC) when tapping raised roku_widgets keys.
self._pressed = True
self.invalidate()
[docs]
def release(self, data=None, event=None):
"""Clear pressed and dirty; flush via the display tick."""
self._pressed = False
self.invalidate()