TinyMaterialDesign
Loading...
Searching...
No Matches
Widget.h
Go to the documentation of this file.
1#pragma once
2#include <stdint.h>
3
4#include "TinyGPU/Input/GestureDetector.h"
5#include "TinyGPU/Surface/ISurface.h"
7#include "TinyMaterialDesign/Core/Bounds.h"
8#include "TinyMaterialDesign/Theme/MaterialTheme.h"
9
10namespace tinymd {
11
12/// True for GestureType::kTap and also kDoubleTap - widgets that react to a
13/// plain tap should check this instead of comparing against kTap directly.
14///
15/// Why: GestureDetector reclassifies a tap as kDoubleTap whenever it lands
16/// within doubleTapMaxGapMs (350ms by default) of *any* previous tap, not
17/// just a second tap on the same widget - so quickly tapping one key then
18/// another on Keyboard (completely normal while typing) can turn the second
19/// one into a kDoubleTap. A widget that only matches kTap exactly then
20/// silently drops that keypress, which is exactly the "the Done key doesn't
21/// work reliably" symptom this fixes. None of these widgets give a tap and
22/// a double-tap different meaning, so treating both as "the user tapped me"
23/// is the correct behavior everywhere a plain tap is handled.
24inline bool isTapGesture(tinygpu::GestureType type) {
25 return type == tinygpu::GestureType::kTap || type == tinygpu::GestureType::kDoubleTap;
26}
27
28/// Darkens every pixel already drawn across `target`'s full extent, in
29/// place - the modal scrim look shared by Dialog and Drawer. Reads each
30/// pixel back and blends it 35% toward black, rather than painting a
31/// flat precomputed color over everything: this format has no alpha
32/// channel, so a flat fill would just erase whatever's actually behind
33/// the modal (the real screen content) instead of dimming it. Relies on
34/// `target` already holding that real content when called - true for
35/// Screen::draw()'s single-buffer pass (widgets are drawn before the
36/// modal), and for Screen::drawDirect()'s modal band loop once it draws
37/// the regular content into each band first (see drawModalDirect()).
38template <typename RGB_T>
40 const size_t w = target.width();
41 const size_t h = target.height();
42 for (size_t y = 0; y < h; ++y) {
43 for (size_t x = 0; x < w; ++x) {
44 target.setPixel(x, y, blend(target.getPixel(x, y), RGB_T(0, 0, 0), 0.35f));
45 }
46 }
47}
48
49/**
50 * @brief Base class every TinyMaterialDesign widget derives from.
51 *
52 * Widgets are plain templated objects the sketch owns (as globals or
53 * members, same non-owning-reference style TinyGPU itself uses) and
54 * registers with a Screen via Screen::addWidget(). Screen calls draw()/
55 * update()/onGesture() on the sketch's behalf each loop() iteration.
56 */
57template <typename RGB_T = TINYMD_DEFAULT_RGB_T>
58class Widget {
59 public:
60 virtual ~Widget() = default;
61
63 bool visible = true;
64 bool enabled = true;
65
66 /// Sets the theme this widget draws itself with - see theme(). Screen
67 /// pushes its own theme into a widget at registration time
68 /// (addWidget()/addFixedWidget()/presentDialog()) and again whenever
69 /// Screen::setTheme() is called; container widgets (Dialog, Drawer)
70 /// cascade this down to whatever children they already hold.
71 virtual void setTheme(const MaterialTheme<RGB_T>& theme) { theme_ = &theme; }
72
73 /// Renders the widget into `target` using colors/fonts/tokens from its
74 /// own theme (see theme()/setTheme()).
75 virtual void draw(tinygpu::ISurface<RGB_T>& target) = 0;
76
77 /// Handles one gesture event. Returns true if this widget consumed it.
78 virtual bool onGesture(const tinygpu::GestureEvent& event) {
79 (void)event;
80 return false;
81 }
82
83 /// Called once per frame, before draw(), to advance any time-based
84 /// animation (ripple fade, indeterminate progress sweep, ...). Returns
85 /// true if that advance changed anything this widget will draw
86 /// differently, so Screen can decide whether a redraw is actually needed -
87 /// see Screen::isDirty(). Default: no-op, not dirty, so widgets that
88 /// don't animate cost nothing extra.
89 virtual bool update(uint32_t nowMs) {
90 (void)nowMs;
91 return false;
92 }
93
94 /// Whether a continuous drag starting inside this widget's bounds should
95 /// be classified as GestureType::kDrag (see GestureDetector::isDraggable
96 /// and Screen::isDraggableAt). Only Slider (and Carousel, for its own
97 /// horizontal swipe) needs true.
98 virtual bool isDraggable() const { return false; }
99
100 /// Whether a drag starting at (x, y) - this widget's own coordinate
101 /// space - should be classified as GestureType::kDrag. Default: just
102 /// isDraggable(), ignoring the point - correct for any leaf widget. A
103 /// composite (Container, Dialog, Drawer, Menu, BottomSheet) overrides
104 /// this to recurse into whichever child sits at that point instead, so
105 /// e.g. a Slider nested inside one of them is still recognized
106 /// correctly by Screen::isDraggableAt().
107 virtual bool isDraggableAt(int32_t x, int32_t y) const {
108 (void)x;
109 (void)y;
110 return isDraggable();
111 }
112
113 /// Number of child widgets this one draws as part of itself, if any (0
114 /// by default) - a composite widget like Drawer overrides this + child()
115 /// to expose its items (Dialog its actions, etc.), so
116 /// Screen::drawDirect() can draw a presented modal's children
117 /// individually, each into its own small right-sized buffer, instead of
118 /// needing one buffer big enough for the whole modal - see
119 /// drawBackground().
120 virtual int childCount() const { return 0; }
121
122 /// The `index`-th child (see childCount()); never called with an
123 /// out-of-range index. Not owned by this widget any more than by
124 /// whatever added it (addItem()/addAction()/...).
125 virtual Widget<RGB_T>* child(int index) {
126 (void)index;
127 return nullptr;
128 }
129
130 /// Draws everything this widget owns *except* its children (see
131 /// childCount()) - e.g. Drawer's scrim + panel fill, without its list
132 /// items. Default: draws everything via draw() itself, which is exactly
133 /// right for a widget that doesn't override childCount() (its "children"
134 /// are however many it reports - zero - so nothing is skipped).
135 /// Screen::drawDirect() calls this instead of draw() for a presented
136 /// modal, then draws each child (if any) separately.
137 virtual void drawBackground(tinygpu::ISurface<RGB_T>& target) {
138 draw(target);
139 }
140
141 /// Lets a container (AppBar, chiefly) push its own background/foreground
142 /// color pair down onto a child it draws itself (leading/trailing), so
143 /// e.g. an IconButton in an app bar with a color override reads clearly
144 /// against it by default instead of staying on its own theme-wide
145 /// default (which is tuned to sit on theme.colors.surface, not
146 /// whatever color the app bar happens to be). Default: no-op, correct
147 /// for any widget with no notion of "ambient" vs. its own explicit
148 /// styling. IconButton overrides this as a fallback *only* used when it
149 /// has no explicit setColorOverride() of its own, so e.g. a record
150 /// button's active-red override still wins over the app bar's ambient
151 /// tint.
152 virtual void setThemeTint(RGB_T background, RGB_T foreground) {
153 (void)background;
154 (void)foreground;
155 }
156
157 /// Provides true if the widget is a container
158 virtual bool isContainer() const { return false; }
159
160 protected:
161 /// The theme this widget draws itself with - set via setTheme(), pushed
162 /// in by Screen at registration time. Never dereferenced before that -
163 /// every widget is registered with a Screen (which always has a theme,
164 /// default-constructed if nothing else) before its first draw().
165 const MaterialTheme<RGB_T>* theme_ = nullptr;
166
167 /// Convenience accessor for draw() overrides - see theme_.
168 const MaterialTheme<RGB_T>& theme() const { return *theme_; }
169};
170
171} // namespace tinymd
Base class every TinyMaterialDesign widget derives from.
Definition: Widget.h:58
virtual void setThemeTint(RGB_T background, RGB_T foreground)
Definition: Widget.h:152
Bounds bounds
Definition: Widget.h:62
const MaterialTheme< RGB_T > * theme_
Definition: Widget.h:165
virtual bool isDraggableAt(int32_t x, int32_t y) const
Definition: Widget.h:107
virtual void drawBackground(tinygpu::ISurface< RGB_T > &target)
Definition: Widget.h:137
virtual bool isDraggable() const
Definition: Widget.h:98
virtual bool onGesture(const tinygpu::GestureEvent &event)
Handles one gesture event. Returns true if this widget consumed it.
Definition: Widget.h:78
bool enabled
Definition: Widget.h:64
virtual Widget< RGB_T > * child(int index)
Definition: Widget.h:125
virtual void draw(tinygpu::ISurface< RGB_T > &target)=0
bool visible
Definition: Widget.h:63
virtual void setTheme(const MaterialTheme< RGB_T > &theme)
Definition: Widget.h:71
virtual bool isContainer() const
Provides true if the widget is a container.
Definition: Widget.h:158
virtual int childCount() const
Definition: Widget.h:120
const MaterialTheme< RGB_T > & theme() const
Convenience accessor for draw() overrides - see theme_.
Definition: Widget.h:168
virtual bool update(uint32_t nowMs)
Definition: Widget.h:89
virtual ~Widget()=default
Definition: AnchorLayout.h:4
void drawScrim(tinygpu::ISurface< RGB_T > &target)
Definition: Widget.h:39
bool isTapGesture(tinygpu::GestureType type)
Definition: Widget.h:24
Axis-aligned pixel rectangle used for widget bounds and hit-testing.
Definition: Bounds.h:21
Bundles a color scheme, shape tokens, typography, and spacing into one theme, passed to widgets so th...
Definition: MaterialTheme.h:50