TinyMaterialDesign
Loading...
Searching...
No Matches
Public Member Functions | List of all members
Screen< RGB_T > Class Template Reference

Owns a set of widgets, draws them, and routes gesture events to whichever one should handle each event - the one root Container every sketch has, plus what only a root needs: a second non-scrolling widget layer, modal dialog presentation, and actually writing to a display. More...

#include <Screen.h>

Inheritance diagram for Screen< RGB_T >:
Inheritance graph
[legend]
Collaboration diagram for Screen< RGB_T >:
Collaboration graph
[legend]

Public Member Functions

 Screen ()
 
 Screen (const MaterialTheme< RGB_T > &theme)
 
void addWidget (Widget< RGB_T > &widget)
 
void setContentProvider (typename Container< RGB_T >::ChildCountFn count, typename Container< RGB_T >::ChildAtFn at)
 
void addFixedWidget (Widget< RGB_T > &widget)
 
void setTheme (const MaterialTheme< RGB_T > &theme) override
 
const MaterialTheme< RGB_T > & theme () const
 
void setBackgroundColor (RGB_T color)
 
bool isDirty () const
 
void invalidate ()
 
void draw (tinygpu::ISurface< RGB_T > &target) override
 
void drawDirect (tinygpu::DisplayDriver< RGB_T > &driver, tinygpu::ISurface< RGB_T > &scratch, int32_t viewportWidth, int32_t viewportHeight)
 
bool update (uint32_t nowMs) override
 
bool isDraggableAt (int32_t x, int32_t y) const
 
void handleGesture (const tinygpu::GestureEvent &event)
 Wire this to GestureDetector::onGesture.
 
bool onGesture (const tinygpu::GestureEvent &event) override
 Handles one gesture event. Returns true if this widget consumed it.
 
void presentDialog (Widget< RGB_T > &dialog)
 
void dismissDialog ()
 
bool hasDialog () const
 True while a dialog (or menu, ...) is presented.
 
bool isDialogPresented () const
 
- Public Member Functions inherited from Container< RGB_T >
 Container ()=default
 
 Container (Bounds containerBounds)
 
void addChild (Widget< RGB_T > &child)
 
bool removeChild (Widget< RGB_T > &child)
 
void clearChildren ()
 Removes all children (they are not deleted) and scrolls to the top.
 
int childrenCount () const
 Number of children added with addChild().
 
void setScrollOffset (int32_t offset)
 
void scrollToChild (const Widget< RGB_T > &child, int32_t margin=4)
 
void setChildProvider (ChildCountFn count, ChildAtFn at)
 
void setUniformItemHeight (int32_t height)
 
void setTheme (const MaterialTheme< RGB_T > &theme) override
 
void draw (tinygpu::ISurface< RGB_T > &target) override
 
void drawBackground (tinygpu::ISurface< RGB_T > &target) override
 
bool update (uint32_t nowMs) override
 
bool onGesture (const tinygpu::GestureEvent &event) override
 Handles one gesture event. Returns true if this widget consumed it.
 
int childCount () const override
 
Widget< RGB_T > * child (int index) override
 
