TinyMaterialDesign
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | List of all members
Container< RGB_T > Class Template Reference

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>

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

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
 

Detailed Description

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

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.

Member Typedef Documentation

◆ ChildAtFn

using ChildAtFn = std::function<Widget<RGB_T>&(int index)>

◆ ChildCountFn

using ChildCountFn = std::function<int()>

Constructor & Destructor Documentation

◆ Container() [1/2]

Container ( )
default

◆ Container() [2/2]

Container ( Bounds  containerBounds)
inlineexplicit

Member Function Documentation

◆ addChild()

void addChild ( Widget< RGB_T > &  child)
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().

◆ child()

Widget< RGB_T > * child ( int  index)
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 >.

◆ childCount()

int childCount ( ) const
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 >.

◆ childrenCount()

int childrenCount ( ) const
inline

Number of children added with addChild().

◆ clampScroll()

void clampScroll ( )
inlineprotected

◆ clearChildren()

void clearChildren ( )
inline

Removes all children (they are not deleted) and scrolls to the top.

◆ contentHeight()

int32_t contentHeight ( ) const
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.

◆ 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()).

Implements Widget< RGB_T >.

Reimplemented in Screen< RGB_T >.

◆ drawBackground()

void drawBackground ( tinygpu::ISurface< RGB_T > &  target)
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 >.

◆ effectiveChild()

Widget< RGB_T > * effectiveChild ( int  index) const
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.

◆ effectiveCount()

int effectiveCount ( ) const
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.

◆ isContainer()

bool isContainer ( ) const
inlineoverridevirtual

Provides true if the widget is a container.

Reimplemented from Widget< RGB_T >.

◆ isContinuousType()

static bool isContinuousType ( tinygpu::GestureType  type)
inlinestatic

True for a gesture type that spans multiple events (kBegan/kChanged/ kEnded) rather than firing once - used by callers that compose a Container (Screen; Drawer/BottomSheet/Menu's own item area) to decide whether to route a gesture here at all before it's mid-flight.

◆ isDraggableAt()

bool isDraggableAt ( int32_t  x,
int32_t  y 
) const
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 >.

◆ isOnScrollbar()

bool isOnScrollbar ( int32_t  x,
int32_t  y 
) const
inlineprotected

True if (x, y) - same coordinate space as bounds - is inside the scrollbar touch zone (see kScrollbarTouchWidth) while the content overflows.

◆ onGesture()

bool onGesture ( const tinygpu::GestureEvent &  event)
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 >.

◆ removeChild()

bool removeChild ( Widget< RGB_T > &  child)
inline

Removes child (it is not deleted - the container does not own it).

Returns
false if it was not a child.

◆ scrollOffset()

int32_t scrollOffset ( ) const
inline

Current vertical scroll offset (0 = content's natural top).

◆ scrollThumbHeight()

int32_t scrollThumbHeight ( int32_t  content) const
inlineprotected

Height of the scrollbar thumb for content pixels of content (see contentHeight()). Shared by drawing and touch handling so both agree.

◆ scrollToChild()

void scrollToChild ( const Widget< RGB_T > &  child,
int32_t  margin = 4 
)
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.

◆ scrollToTrackY()

void scrollToTrackY ( int32_t  y)
inlineprotected

Scrolls so that the thumb is centered on track position y (same coordinate space as bounds).

◆ setChildProvider()

void setChildProvider ( ChildCountFn  count,
ChildAtFn  at 
)
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.

◆ setScrollOffset()

void setScrollOffset ( int32_t  offset)
inline

Scrolls the content by offset pixels (0 = top), limited to the content height.

◆ setTheme()

void setTheme ( const MaterialTheme< RGB_T > &  theme)
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 >.

◆ setUniformItemHeight()

void setUniformItemHeight ( int32_t  height)
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.

◆ update()

bool update ( uint32_t  nowMs)
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 >.

Member Data Documentation

◆ activeChild_

Widget<RGB_T>* activeChild_ = nullptr
protected

◆ childAtFn_

ChildAtFn childAtFn_
protected

◆ childCountFn_

ChildCountFn childCountFn_
protected

◆ children_

std::vector<Widget<RGB_T>*> children_
protected

◆ kScrollbarTouchWidth

constexpr int32_t kScrollbarTouchWidth = 12
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.

◆ scrollbarDragActive_

bool scrollbarDragActive_ = false
protected

A continuous gesture started on the scrollbar (see isOnScrollbar()).

◆ scrollDragActive_

bool scrollDragActive_ = false
protected

◆ scrollOffset_

int32_t scrollOffset_ = 0
protected

◆ uniformItemHeight_

int32_t uniformItemHeight_ = 0
protected

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