Skip to main content
Version: 4.16

ScrollableContainer

A ScrollableContainer is a container that allows its contents to be scrolled. It will intercept drag operations and move child nodes accordingly.

A standard Container will simply clip children that are either larger than the container itself, or children that extend beyond the borders of the container or children that are placed outside the borders of the container. A ScrollableContainer behaves much like a Container, except it enables the user to scroll the children and thereby act like a viewport. When the contents of the ScrollableContainer is scrollable, scrollbars can be seen near the edge of the ScrollableContainer.

See: Container

Note: The ScrollableContainer will consume all DragEvents in the area covered by the container.

Inherits from: Container, Drawable

Public Functions#

virtual voidadd(Drawable & d)
Adds a Drawable instance as child to this Container.
virtual voidchildGeometryChanged()
Used to signal that the size or position of one or more children have changed.
voidenableHorizontalScroll(bool enable)
Enables horizontal scrolling.
voidenableVerticalScroll(bool enable)
Enables vertical scrolling.
virtual RectgetContainedArea() const
Gets the area that contains all children added to the ScrollableContainer.
virtual voidgetLastChild(int16_t x, int16_t y, Drawable ** last)
Gets the last child in the list of children in this Container.
uint16_tgetScrollDurationSlowdown() const
Gets scroll duration speedup divisor.
uint16_tgetScrollDurationSpeedup() const
Gets scroll duration speedup multiplier.
int16_tgetScrolledX() const
Gets the distance scrolled for the x-axis.
int16_tgetScrolledY() const
Gets the distance scrolled for the y-axis.
virtual voidhandleClickEvent(const ClickEvent & evt)
Defines the event handler interface for ClickEvents.
virtual voidhandleDragEvent(const DragEvent & evt)
Defines the event handler interface for DragEvents.
virtual voidhandleGestureEvent(const GestureEvent & evt)
Defines the event handler interface for GestureEvents.
virtual voidhandleTickEvent()
Called periodically by the framework if the Drawable instance has subscribed to timer ticks.
virtual voidisScrollableXY(bool & scrollX, bool & scrollY)
Is the ClickableContainer scrollable in either direction? Takes the width of the contained elements into account and also checks to see if horizontal or vertical scrolling is allowed.
virtual voidmoveChildrenRelative(int16_t deltaX, int16_t deltaY)
Calls moveRelative on all children.
voidreset()
Resets the ScrollableContainer to its original state, before the user started dragging the contents.
ScrollableContainer()
voidsetMaxVelocity(uint16_t max)
Sets the maximum velocity of a scroll due to a swipe.
voidsetScrollbarPadding(uint8_t padding)
Sets the amount of space between the scrollbar and the edge of the ScrollableContainer.
voidsetScrollbarsAlpha(uint8_t alpha)
Sets the alpha value (transparency) of the scrollbars.
voidsetScrollbarsColor(colortype color)
Sets the color of the scrollbars.
voidsetScrollbarsPermanentlyVisible(bool permanentlyVisible =true)
Make scrollbars permanently visible regardless of the size and position of the children of the ScrollableContainer.
voidsetScrollbarsVisible(bool newVisible)
Sets the visibility of the scrollbars, when the scrollable area is pressed.
voidsetScrollbarWidth(uint8_t width)
Sets the width of the scrollbar measured in pixels.
voidsetScrollDurationSlowdown(uint16_t slowdown)
Sets scroll duration speedup divisor.
voidsetScrollDurationSpeedup(uint16_t speedup)
Sets scroll duration speedup multiplier.
voidsetScrollThreshold(int16_t t)
Change the threshold which the first drag event received must exceed before initiating a scroll.

Protected Functions#