int32_t scrollOffset () const
 Current vertical scroll offset (0 = content's natural top).
 
bool isDraggableAt (int32_t x, int32_t y) const override
 
bool isContainer () const override
 Provides true if the widget is a container.
 
- Public Member Functions inherited from Widget< RGB_T >
virtual ~Widget ()=default
 
virtual void setTheme (const MaterialTheme< RGB_T > &theme)
 
virtual void draw (tinygpu::ISurface< RGB_T > &target)=0
 
virtual bool onGesture (const tinygpu::GestureEvent &event)
 Handles one gesture event. Returns true if this widget consumed it.
 
virtual bool update (uint32_t nowMs)
 
virtual bool isDraggable () const
 
virtual bool isDraggableAt (int32_t x, int32_t y) const
 
virtual int childCount () const
 
virtual Widget< RGB_T > * child (int index)
 
virtual void drawBackground (tinygpu::ISurface< RGB_T > &target)
 
virtual void setThemeTint (RGB_T background, RGB_T foreground)
 
virtual bool isContainer () const
 Provides true if the widget is a container.
 

Additional Inherited Members

- Public Types inherited from Container< RGB_T >
using ChildCountFn = std::function< int()>
 
using ChildAtFn = std::function< Widget< RGB_T > &(int index)>
 
- Static Public Member Functions inherited from Container< RGB_T >
static bool isContinuousType (tinygpu::GestureType type)
 
- Public Attributes inherited from Widget< RGB_T >
Bounds bounds
 
bool visible = true
 
bool enabled = true
 
- Static Public Attributes inherited from Container< RGB_T >
static constexpr int32_t kScrollbarTouchWidth = 12
 
- Protected Member Functions inherited from Container< RGB_T >
int32_t contentHeight () const
 
int32_t scrollThumbHeight (int32_t content) const
 
bool isOnScrollbar (int32_t x, int32_t y) const
 
void scrollToTrackY (int32_t y)
 
void clampScroll ()
 
int effectiveCount () const
 
Widget< RGB_T > * effectiveChild (int index) const
 
- Protected Member Functions inherited from Widget< RGB_T >
const MaterialTheme< RGB_T > & theme () const
 Convenience accessor for draw() overrides - see theme_.
 
- Protected Attributes inherited from Container< RGB_T >
std::vector< Widget< RGB_T > * > children_
 
ChildCountFn childCountFn_
 
ChildAtFn childAtFn_
 
int32_t uniformItemHeight_ = 0
 
Widget< RGB_T > * activeChild_ = nullptr
 
bool scrollDragActive_ = false
 
bool scrollbarDragActive_ = false
 A continuous gesture started on the scrollbar (see isOnScrollbar()).
 
int32_t scrollOffset_ = 0
 
- Protected Attributes inherited from Widget< RGB_T >
const MaterialTheme< RGB_T > * theme_ = nullptr
 

Detailed Description

template<typename RGB_T = TINYMD_DEFAULT_RGB_T>
class tinymd::Screen< RGB_T >

Owns a set of widgets, draws them, and routes gesture events to whichever one should handle each event - the one root Container every sketch has, plus what only a root needs: a second non-scrolling widget layer, modal dialog presentation, and actually writing to a display.

Screen does not own the widgets (the sketch does, typically as globals - the same non-owning-reference composition TinyGPU itself uses everywhere, e.g. DeviceOutput(driver&)). Usage, mirroring TinyGPU's own examples:

Screen<RGB565> screen(theme); Button<RGB565> okButton(...); screen.addWidget(okButton);

GestureDetector gestures; gestures.onGesture = [](GestureEvent& e) { screen.handleGesture(e); }; gestures.isDraggable = [](int16_t x, int16_t y) { return screen.isDraggableAt(x, y); };

void loop() { gestures.update(touchDriver); screen.update(millis()); if (screen.isDirty()) { // see isDirty() - skips the (slow) screen.draw(surface); // redraw + display write when display.writeData(surface); // nothing changed this frame } }

Vertical scrolling: widgets added via addWidget() are Container's own children (see Container.h) - laid out in one "content" coordinate space that can be taller than the surface passed to draw() - if it is, dragging up/down over any non-interactive spot (an empty gap, a Label, a Card, ...) scrolls that content, the same gesture TouchDriver/GestureDetector already classify as kScroll/kPan. Widgets that should stay put while the content behind them scrolls - a top AppBar, a bottom Keyboard - go through addFixedWidget() instead; they're always drawn and hit-tested on top of the scrollable content, at their own authored (screen-space) bounds. If everything already fits within the drawn surface, scrolling never engages (offset stays 0), no scrollbar is drawn, and existing sketches that only call addWidget() are unaffected. A thin scrollbar on the right edge appears automatically whenever there's something to scroll - see Container::draw().

Since Screen is a Container (its scrollable content is just Container's own child list), an addWidget()'d widget can itself be a Container - nesting a smaller scrollable panel inside the one root scrollable area. See Container.h for that case's own scroll/gesture behavior and limitations (which Screen shares for its own content, listed below).

A widget that straddles the viewport's top/bottom edge while scrolled partway off it is cropped to the viewport (see ISurface::pushClipRect(), used the same way Container.h uses it for its own children) rather than rendered pinned to y=0 at full size or skipped outright.

Constructor & Destructor Documentation

◆ Screen() [1/2]

Screen ( )
inline

◆ Screen() [2/2]

Screen ( const MaterialTheme< RGB_T > &  theme)
inlineexplicit

Constructs a Screen that starts with theme already set - pushed into every widget registered afterward (see setTheme()).

Member Function Documentation

◆ addFixedWidget()

void addFixedWidget ( Widget< RGB_T > &  widget)
inline

Registers widget pinned to its authored bounds regardless of scrolling - e.g. a top AppBar or bottom Keyboard. Always drawn and hit-tested on top of every scrollable widget.

◆ addWidget()

void addWidget ( Widget< RGB_T > &  widget)
inline

Registers widget as scrollable content (see the class comment) - Screen's own name for Container::addChild().

◆ dismissDialog()

void dismissDialog ( )
inline

◆ draw()

void draw ( tinygpu::ISurface< RGB_T > &  target)
inlineoverridevirtual

Renders the widget into target using colors/fonts/tokens from its own theme (see theme()/setTheme()).

Reimplemented from Container< RGB_T >.

◆ drawDirect()

void drawDirect ( tinygpu::DisplayDriver< RGB_T > &  driver,
tinygpu::ISurface< RGB_T > &  scratch,
int32_t  viewportWidth,
int32_t  viewportHeight 
)
inline

Renders the full layout straight to driver without ever needing a full-screen framebuffer - for boards that can't spare a single contiguous allocation the size of the whole screen (e.g. classic ESP32 without PSRAM: a 240x320 RGB565 buffer is 153,600 bytes, which can exceed the largest free block even with plenty of total free heap, since the heap ends up split into multiple smaller regions).

Each visible widget - scrollable or fixed, skipping anything invisible or entirely outside the viewport (including scrolled off it), same idea as content that's never drawn today - gets scratch resized to exactly its own bounds, is drawn into it once, and is blitted directly to the panel at its own position: genuinely one small buffer and one write per control, not a shared full-screen (or full-band) one. scratch is one small, reused, real (non-owning, already-begin()'d) surface - since Surface::resize() only reallocates when growing past its current capacity, repeatedly resizing it this way settles down to zero reallocation once it's been sized to the largest single widget this layout ever draws.

The one case that can't work this way is a presented modal (Dialog/Drawer): its scrim always covers the full viewport regardless of the modal's own bounds (see Dialog.h/Drawer.h), and it can itself span most of the screen (a full-height Drawer) - both too much for one small per-widget buffer. So while a modal is presented, everything else is skipped outright (it would just be fully occluded) and only the modal is drawn: its drawBackground() (see Widget.h) - scrim plus whatever chrome isn't one of its children - one short horizontal strip at a time via a WindowedSurface (see that class) that reports the full viewport size for the scrim's own math but clips actual pixel writes to the current strip, followed by each of its children (see childCount()/child()) individually via the same per-widget path as everything else - e.g. Drawer's own list items, each drawn once rather than redrawn on every strip. A modal type that doesn't override drawBackground()/childCount() (Dialog, as yet) falls back to the default drawBackground() = draw() and childCount() = 0, i.e. its entire contents (chrome + actions) drawn banded, same as before.

This is an alternative to draw()+writeData(surface) (unaffected by this method's existence) - pick whichever fits your board.

◆ handleGesture()

void handleGesture ( const tinygpu::GestureEvent &  event)
inline

Wire this to GestureDetector::onGesture.

◆ hasDialog()

bool hasDialog ( ) const
inline

True while a dialog (or menu, ...) is presented.

◆ invalidate()

void invalidate ( )
inline

Forces the next isDirty() to be true / the next draw() to run, for widget state changed from outside a gesture or update() callback - see isDirty().

◆ isDialogPresented()

bool isDialogPresented ( ) const
inline

◆ isDirty()

bool isDirty ( ) const
inline

True if draw() would paint something different than last time - see invalidate(). A typical loop() should skip draw()/writeData() while this is false:

screen.update(millis()); if (screen.isDirty()) { screen.draw(surface); display.writeData(surface); }

Starts true so the first frame always draws. Set whenever a gesture reaches handleGesture() (tap/drag/scroll - covers ripple starts, toggles, slider drags, and anything a click/change callback does to this or any other widget, since those callbacks run synchronously during dispatch) or when update() advances a time-based animation (ripple fade, indeterminate progress sweep, cursor blink). Cleared once draw() has run.

This is a coarse, screen-wide flag, not per-widget dirty rects - one changed widget still repaints the whole screen. It also can't see state a sketch mutates directly on a widget from outside a gesture/ update callback (e.g. a Label updated from a sensor reading in loop()) - call invalidate() explicitly after changes like that.

◆ isDraggableAt()

bool isDraggableAt ( int32_t  x,
int32_t  y 
) const
inlinevirtual

Wire this to GestureDetector::isDraggable so a drag starting on a draggable widget (currently only Slider) is classified as kDrag instead of kPan/kScroll - recurses into nested composites (Container, Dialog, Drawer, Menu, BottomSheet) via their own isDraggableAt(), so a Slider at any nesting depth is still recognized correctly.

Reimplemented from Container< RGB_T >.

◆ onGesture()

bool onGesture ( const tinygpu::GestureEvent &  event)
inlineoverridevirtual

Handles one gesture event. Returns true if this widget consumed it.

Reimplemented from Container< RGB_T >.

◆ presentDialog()

void presentDialog ( Widget< RGB_T > &  dialog)
inline

Shows dialog modally: it receives every gesture and is drawn on top until dismissDialog() is called (typically from one of the dialog's own action-button callbacks).

◆ setBackgroundColor()

void setBackgroundColor ( RGB_T  color)
inline

Overrides the theme's background color for this screen. Not required - draw() falls back to theme_.colors.background.

◆ setContentProvider()

void setContentProvider ( typename Container< RGB_T >::ChildCountFn  count,
typename Container< RGB_T >::ChildAtFn  at 
)
inline

Switches the scrollable content to callback-driven mode - Screen's own name for Container::setChildProvider(), for lists too large to keep every item's Widget resident at once. See Container.h's class comment.

◆ setTheme()

void setTheme ( const MaterialTheme< RGB_T > &  theme)
inlineoverridevirtual

Replaces the screen's theme and pushes it into every widget already registered (scrollable, fixed, and a presented dialog if any). Widgets registered later (addWidget()/addFixedWidget()/ presentDialog()) pick up whatever theme is current at that time.

Reimplemented from Container< RGB_T >.

◆ theme()

const MaterialTheme< RGB_T > & theme ( ) const
inline

The theme currently in effect - see setTheme(). Public (unlike Widget's own protected theme()) since a sketch often wants to read a color role directly (e.g. to pass to a widget's own setColorOverride()) without keeping a second copy of the theme alongside the Screen.

◆ update()

bool update ( uint32_t  nowMs)
inlineoverridevirtual

Advances any time-based widget animation. Call once per loop(), before checking isDirty().

Reimplemented from Container< RGB_T >.


The documentation for this class was generated from the following file: