|
TinyMaterialDesign
|
A widget that holds child widgets, draws/dispatches gestures to them, and scrolls its content vertically when it overflows its own bounds. More...
#include <Container.h>


Public Types | |
| using | ChildCountFn = std::function< int()> |
| using | ChildAtFn = std::function< Widget< RGB_T > &(int index)> |
Public Member Functions | |
| 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. | |
Static Public Member Functions | |
| static bool | isContinuousType (tinygpu::GestureType type) |
Static Public Attributes | |
| static constexpr int32_t | kScrollbarTouchWidth = 12 |
Protected Member Functions | |
| 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 | |
| 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 |
Additional Inherited Members | |
Public Attributes inherited from Widget< RGB_T > | |
| Bounds | bounds |
| bool | visible = true |
| bool | enabled = true |
A widget that holds child widgets, draws/dispatches gestures to them, and scrolls its content vertically when it overflows its own bounds.
This is the nestable counterpart to Screen (which does the same job once, for the one root every sketch already has) - unlike GridLayout/LinearLayout/ etc. (pure rect calculators consumed before construction), Container is a real Widget: it owns a child list, and since it's a Widget itself it can be added as a child of another Container, nesting arbitrarily deep.
Container<RGB565> panel(Bounds(16, 56, 288, 300)); panel.addChild(card1); panel.addChild(card2); // more content than panel.bounds.h -> scrolls screen.addWidget(panel);
Children are non-owning references (same convention as every other composite in this library - Dialog's actions, Drawer's items, ...) and are authored with absolute Bounds starting at/near this container's own bounds.y, exactly like Screen's own scrollable content: at scrollOffset 0 a child renders at its own authored position, and scrolling shifts that the same way Screen::draw() does.
Children partially or fully scrolled past this container's own bounds are cropped to it (see ISurface::pushClipRect()), not just skipped or drawn in full - matching Screen's own root-level clip.
Known limitation (shared with Screen - see its class comment): scrolling is vertical only, one axis.
Alternative to addChild(): setChildProvider(count, at) switches this container to callback-driven content, for lists too large to keep every item's Widget resident at once (thousands of rows) - count reports how many logical items there are, at(index) returns a reference to the Widget representing item index, typically a small pool of real Widgets reused/repositioned/relabeled for whichever indices are currently visible (the classic "recycler" pattern), rather than one Widget per item. Once a provider is set it takes over completely - addChild()'d children are ignored while one is active. Caution: a continuous gesture (drag/scroll) latches the Widget* returned by at() at kBegan and keeps calling methods on it through kChanged/kEnded - don't let the pool reassign that same slot to a different index while a gesture is still in progress.
| using ChildCountFn = std::function<int()> |
|
default |
|
inline |
Registers child as content of this container. Not owned - see the class comment. child may itself be a Container. Ignored while a child provider is active - see setChildProvider().
|
inlineoverridevirtual |
The index-th child (see childCount()); never called with an out-of-range index. Not owned by this widget any more than by whatever added it (addItem()/addAction()/...).
Reimplemented from Widget< RGB_T >.
|
inlineoverridevirtual |
Number of child widgets this one draws as part of itself, if any (0 by default) - a composite widget like Drawer overrides this + child() to expose its items (Dialog its actions, etc.), so Screen::drawDirect() can draw a presented modal's children individually, each into its own small right-sized buffer, instead of needing one buffer big enough for the whole modal - see drawBackground().
Reimplemented from Widget< RGB_T >.
|
inline |
Number of children added with addChild().
|
inlineprotected |
|
inline |
Removes all children (they are not deleted) and scrolls to the top.
|
inlineprotected |
Height of this container's content, measured from its own bounds.y - mirrors Screen::contentHeight() but relative to this container's own top rather than the whole surface. Protected: Screen reuses this directly for its own drawDirect()/drawScrollbarDirect(), since it's a Container itself and drives the same scroll math one layer further out. In provider mode this visits every logical index to find the tallest - still O(count) rather than O(memory), but a huge count makes this (and so every clampScroll() call, i.e. every frame) proportionally slower; keep item heights cheap to compute if count is large, or call setUniformItemHeight() for an O(1) alternative when rows are all the same height.
|
inlineoverridevirtual |
Renders the widget into target using colors/fonts/tokens from its own theme (see theme()/setTheme()).
Implements Widget< RGB_T >.
Reimplemented in Screen< RGB_T >.
|
inlineoverridevirtual |
Everything this container draws except its children - see Widget::drawBackground(). Just the scrollbar, since a Container has no chrome of its own.
Reimplemented from Widget< RGB_T >.
|
inlineprotected |
The child at index right now - from the provider if active (themed immediately, since there's no fixed set to cascade setTheme() to ahead of time - see setChildProvider()), else from the addChild()'d vector. Protected: Screen's drawDirect() drives the same loop one layer out.
|
inlineprotected |
Number of children right now - the provider's count() if setChildProvider() is active, else the addChild()'d vector's size. Protected: Screen's drawDirect() drives the same loop one layer out.
|
inlineoverridevirtual |
Provides true if the widget is a container.
Reimplemented from Widget< RGB_T >.
|
inlinestatic |
|
inlineoverridevirtual |
True if there's a child at (x, y) - this container's own coordinate space - that's draggable, recursing into it via its own isDraggableAt() if it's itself a composite (a nested Container, Dialog, ...) - see Widget::isDraggableAt(). Wire Screen:: isDraggableAt() (or, for a Container nested inside another, this same method on the outer one) to this so a drag starting on it, at any nesting depth, is classified correctly.
Reimplemented from Widget< RGB_T >.
Reimplemented in Screen< RGB_T >, and Screen< TINYMD_DEFAULT_RGB_T >.
|
inlineprotected |
True if (x, y) - same coordinate space as bounds - is inside the scrollbar touch zone (see kScrollbarTouchWidth) while the content overflows.
|
inlineoverridevirtual |
Handles one gesture event. Returns true if this widget consumed it.
Reimplemented from Widget< RGB_T >.
Reimplemented in Screen< RGB_T >, and Screen< TINYMD_DEFAULT_RGB_T >.
|
inline |
Removes child (it is not deleted - the container does not own it).
|
inline |
Current vertical scroll offset (0 = content's natural top).
|
inlineprotected |
Height of the scrollbar thumb for content pixels of content (see contentHeight()). Shared by drawing and touch handling so both agree.
|
inline |
Scrolls so that child is margin pixels below the top of the container (as far as the content height allows) - e.g. to keep a text field visible above an on-screen keyboard.
|
inlineprotected |
Scrolls so that the thumb is centered on track position y (same coordinate space as bounds).
|
inline |
Switches this container to callback-driven content - see the class comment. Pass empty functions (the default-constructed state) to switch back to addChild()'s stored-vector mode.
|
inline |
Scrolls the content by offset pixels (0 = top), limited to the content height.
|
inlineoverridevirtual |
Cascades the theme to every already-added child (vector mode). In provider mode, each Widget the provider hands back is themed at the point it's fetched instead (see effectiveChild()) - there's no fixed set of children to cascade to ahead of time.
Reimplemented from Widget< RGB_T >.
Reimplemented in Screen< RGB_T >.
|
inline |
Fast path for contentHeight(): when every item is exactly height tall (uniform-height rows, the common case for a huge provider-backed list), content height becomes effectiveCount() * height - an O(1) calculation - instead of fetching and measuring every single item every frame (see contentHeight()'s own doc comment on why that matters at large counts). Pass 0 (the default) to go back to measuring each item; irrelevant in addChild() vector mode, where items are typically few enough that measuring them all is already cheap.
|
inlineoverridevirtual |
Called once per frame, before draw(), to advance any time-based animation (ripple fade, indeterminate progress sweep, ...). Returns true if that advance changed anything this widget will draw differently, so Screen can decide whether a redraw is actually needed - see Screen::isDirty(). Default: no-op, not dirty, so widgets that don't animate cost nothing extra.
Reimplemented from Widget< RGB_T >.
Reimplemented in Screen< RGB_T >, and Screen< TINYMD_DEFAULT_RGB_T >.
|
protected |
|
protected |
|
protected |
|
protected |
|
staticconstexpr |
Width (in pixels, from the right edge) of the touch zone of the scrollbar - wider than the drawn bar so it is easy to hit with a finger. Tapping in it scrolls to the touched position, dragging in it moves the thumb with the finger. The zone only exists while the content overflows and takes priority over children below it, so keep interactive children this far from the right edge of a scrolling container.
|
protected |
A continuous gesture started on the scrollbar (see isOnScrollbar()).
|
protected |
|
protected |
|
protected |