virtual booldoScroll(int16_t deltaX, int16_t deltaY)
Method to actually scroll the container.
RectgetXBorder(const Rect & xBar, const Rect & yBar) const
Gets the area where the horizontal scrollbar can move.
RectgetXScrollbar() const
Gets x coordinate of the scrollbar.
RectgetYBorder(const Rect & xBar, const Rect & yBar) const
Gets the area where the vertical scrollbar can move.
RectgetYScrollbar() const
Gets y coordinate of the scrollbar.
voidinvalidateScrollbars()
Invalidate the scrollbars.

Protected Attributes#

GestureEvent::GestureEventTypeaccelDirection
The current direction (horizontal or vertical) of scroll.
boolanimate
Is scroll animation currently active.
uint16_tanimationCounter
Current step/tick in scroll animation.
int16_tbeginningValue
Initial X or Y for calculated values in scroll animation.
int16_tfingerAdjustmentX
How much should the finger be adjusted horizontally.
int16_tfingerAdjustmentY
and how much vertically
boolhasIssuedCancelEvent
true if the pressed drawable has received cancel event
boolisPressed
Is the container currently pressed (maybe show scrollbars)
boolisScrolling
Is the container scrolling (i.e. has overcome the initial larger drag that is required to initiate a scroll).
Drawable *lastDraggableChild
The drawable child of this container which should receive drag events. Note that only drag events in directions which cannot be scrolled by this ScrollableContainer will be forwarded to children.
uint16_tmaxVelocity
The maximum velocity of a scroll (due to a swipe)
Drawable *pressedDrawable
The drawable child of this container which received the last ClickEvent::PRESSED notification. When scrolling, send this drawable a CANCEL event if the new x/y coords no longer matches this drawable.
int16_tpressedX
The x coordinate where the last ClickEvent::PRESSED was received.
int16_tpressedY
The y coordinate where the last ClickEvent::PRESSED was received.
boolscrollableX
Is the container scrollable in the horizontal direction.
boolscrollableY
Is the container scrollable in the vertical direction.
uint8_tscrollbarAlpha
The scrollbar is semitransparent.
colortypescrollbarColor
The color of the scrollbar.
uint8_tscrollbarPadding
The amount of padding. The scrollbar will have a bit of space to the borders of the container.
boolscrollbarsPermanentlyVisible
Are scrollbars always visible.
boolscrollbarsVisible
Are scrollbars visible.
uint8_tscrollbarWidth
The width of the scrollbar.
uint16_tscrollDuration
Number of ticks the scroll animation should use.
uint16_tscrollDurationSlowdown
The scroll durations is divided by this number.
uint16_tscrollDurationSpeedup
The scroll durations is multipled by this number.
int16_tscrolledXDistance
The scrolled horizontal distance.
int16_tscrolledYDistance
The scrolled vertical distance.
int16_tscrollThreshold
The threshold which the first drag event received must exceed before scrolling. Default is 5.
int16_ttargetValue
Target X or Y value for scroll animation.
BoxxSlider
The horizontal scrollbar drawable.
BoxySlider
The vertical scrollbar drawable.
const uint8_tSCROLLBAR_LINE
The scrollbar line.
const uint16_tSCROLLBAR_MAX_VELOCITY
The (default) maximum velocity of a scroll due to a swipe.
const uint16_tSCROLLBAR_MIN_VELOCITY
The minimum velocity of a scroll due to a swipe.

Additional inherited members#

Public Functions inherited from Container#

