DrawableList
A container able to display many items using only a few drawables. This is done by only having drawables for visible items, and populating these drawables with new content when each of these become visible.
This means that all drawables must have an identical structure in some way, for example an Image or a Container with a button and a text.
Inherits from: Container, Drawable
Public Functions
DrawableList() | |
virtual bool | getCircular() const |
Gets the circular setting, previously set using setCircular(). | |
int16_t | getDrawableIndex(int16_t itemIndex, int16_t prevDrawableIndex =-1) const |
Gets the drawable index of an item. | |
int16_t | getDrawableIndices(int16_t itemIndex, int16_t * drawableIndexArray, int16_t arraySize) const |
Gets drawable indices. | |
virtual int16_t | getDrawableMargin() const |
Gets drawable margin. | |
virtual int16_t | getDrawableSize() const |
Gets drawable size as set by setDrawables. | |
virtual bool | getHorizontal() const |
Gets the orientation of the drawables, previously set using setHorizontal(). | |
int16_t | getItemIndex(int16_t drawableIndex) const |
Gets item stored in a given Drawable. | |
virtual int16_t | getItemSize() const |
Gets size of each item. | |
int16_t | getNumberOfDrawables() const |
Gets number of drawables based on the size of each item and the size of the widget. | |
int16_t | getNumberOfItems() const |
Gets number of items in the DrawableList, as previously set using setNumberOfItems(). | |
int32_t | getOffset() const |
Gets offset, as previously set using setOffset(). | |
int16_t | getRequiredNumberOfDrawables() const |
Gets required number of drawables. | |
void | itemChanged(int16_t itemIndex) |
Item changed. | |
void | refreshDrawables() |
Refresh drawables. | |
virtual void | setCircular(bool circular) |
Sets whether the list is circular (infinite) or not. | |
virtual void | setDrawables(DrawableListItemsInterface & drawableListItems, int16_t drawableItemIndexOffset, GenericCallback< DrawableListItemsInterface *, int16_t, int16_t > & updateDrawableCallback) |
Sets the drawables parameters. | |
void | setDrawableSize(int16_t drawableSize, int16_t drawableMargin) |
Sets drawables size. | |
virtual void | setHeight(int16_t height) |
Sets the height of this drawable. | |
virtual void | setHorizontal(bool horizontal) |
Sets a horizontal or vertical layout. | |
void | setNumberOfItems(int16_t numberOfItems) |
Sets number of items in the list. | |
void | setOffset(int32_t ofs) |
Sets virtual coordinate. | |
virtual void | setWidth(int16_t width) |
Sets the width of this drawable. | |
Additional inherited members
Public Functions inherited from Container
virtual void | add(Drawable & d) |
Adds a Drawable instance as child to this Container. | |
Container() | |
virtual bool | contains(const Drawable & d) |
Query if a given Drawable has been added directly to this Container. | |
virtual void | draw(const Rect & invalidatedArea) const |
Draw this drawable. | |
virtual void | forEachChild(GenericCallback< Drawable & > * function) |
Executes the specified callback function for each child in the Container. | |
virtual Drawable * | getFirstChild() |
Obtain a pointer to the first child of this container. | |
virtual void | getLastChild(int16_t x, int16_t y, Drawable ** last) |
Gets the last child in the list of children in this Container. | |
virtual Rect | getSolidRect() const |
Get (the largest possible) rectangle that is guaranteed to be solid (opaque). | |
virtual void | insert(Drawable * previous, Drawable & d) |
Inserts a Drawable after a specific child node. | |
virtual void | remove(Drawable & d) |
Removes a Drawable from the container by removing it from the linked list of children. | |
virtual void | removeAll() |
Removes all children in the Container by resetting their parent and sibling pointers. | |
virtual void | unlink() |
Removes all children by unlinking the first child. | |
Protected Functions inherited from Container
virtual Rect | getContainedArea() const |
Gets a rectangle describing the total area covered by the children of this container. | |
virtual void | moveChildrenRelative(int16_t deltaX, int16_t deltaY) |
Calls moveRelative on all children. | |
Protected Attributes inherited from Container
Drawable * | firstChild |
Pointer to the first child of this container. Subsequent children can be found through firstChild's nextSibling. | |
Public Functions inherited from Drawable
virtual void | childGeometryChanged() |
This function can be called on parent nodes to signal that the size or position of one or more of its children has changed. | |
virtual void | draw(const Rect & invalidatedArea) const =0 |
Draw this drawable. | |
Drawable() | |
Initializes a new instance of the Drawable class. | |
void | drawToDynamicBitmap(BitmapId id) |
Render the Drawable object into a dynamic bitmap. | |
Rect | getAbsoluteRect() const |
Helper function for obtaining the rectangle this Drawable covers, expressed in absolute coordinates. | |
virtual Drawable * | getFirstChild() |
Function for obtaining the first child of this drawable if any. | |
int16_t | getHeight() const |
Gets the height of this Drawable. | |
virtual void | getLastChild(int16_t x, int16_t y, Drawable ** last) =0 |
Function for obtaining the the last child of this drawable that intersects with the specified point. | |
Drawable * | getNextSibling() |
Gets the next sibling node. | |
Drawable * | getParent() const |
Returns the parent node. | |
const Rect & | getRect() const |
Gets the rectangle this Drawable covers, in coordinates relative to its parent. | |
virtual Rect | getSolidRect() const =0 |
Get (the largest possible) rectangle that is guaranteed to be solid (opaque). | |
virtual Rect | getSolidRectAbsolute() |
Helper function for obtaining the largest solid rect (as implemented by getSolidRect()) expressed in absolute coordinates. | |
virtual void | getVisibleRect(Rect & rect) const |
Function for finding the visible part of this drawable. | |
int16_t | getWidth() const |
Gets the width of this Drawable. | |
int16_t | getX() const |
Gets the x coordinate of this Drawable, relative to its parent. | |
int16_t | getY() const |
Gets the y coordinate of this Drawable, relative to its parent. | |
virtual void | handleClickEvent(const ClickEvent & event) |
Defines the event handler interface for ClickEvents. | |
virtual void | handleDragEvent(const DragEvent & event) |
Defines the event handler interface for DragEvents. | |
virtual void | handleGestureEvent(const GestureEvent & event) |
Defines the event handler interface for GestureEvents. | |
virtual void | handleTickEvent() |
Called periodically by the framework if the Drawable instance has subscribed to timer ticks. | |
virtual void | invalidate() const |
Tell the framework that this entire Drawable needs to be redrawn. | |
virtual void | invalidateRect(Rect & invalidatedArea) const |
Request that a region of this drawable is redrawn. | |
bool | isTouchable() const |
Gets whether this Drawable receives touch events or not. | |
bool | isVisible() const |
Gets whether this Drawable is visible. | |
virtual void | moveRelative(int16_t x, int16_t y) |
Moves the drawable. | |
virtual void | moveTo(int16_t x, int16_t y) |
Moves the drawable. | |
void | setPosition(const Drawable & drawable) |
Sets the position of the Drawable to the same as the given Drawable. | |
void | setPosition(int16_t x, int16_t y, int16_t width, int16_t height) |
Sets the size and position of this Drawable, relative to its parent. | |
void | setTouchable(bool touch) |
Controls whether this Drawable receives touch events or not. | |
void | setVisible(bool vis) |
Controls whether this Drawable should be visible. | |
void | setWidthHeight(const Bitmap & bitmap) |
Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates). | |
void | setWidthHeight(const Drawable & drawable) |
Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates). | |
void | setWidthHeight(const Rect & rect) |
Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates). | |
void | setWidthHeight(int16_t width, int16_t height) |
Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates). | |
virtual void | setX(int16_t x) |
Sets the x coordinate of this Drawable, relative to its parent. | |
void | setXY(const Drawable & drawable) |
Sets the x and y coordinates of this Drawable. | |
void | setXY(int16_t x, int16_t y) |
Sets the x and y coordinates of this Drawable, relative to its parent. | |
virtual void | setY(int16_t y) |
Sets the y coordinate of this Drawable, relative to its parent. | |
virtual void | translateRectToAbsolute(Rect & r) const |
Helper function for converting a region of this Drawable to absolute coordinates. | |
virtual | ~Drawable() |
Finalizes an instance of the Drawable class. | |
Protected Attributes inherited from Drawable
Drawable * | nextSibling |
Pointer to the next Drawable. | |
Drawable * | parent |
Pointer to this drawable's parent. | |
Rect | rect |
The coordinates of this Drawable, relative to its parent. | |
bool | touchable |
True if this drawable should receive touch events. | |
bool | visible |
True if this drawable should be drawn. | |
Public Functions Documentation
DrawableList
getCircular
virtual bool getCircular | ( | ) | const |
Gets the circular setting, previously set using setCircular().
True if the list is circular (infinite), false if the list is not circular (finite).
getDrawableIndex
int16_t getDrawableIndex | ( | int16_t | itemIndex , | const | |
int16_t | prevDrawableIndex =-1 | const | |||
) | const |
Gets the drawable index of an item.
If the number of items is smaller than the number of drawables and the DrawableList is circular, the same item can be in more than one drawable. In that case, calling this function again with the previously returned index as second parameter, the index of the next drawable containing the item will be returned.
itemIndex | Index of the item. |
prevDrawableIndex | (Optional) Index of the previous drawable. If given, search starts after this index. |
The first drawable index with the given item. Returns -1 if the item is not in a drawable.
getDrawableIndices
int16_t getDrawableIndices | ( | int16_t | itemIndex , | const | |
int16_t * | drawableIndexArray , | const | |||
int16_t | arraySize | const | |||
) | const |
Gets drawable indices.
Useful when the number of items is smaller than the number of drawables as the same item might be in more than one drawable on the screen (if the DrawableList is circular). The passed array will be filled with the drawable indices and the number of indices found is returned.
itemIndex | Zero-based index of the item. |
drawableIndexArray | Array where the drawable indices are stored. |
arraySize | Size of drawable array. |
The number of drawable indices found.
getDrawableMargin
virtual int16_t getDrawableMargin | ( | ) | const |
Gets drawable margin.
Gets drawable margin as set by setDrawables.
The drawable margin.
getDrawableSize
virtual int16_t getDrawableSize | ( | ) | const |
getHorizontal
virtual bool getHorizontal | ( | ) | const |
Gets the orientation of the drawables, previously set using setHorizontal().
True if it horizontal, false if it is vertical.
getItemIndex
int16_t getItemIndex | ( | int16_t | drawableIndex | ) | |
Gets item stored in a given Drawable.
drawableIndex | Zero-based index of the drawable. |
The item index.
getItemSize
virtual int16_t getItemSize | ( | ) | const |
Gets size of each item.
This equals the drawable size plus the drawable margin as set in setDrawables(). Equals getDrawableSize() + 2 * getDrawableMargin().
The item size.
Note
Not the same as getDrawableSize().
getNumberOfDrawables
int16_t getNumberOfDrawables | ( | ) | const |
Gets number of drawables based on the size of each item and the size of the widget.
The number of drawables.
getNumberOfItems
int16_t getNumberOfItems | ( | ) | const |
Gets number of items in the DrawableList, as previously set using setNumberOfItems().
The number of items.
getOffset
int32_t getOffset | ( | ) | const |
getRequiredNumberOfDrawables
int16_t getRequiredNumberOfDrawables | ( | ) | const |
Gets required number of drawables.
After setting up the DrawableList it is possible to request how many drawables are needed to ensure that the list can always be drawn properly. If the DrawableList has been setup with fewer Drawables than the required number of drawables, part of the lower part of the DrawableList will look wrong.
The number of required drawables depend on the size of the widget and the size of the drawables and the margin around drawables. If there are fewer drawables than required, the widget will not display correctly. If there are more drawables than required, some will be left unused.
The required number of drawables.
itemChanged
void itemChanged | ( | int16_t | itemIndex | ) | |
Item changed.
Item changed and drawables containing this item must be updated. This function can be called when an item has changed and needs to be updated on screen. If the given item is displayed on screen, possible more than once for cyclic lists, each drawable is request to refresh its content to reflect the new value.
itemIndex | Zero-based index of the item. |
refreshDrawables
void refreshDrawables | ( | ) |
Refresh drawables.
Useful to call if the number or items, their size or other properties have changed.
setCircular
virtual void setCircular | ( | bool | circular | ) | |
Sets whether the list is circular (infinite) or not.
A circular list is a list where the first drawable re-appears after the last item in the list - and the last item in the list appears before the first item in the list.
circular | True if the list should be circular, false if the list should not be circular. |
setDrawables
virtual void setDrawables | ( | DrawableListItemsInterface & | drawableListItems , | ||
int16_t | drawableItemIndexOffset , | ||||
GenericCallback< DrawableListItemsInterface *, int16_t, int16_t > & | updateDrawableCallback | ||||
) |
Sets the drawables parameters.
These parameters are
- The access class to the array of drawables
- The offset in the drawableListItems array to start using drawable and
- Callback to update the contents of a drawable.
drawableListItems | Number of drawables allocated. |
drawableItemIndexOffset | The offset of the drawable item. |
updateDrawableCallback | A callback to update the contents of a drawable. |
setDrawableSize
void setDrawableSize | ( | int16_t | drawableSize , | ||
int16_t | drawableMargin | ||||
) |
Sets drawables size.
The drawable is is the size of each drawable in the list in the set direction of the list (this is enforced by the DrawableList class). The specified margin is added above and below each item for spacing. The entire size of an item is thus size + 2 * spacing.
For a horizontal list each element will be drawableSize high and have the same width as set using setWidth(). For a vertical list each element will be drawableSize wide and have the same height as set using setHeight().
drawableSize | The size of the drawable. |
drawableMargin | The margin around drawables (margin before and margin after). |
setHeight
virtual void setHeight | ( | int16_t | height | ) | |
Sets the height of this drawable.
height | The new height. |
Note
For most Drawable widgets, changing this does normally not automatically yield a redraw.If the list is horizontal, the height is also propagated to all drawables in the list.
Reimplements: touchgfx::Drawable::setHeight
setHorizontal
virtual void setHorizontal | ( | bool | horizontal | ) | |
Sets a horizontal or vertical layout.
If parameter horizontal is set true, all drawables are arranged side by side. If horizontal is set false, the drawables are arranged above and below each other (vertically).
horizontal | True to align drawables horizontal, false to align drawables vertically. |
Note
Default value is false, i.e. vertical layout.
setNumberOfItems
void setNumberOfItems | ( | int16_t | numberOfItems | ) | |
Sets number of items in the list.
This forces all drawables to be updated to ensure that the content is correct.
numberOfItems | Number of items. |
Note
The DrawableList is refreshed to reflect the change.
setOffset
void setOffset | ( | int32_t | ofs | ) | |
Sets virtual coordinate.
Does not move to the given coordinate, but places the drawables and fill correct content into the drawables to give the impression that everything has been scrolled to the given coordinate.
Setting a value of 0 means that item 0 is at the start of the DrawableList. Setting a value of "-getItemSize()" places item 0 outside the start of the DrawableList and item 1 at the start of it.
Items that are completely outside of view, will be updated with new content using the provided callback from setDrawables(). Care is taken to not fill drawables more than strictly required.
ofs | The virtual coordinate. |
setWidth
virtual void setWidth | ( | int16_t | width | ) | |
Sets the width of this drawable.
width | The new width. |
Note
For most Drawable widgets, changing this does normally not automatically yield a redraw.If the list is vertical, the width is also propagated to all drawables in the list.
Reimplements: touchgfx::Drawable::setWidth