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

Horizontally paged, drag-to-swipe row of items (typically MediaCard), with a snap-to-item animation and a page-dot indicator - Material's "carousel", e.g. a row of featured stations/genres. More...

#include <Carousel.h>

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

Public Types

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

Public Member Functions

 Carousel ()=default
 
 Carousel (Bounds bounds, int32_t itemWidth=140, int32_t gap=12)
 
void addItem (Widget< RGB_T > &item)
 
void setItemProvider (ItemCountFn count, ItemAtFn at)
 Switches to callback-driven items - see the class comment.
 
void setTheme (const MaterialTheme< RGB_T > &theme) override
 
Bounds itemRect (int index) const
 
int currentIndex () const
 
int pageCount () const
 
void setCurrentIndex (int index, bool animate=true)
 
bool isDraggable () const override
 
void draw (tinygpu::ISurface< RGB_T > &target) override
 
bool onGesture (const tinygpu::GestureEvent &event) override
 Handles one gesture event. Returns true if this widget consumed it.
 
bool update (uint32_t nowMs) override
 
- 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.
 

Public Attributes

std::function< void(int)> onPageChange
 
- Public Attributes inherited from Widget< RGB_T >
Bounds bounds
 
bool visible = true
 
bool enabled = true
 

Additional Inherited Members

- 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 Widget< RGB_T >
const MaterialTheme< RGB_T > * theme_ = nullptr
 

Detailed Description

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

Horizontally paged, drag-to-swipe row of items (typically MediaCard), with a snap-to-item animation and a page-dot indicator - Material's "carousel", e.g. a row of featured stations/genres.

Items are not owned by Carousel - same non-owning addItem() convention as Drawer/BottomSheet. Each item's bounds is authored in the carousel's own content space (see itemRect(), stacked left-to-right by itemWidth + gap, starting at x=0) rather than screen space - draw() temporarily shifts each item's bounds.x by the carousel's own position and current scroll offset before drawing it, then restores it, the same pattern Screen::draw() uses for its own vertically-scrolled content. onGesture() translates a tap's point the same way before forwarding it to whichever item it landed on.

Reports isDraggable() == true (like Slider) so a horizontal drag starting on the carousel is classified as GestureType::kDrag and latched to it for the drag's whole lifetime - see Screen:: isDraggableAt(). Releasing mid-drag snaps to the nearest item, animated over a few frames via update().

An item scrolled partway past the carousel's left/right edge is cropped to it (see ISurface::pushClipRect()), not drawn in full or skipped.

Alternative to addItem(): setItemProvider(count, at) switches to callback-driven items, for a station/genre list too large to keep every MediaCard resident at once - see Container.h's class comment for the same pattern. at(index)'s returned Widget has its bounds overwritten with itemRect(index) on every fetch (addItem() only does this once, since a vector-mode item's position never needs to change again).

Member Typedef Documentation

◆ ItemAtFn

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

◆ ItemCountFn

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

Constructor & Destructor Documentation

◆ Carousel() [1/2]

Carousel ( )
default

◆ Carousel() [2/2]

Carousel ( Bounds  bounds,
int32_t  itemWidth = 140,
int32_t  gap = 12 
)
inlineexplicit

Member Function Documentation

◆ addItem()

void addItem ( Widget< RGB_T > &  item)
inline

Positions item's own bounds (see class comment) and appends it. Ignored while an item provider is active - see setItemProvider().

◆ currentIndex()

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

Implements Widget< RGB_T >.

◆ isDraggable()

bool isDraggable ( ) const
inlineoverridevirtual

Whether a continuous drag starting inside this widget's bounds should be classified as GestureType::kDrag (see GestureDetector::isDraggable and Screen::isDraggableAt). Only Slider (and Carousel, for its own horizontal swipe) needs true.

Reimplemented from Widget< RGB_T >.

◆ itemRect()

Bounds itemRect ( int  index) const
inline

Suggested content-space rect for the index-th item - see class comment. Leaves room at the bottom for the page-dot indicator.

◆ onGesture()

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

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

Reimplemented from Widget< RGB_T >.

◆ pageCount()

int pageCount ( ) const
inline

◆ setCurrentIndex()

void setCurrentIndex ( int  index,
bool  animate = true 
)
inline

Pages to index, clamped to a valid item - animated (the same snap-glide update() uses after a drag release) unless animate is false.

◆ setItemProvider()

void setItemProvider ( ItemCountFn  count,
ItemAtFn  at 
)
inline

Switches to callback-driven items - see the class comment.

◆ setTheme()

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

Sets the theme this widget draws itself with - see theme(). Screen pushes its own theme into a widget at registration time (addWidget()/addFixedWidget()/presentDialog()) and again whenever Screen::setTheme() is called; container widgets (Dialog, Drawer) cascade this down to whatever children they already hold.

Reimplemented from Widget< RGB_T >.

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

Member Data Documentation

◆ onPageChange

std::function<void(int)> onPageChange

Fired whenever the settled current page changes - by drag-release snap or by setCurrentIndex().


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