Container()
virtual boolcontains(const Drawable & d)
Query if a given Drawable has been added directly to this Container.
virtual voiddraw(const Rect & invalidatedArea) const
Draw this drawable.
virtual voidforEachChild(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 RectgetSolidRect() const
Get (the largest possible) rectangle that is guaranteed to be solid (opaque).
virtual voidinsert(Drawable * previous, Drawable & d)
Inserts a Drawable after a specific child node.
virtual voidremove(Drawable & d)
Removes a Drawable from the container by removing it from the linked list of children.
virtual voidremoveAll()
Removes all children in the Container by resetting their parent and sibling pointers.
virtual voidunlink()
Removes all children by unlinking the first child.

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 voiddraw(const Rect & invalidatedArea) const =0
Draw this drawable.
Drawable()
Initializes a new instance of the Drawable class.
voiddrawToDynamicBitmap(BitmapId id)
Render the Drawable object into a dynamic bitmap.
RectgetAbsoluteRect() 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_tgetHeight() const
Gets the height of this Drawable.
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 RectgetSolidRect() const =0
Get (the largest possible) rectangle that is guaranteed to be solid (opaque).
virtual RectgetSolidRectAbsolute()
Helper function for obtaining the largest solid rect (as implemented by getSolidRect()) expressed in absolute coordinates.
virtual voidgetVisibleRect(Rect & rect) const
Function for finding the visible part of this drawable.
int16_tgetWidth() const
Gets the width of this Drawable.
int16_tgetX() const
Gets the x coordinate of this Drawable, relative to its parent.
int16_tgetY() const
Gets the y coordinate of this Drawable, relative to its parent.
virtual voidinvalidate() const
Tell the framework that this entire Drawable needs to be redrawn.
virtual voidinvalidateRect(Rect & invalidatedArea) const
Request that a region of this drawable is redrawn.
boolisTouchable() const
Gets whether this Drawable receives touch events or not.
boolisVisible() const
Gets whether this Drawable is visible.
virtual voidmoveRelative(int16_t x, int16_t y)
Moves the drawable.
virtual voidmoveTo(int16_t x, int16_t y)
Moves the drawable.
virtual voidsetHeight(int16_t height)
Sets the height of this drawable.
voidsetPosition(const Drawable & drawable)
Sets the position of the Drawable to the same as the given Drawable.
voidsetPosition(int16_t x, int16_t y, int16_t width, int16_t height)
Sets the size and position of this Drawable, relative to its parent.
voidsetTouchable(bool touch)
Controls whether this Drawable receives touch events or not.
voidsetVisible(bool vis)
Controls whether this Drawable should be visible.
virtual voidsetWidth(int16_t width)
Sets the width of this drawable.
voidsetWidthHeight(const Bitmap & bitmap)
Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates).
voidsetWidthHeight(const Drawable & drawable)
Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates).
voidsetWidthHeight(const Rect & rect)
Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates).
voidsetWidthHeight(int16_t width, int16_t height)
Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates).
virtual voidsetX(int16_t x)
Sets the x coordinate of this Drawable, relative to its parent.
voidsetXY(const Drawable & drawable)
Sets the x and y coordinates of this Drawable.
voidsetXY(int16_t x, int16_t y)
Sets the x and y coordinates of this Drawable, relative to its parent.
virtual voidsetY(int16_t y)
Sets the y coordinate of this Drawable, relative to its parent.
virtual voidtranslateRectToAbsolute(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.
Rectrect
The coordinates of this Drawable, relative to its parent.
booltouchable
True if this drawable should receive touch events.
boolvisible
True if this drawable should be drawn.

Public Functions Documentation#

add#

virtual void add(Drawable &d)

Adds a Drawable instance as child to this Container.

The Drawable added will be placed as the element to be drawn last, and thus appear on top of all previously added drawables in the Container.

Parameters:
dThe Drawable to add.
Note

Never add a drawable more than once!

Reimplements: touchgfx::Container::add

childGeometryChanged#

virtual void childGeometryChanged()

Used to signal that the size or position of one or more children have changed.

This function can be called on parent nodes to signal that the size of one or more of its children have changed.

Reimplements: touchgfx::Drawable::childGeometryChanged

enableHorizontalScroll#

void enableHorizontalScroll(boolenable)

Enables horizontal scrolling.

By default, scrolling in either direction is enabled, provided that the content is larger than the size of the ScrollableContainer. This function can be used to explicitly (dis)allow horizontal scrolling, even if the content is larger than the container.

Parameters:
enableIf true (default), horizontal scrolling is enabled. If false, horizontal scrolling is disabled.
See also:

enableVerticalScroll#

void enableVerticalScroll(boolenable)

Enables vertical scrolling.

By default, scrolling in either direction is enabled, provided that the content is larger than the size of the ScrollableContainer. This function can be used to explicitly (dis)allow vertical scrolling, even if the content is larger than the container.

Parameters:
enableIf true (default), vertical scrolling is enabled. If false, vertical scrolling is disabled.
See also:

getContainedArea#

virtual Rect getContainedArea()const

Gets the area that contains all children added to the ScrollableContainer.

The scrollbars are not considered in this operation.

Returns:

The contained area.

Reimplements: touchgfx::Container::getContainedArea

getLastChild#

virtual void getLastChild(int16_tx ,
int16_ty ,
Drawable **last
)

Gets the last child in the list of children in this Container.

If this Container is touchable (isTouchable()), it will be passed back as the result. Otherwise all visible children are traversed recursively to find the Drawable that intersects with the given coordinate.

Parameters:
xThe x coordinate of the intersection.
yThe y coordinate of the intersection.
lastout parameter in which the result is placed.
See also:

Reimplements: touchgfx::Container::getLastChild

getScrollDurationSlowdown#

uint16_t getScrollDurationSlowdown()const

Gets scroll duration speedup divisor.

Returns:

The scroll duration speedup divisor.

See also:

getScrollDurationSpeedup#

uint16_t getScrollDurationSpeedup()const

Gets scroll duration speedup multiplier.

Returns:

The swipe acceleration.

See also:

getScrolledX#

int16_t getScrolledX()const

Gets the distance scrolled for the x-axis.

Returns:

the distance scrolled for the x-axis.

getScrolledY#

int16_t getScrolledY()const

Gets the distance scrolled for the y-axis.

Returns:

the distance scrolled for the y-axis.

handleClickEvent#

virtual void handleClickEvent(const ClickEvent &evt)

Defines the event handler interface for ClickEvents.

The default implementation ignores the event. The event is only received if the Drawable is touchable and visible.

Parameters:
evtThe ClickEvent received from the HAL.

Reimplements: touchgfx::Drawable::handleClickEvent

handleDragEvent#

virtual void handleDragEvent(const DragEvent &evt)

Defines the event handler interface for DragEvents.

The default implementation ignores the event. The event is only received if the drawable is touchable and visible.

Parameters:
evtThe DragEvent received from the HAL.

Reimplements: touchgfx::Drawable::handleDragEvent

handleGestureEvent#

virtual void handleGestureEvent(const GestureEvent &evt)

Defines the event handler interface for GestureEvents.

The default implementation ignores the event. The event is only received if the Drawable is touchable and visible.

Parameters:
evtThe GestureEvent received from the HAL.

Reimplements: touchgfx::Drawable::handleGestureEvent

handleTickEvent#

virtual void handleTickEvent()

Called periodically by the framework if the Drawable instance has subscribed to timer ticks.

See also:

Reimplements: touchgfx::Drawable::handleTickEvent

isScrollableXY#

virtual void isScrollableXY(bool &scrollX ,
bool &scrollY
)

Is the ClickableContainer scrollable in either direction? Takes the width of the contained elements into account and also checks to see if horizontal or vertical scrolling is allowed.

Parameters:
scrollXTrue if the container is able to scroll horizontally.
scrollYTrue if the container is able to scroll vertically.
See also:

moveChildrenRelative#

virtual void moveChildrenRelative(int16_tdeltaX ,
int16_tdeltaY
)

Calls moveRelative on all children.

Parameters:
deltaXHorizontal displacement.
deltaYVertical displacement.
Note

Takes care not to move the scrollbars, which are also children.

Reimplements: touchgfx::Container::moveChildrenRelative

reset#

void reset()

Resets the ScrollableContainer to its original state, before the user started dragging the contents.

This reset the x/y coordinates of children to the position they were in before the first drag event was received.

ScrollableContainer#

setMaxVelocity#

void setMaxVelocity(uint16_tmax)

Sets the maximum velocity of a scroll due to a swipe.

This can be used to force smooth scrolling by limiting the speed of any swipe gesture.

Parameters:
maxThe maximum velocity of the scroll.
See also:

setScrollbarPadding#

void setScrollbarPadding(uint8_tpadding)

Sets the amount of space between the scrollbar and the edge of the ScrollableContainer.

Parameters:
paddingThe padding.

setScrollbarsAlpha#

void setScrollbarsAlpha(uint8_talpha)

Sets the alpha value (transparency) of the scrollbars.

Parameters:
alphaThe alpha value. 255 being completely solid, 0 being completely invisible.

setScrollbarsColor#

Sets the color of the scrollbars.

Parameters:
colorThe color of the box.

setScrollbarsPermanentlyVisible#

void setScrollbarsPermanentlyVisible(boolpermanentlyVisible =true)

Make scrollbars permanently visible regardless of the size and position of the children of the ScrollableContainer.

Normally the scrollbars are hidden and only shown when dragging the contents of the ScrollableContainer (unless prohibited using setScrollbarsVisible()).

Parameters:
permanentlyVisible(Optional) True to show the scrollbars permanently, false for default behavior.
See also:

setScrollbarsVisible#

void setScrollbarsVisible(boolnewVisible)

Sets the visibility of the scrollbars, when the scrollable area is pressed.

By default the scrollbars are hidden, but shown when the contents of the ScrollableContainer is being dragged around. Using setScrollbarsVisible, it is possble to hide the scrollbars when dragging the contents.

Parameters:
newVisibleIf true (default), the scrollbars are visible when scrollable area is pressed. If false, scrollbars are always hidden.
See also:

setScrollbarWidth#

void setScrollbarWidth(uint8_twidth)

Sets the width of the scrollbar measured in pixels.

Parameters:
widthThe width of the scrollbar.

setScrollDurationSlowdown#

void setScrollDurationSlowdown(uint16_tslowdown)

Sets scroll duration speedup divisor.

Default value is 1.

Parameters:
slowdownThe scroll duration speedup divisor.
See also:

setScrollDurationSpeedup#

void setScrollDurationSpeedup(uint16_tspeedup)

Sets scroll duration speedup multiplier.

Default value is 7 which gives a nice speedup on gestures.

Parameters:
speedupThe scroll duration speedup multiplier.
See also:

setScrollThreshold#

void setScrollThreshold(int16_tt)

Change the threshold which the first drag event received must exceed before initiating a scroll.

This can be used to avoid touching the screen and moving the finger only a few pixels resulting in the contents being scrolled.

Parameters:
tThe new threshold value.
Note

All subsequent scrolls will be processed regardless of threshold value until a ClickEvent::RELEASED is received.

Protected Functions Documentation#

doScroll#

virtual bool doScroll(int16_tdeltaX ,
int16_tdeltaY
)

Method to actually scroll the container.

Passing negative values will scroll the items in the ScrollableContainer up / left, whereas positive values will scroll items down / right.

If the distance is larger than allowed, the deltas are adjusted down to make sure the contained items stay inside view.

Parameters:
deltaXThe horizontal amount to scroll.
deltaYThe vertical amount to scroll.
Returns:

did the container actually scroll. The call doScroll(0,0) will always return false.

getXBorder#

Rect getXBorder(const Rect &xBar ,const
const Rect &yBarconst
)const

Gets the area where the horizontal scrollbar can move.

Parameters:
xBarThe current horizontal scrollbar, supplied for caching reasons.
yBarThe current vertical scrollbar, supplied for caching reasons.
Returns:

The area.

getXScrollbar#

Rect getXScrollbar()const

Gets x coordinate of the scrollbar.

Returns:

The horizontal scrollbar area.

getYBorder#

Rect getYBorder(const Rect &xBar ,const
const Rect &yBarconst
)const

Gets the area where the vertical scrollbar can move.

Parameters:
xBarThe current horizontal scrollbar, supplied for caching reasons.
yBarThe current vertical scrollbar, supplied for caching reasons.
Returns:

The area.

getYScrollbar#

Rect getYScrollbar()const

Gets y coordinate of the scrollbar.

Returns:

The vertical scrollbar area.

invalidateScrollbars#

Invalidate the scrollbars.

Protected Attributes Documentation#

accelDirection#

The current direction (horizontal or vertical) of scroll.

animate#

bool animate

Is scroll animation currently active.

animationCounter#

uint16_t animationCounter

Current step/tick in scroll animation.

beginningValue#

int16_t beginningValue

Initial X or Y for calculated values in scroll animation.

fingerAdjustmentX#

int16_t fingerAdjustmentX

How much should the finger be adjusted horizontally.

fingerAdjustmentY#

int16_t fingerAdjustmentY

and how much vertically

hasIssuedCancelEvent#

bool hasIssuedCancelEvent

true if the pressed drawable has received cancel event

isPressed#

bool isPressed

Is the container currently pressed (maybe show scrollbars)

isScrolling#

bool isScrolling

Is the container scrolling (i.e. has overcome the initial larger drag that is required to initiate a scroll).

lastDraggableChild#

Drawable * lastDraggableChild

The drawable child of this container which should receive drag events. Note that only drag events in directions which cannot be scrolled by this ScrollableContainer will be forwarded to children.

maxVelocity#

uint16_t maxVelocity

The maximum velocity of a scroll (due to a swipe)

pressedDrawable#

Drawable * pressedDrawable

The drawable child of this container which received the last ClickEvent::PRESSED notification. When scrolling, send this drawable a CANCEL event if the new x/y coords no longer matches this drawable.

pressedX#

int16_t pressedX

The x coordinate where the last ClickEvent::PRESSED was received.

pressedY#

int16_t pressedY

The y coordinate where the last ClickEvent::PRESSED was received.

scrollableX#

bool scrollableX

Is the container scrollable in the horizontal direction.

scrollableY#

bool scrollableY

Is the container scrollable in the vertical direction.

scrollbarAlpha#

uint8_t scrollbarAlpha

The scrollbar is semitransparent.

scrollbarColor#

colortype scrollbarColor

The color of the scrollbar.

scrollbarPadding#

uint8_t scrollbarPadding

The amount of padding. The scrollbar will have a bit of space to the borders of the container.

scrollbarsPermanentlyVisible#

bool scrollbarsPermanentlyVisible

Are scrollbars always visible.

scrollbarsVisible#

bool scrollbarsVisible

Are scrollbars visible.

scrollbarWidth#

uint8_t scrollbarWidth

The width of the scrollbar.

scrollDuration#

uint16_t scrollDuration

Number of ticks the scroll animation should use.

scrollDurationSlowdown#

uint16_t scrollDurationSlowdown

The scroll durations is divided by this number.

scrollDurationSpeedup#

uint16_t scrollDurationSpeedup

The scroll durations is multipled by this number.

scrolledXDistance#

int16_t scrolledXDistance

The scrolled horizontal distance.

scrolledYDistance#

int16_t scrolledYDistance

The scrolled vertical distance.

scrollThreshold#

int16_t scrollThreshold

The threshold which the first drag event received must exceed before scrolling. Default is 5.

targetValue#

int16_t targetValue

Target X or Y value for scroll animation.

xSlider#

Box xSlider

The horizontal scrollbar drawable.

ySlider#

Box ySlider

The vertical scrollbar drawable.

SCROLLBAR_LINE#

const uint8_t SCROLLBAR_LINE = 0

The scrollbar line.

SCROLLBAR_MAX_VELOCITY#

const uint16_t SCROLLBAR_MAX_VELOCITY = 17

The (default) maximum velocity of a scroll due to a swipe.

SCROLLBAR_MIN_VELOCITY#

const uint16_t SCROLLBAR_MIN_VELOCITY = 5

The minimum velocity of a scroll due to a swipe.