Skip to main content
Version: 4.16

Drawable

The Drawable class is an abstract definition of something that can be drawn. In the composite design pattern, the Drawable is the component interface. Drawables can be added to a screen as a tree structure through the leaf node class Widget and the Container class. A Drawable contains a pointer to its next sibling and a pointer to its parent node. These are maintained by the Container to which the Drawable is added.

The Drawable interface contains two pure virtual functions which must be implemented by widgets, namely draw() and getSolidRect(). In addition it contains general functionality for receiving events and navigating the tree structure.

The coordinates of a Drawable are always relative to its parent node.

See: Widget, Container

Inherited by: Container, Widget

Public Functions#

virtual voidchildGeometryChanged()
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 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.
virtual voidgetLastChild(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 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 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 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#

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#

childGeometryChanged#

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.

Currently only used in ScrollableContainer to redraw scrollbars when the size of the scrolling contents changes.

Reimplemented by: touchgfx::ScrollableContainer::childGeometryChanged

draw#

Drawable#

Initializes a new instance of the Drawable class.

drawToDynamicBitmap#

Render the Drawable object into a dynamic bitmap.

Parameters:
idThe target dynamic bitmap to use for rendering.

getAbsoluteRect#

Rect getAbsoluteRect()const

Helper function for obtaining the rectangle this Drawable covers, expressed in absolute coordinates.

Returns:

The rectangle this Drawable covers expressed in absolute coordinates.

See also:

getFirstChild#

virtual Drawable * getFirstChild()

Function for obtaining the first child of this drawable if any.

Returns:

A pointer on the first child drawable if any.

See also:

Reimplemented by: touchgfx::Container::getFirstChild

getHeight#

int16_t getHeight()const

Gets the height of this Drawable.

Returns:

The height of this Drawable.

getLastChild#

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

Function for obtaining the the last child of this drawable that intersects with the specified point.

The last child is the Drawable that is drawn last and therefore the topmost child. Used in input event handling for obtaining the appropriate drawable that should receive the event.

Parameters:
xThe point of intersection expressed in coordinates relative to the parent.
yThe point of intersection expressed in coordinates relative to the parent.
lastLast (topmost) Drawable on the given coordinate.
Note

Input events must be delegated to the last drawable of the tree (meaning highest z- order / front-most drawable).

Reimplemented by: touchgfx::Container::getLastChild, touchgfx::ScrollableContainer::getLastChild, touchgfx::Widget::getLastChild

getNextSibling#

Drawable * getNextSibling()

Gets the next sibling node.

This will be the next Drawable that has been added to the same Container as this Drawable.

Returns:

The next sibling. If there are no more siblings, the return value is 0.

getParent#

Drawable * getParent()const

Returns the parent node.

For the root container, the return value is 0.

Returns:

The parent node. For the root container, the return value is 0.

Note

A disconnected Drawable also has parent 0 which may cause strange side effects.

getRect#

const Rect & getRect()const

Gets the rectangle this Drawable covers, in coordinates relative to its parent.

Returns:

The rectangle this Drawable covers expressed in coordinates relative to its parent.

See also:

getSolidRect#

virtual Rect getSolidRect()const =0

Get (the largest possible) rectangle that is guaranteed to be solid (opaque).

This information is important, as any Drawable underneath the solid area does not need to be drawn.

Returns:

The solid rectangle part of the Drawable.

Note

The rectangle returned must be relative to upper left corner of the Drawable, meaning that a completely solid widget should return the full size Rect(0, 0, getWidth(), getHeight()). If no area can be guaranteed to be solid, an empty Rect(0, 0, 0, 0) must be returned. Failing to return the correct rectangle may result in errors on the display.

Reimplemented by: touchgfx::Container::getSolidRect, touchgfx::WipeTransition::FullSolidRect::getSolidRect, touchgfx::Box::getSolidRect, touchgfx::Button::getSolidRect, touchgfx::CanvasWidget::getSolidRect, touchgfx::Image::getSolidRect, touchgfx::PixelDataWidget::getSolidRect, touchgfx::RadioButton::getSolidRect, touchgfx::ScalableImage::getSolidRect, touchgfx::SnapshotWidget::getSolidRect, touchgfx::TextArea::getSolidRect, touchgfx::TextureMapper::getSolidRect, touchgfx::TiledImage::getSolidRect, touchgfx::TouchArea::getSolidRect

getSolidRectAbsolute#

virtual Rect getSolidRectAbsolute()

Helper function for obtaining the largest solid rect (as implemented by getSolidRect()) expressed in absolute coordinates.

Will recursively traverse to the root of the tree to find the proper location of the rectangle on the display.

Returns:

The (largest) solid rect (as implemented by getSolidRect()) expressed in absolute coordinates.

getVisibleRect#

virtual void getVisibleRect(Rect &rect)

Function for finding the visible part of this drawable.

If the parent node has a smaller area than this Drawable, or if the Drawable is placed "over the edge" of the parent, the parent will act as a view port, cutting off the parts of this Drawable that are outside the region. Traverses the tree and yields a result expressed in absolute coordinates.

Parameters:
rectThe region of the Drawable that is visible.

getWidth#

int16_t getWidth()const

Gets the width of this Drawable.

Returns:

The width of this Drawable.

getX#

int16_t getX()const

Gets the x coordinate of this Drawable, relative to its parent.

Returns:

The x value, relative to the parent.

getY#

int16_t getY()const

Gets the y coordinate of this Drawable, relative to its parent.

Returns:

The y value, relative to the parent.

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.

Reimplemented by: touchgfx::Slider::handleDragEvent, touchgfx::AbstractDataGraph::handleDragEvent, touchgfx::ScrollableContainer::handleDragEvent, touchgfx::ScrollBase::handleDragEvent, touchgfx::ScrollWheelBase::handleDragEvent, touchgfx::SwipeContainer::handleDragEvent, touchgfx::Keyboard::handleDragEvent, touchgfx::TouchArea::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.

Reimplemented by: touchgfx::ScrollableContainer::handleGestureEvent, touchgfx::ScrollBase::handleGestureEvent, touchgfx::ScrollWheelBase::handleGestureEvent, touchgfx::SwipeContainer::handleGestureEvent

handleTickEvent#

invalidate#

virtual void invalidate()const

Tell the framework that this entire Drawable needs to be redrawn.

It is the same as calling invalidateRect() with Rect(0, 0, getWidth(), getHeight()).

See also:

Reimplemented by: touchgfx::CanvasWidget::invalidate

invalidateRect#

virtual void invalidateRect(Rect &invalidatedArea)

Request that a region of this drawable is redrawn.

Will recursively traverse the tree towards the root, and once reached, issue a draw operation. When this function returns, the specified invalidated area has been redrawn for all appropriate Drawables covering the region.

To invalidate the entire Drawable, use invalidate()

Parameters:
invalidatedAreaThe area of this drawable to redraw expressed in relative coordinates.
See also:

Reimplemented by: touchgfx::CacheableContainer::invalidateRect

isTouchable#

bool isTouchable()const

Gets whether this Drawable receives touch events or not.

Returns:

True if touch events are received.

See also:

isVisible#

bool isVisible()const

Gets whether this Drawable is visible.

Returns:

true if the Drawable is visible.

See also:

moveRelative#

virtual void moveRelative(int16_tx ,
int16_ty
)

Moves the drawable.

Parameters:
xThe relative position to move to.
yThe relative position to move to.
Note

Will redraw the appropriate areas of the screen.

See also:

moveTo#

virtual void moveTo(int16_tx ,
int16_ty
)

Moves the drawable.

Parameters:
xThe absolute position to move to.
yThe absolute position to move to.
Note

Will redraw the appropriate areas of the screen.

See also:

setHeight#

virtual void setHeight(int16_theight)

Sets the height of this drawable.

Parameters:
heightThe new height.
Note

For most Drawable widgets, changing this does normally not automatically yield a redraw.

Reimplemented by: touchgfx::DigitalClock::setHeight, touchgfx::DrawableList::setHeight, touchgfx::ScrollBase::setHeight, touchgfx::ScrollWheelWithSelectionStyle::setHeight, touchgfx::ZoomAnimationImage::setHeight, touchgfx::Gauge::setHeight, touchgfx::AbstractDataGraph::setHeight

setPosition#

void setPosition(const Drawable &drawable)

Sets the position of the Drawable to the same as the given Drawable.

This will copy the x, y, width and height.

Parameters:
drawableThe drawable.
See also:

setPosition#

void setPosition(int16_tx ,
int16_ty ,
int16_twidth ,
int16_theight
)

Sets the size and position of this Drawable, relative to its parent.

The same as calling setXY(), setWidth() and setHeight() in that order.

Parameters:
xThe x coordinate of this Drawable relative to its parent.
yThe y coordinate of this Drawable relative to its parent.
widthThe width of this Drawable.
heightThe height of this Drawable.
Note

For most Drawable widgets, changing this does normally not automatically yield a redraw.

setTouchable#

void setTouchable(booltouch)

Controls whether this Drawable receives touch events or not.

Parameters:
touchIf true it will receive touch events, if false it will not.

setVisible#

void setVisible(boolvis)

Controls whether this Drawable should be visible.

Only visible Drawables will have their draw function called. Additionally, invisible drawables will not receive input events.

Parameters:
vistrue if this Drawable should be visible. By default, drawables are visible unless this function has been called with false as argument.
Note

For most Drawable widgets, changing this does normally not automatically yield a redraw.

setWidth#

virtual void setWidth(int16_twidth)

Sets the width of this drawable.

Parameters:
widthThe new width.
Note

For most Drawable widgets, changing this does normally not automatically yield a redraw.

Reimplemented by: touchgfx::DigitalClock::setWidth, touchgfx::DrawableList::setWidth, touchgfx::ScrollBase::setWidth, touchgfx::ScrollWheelWithSelectionStyle::setWidth, touchgfx::ZoomAnimationImage::setWidth, touchgfx::Gauge::setWidth, touchgfx::AbstractDataGraph::setWidth

setWidthHeight#

void setWidthHeight(const Bitmap &bitmap)

Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates).

Parameters:
bitmapThe Bitmap to copy the width and height from.
See also:

setWidthHeight#

void setWidthHeight(const Drawable &drawable)

Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates).

Parameters:
drawableThe Drawable to copy the width and height from.
See also:

setWidthHeight#

void setWidthHeight(const Rect &rect)

Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates).

Parameters:
rectThe Rect to copy the width and height from.
See also:

setWidthHeight#

void setWidthHeight(int16_twidth ,
int16_theight
)

Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates).

Parameters:
widthThe width.
heightThe height.

setX#

virtual void setX(int16_tx)

Sets the x coordinate of this Drawable, relative to its parent.

Parameters:
xThe new x value, relative to the parent. A negative value is allowed.
Note

For most Drawable widgets, changing this does normally not automatically yield a redraw.

setXY#

void setXY(const Drawable &drawable)

Sets the x and y coordinates of this Drawable.

Parameters:
drawableThe Drawable to copy the x and y coordinates from.
See also:

setXY#

void setXY(int16_tx ,
int16_ty
)

Sets the x and y coordinates of this Drawable, relative to its parent.

The same as calling setX() followed by calling setY().

Parameters:
xThe new x value, relative to the parent. A negative value is allowed.
yThe new y value, relative to the parent. A negative value is allowed.
Note

For most Drawable widgets, changing this does normally not automatically yield a redraw.

See also:

setY#

virtual void setY(int16_ty)

Sets the y coordinate of this Drawable, relative to its parent.

Parameters:
yThe new y value, relative to the parent. A negative value is allowed.
Note

For most Drawable widgets, changing this does normally not automatically yield a redraw.

translateRectToAbsolute#

virtual void translateRectToAbsolute(Rect &r)

Helper function for converting a region of this Drawable to absolute coordinates.

Parameters:
rThe Rect to translate.

~Drawable#

virtual ~Drawable()

Finalizes an instance of the Drawable class.

Protected Attributes Documentation#

nextSibling#

Drawable * nextSibling

Pointer to the next Drawable.

parent#

Drawable * parent

Pointer to this drawable's parent.

rect#

Rect rect

The coordinates of this Drawable, relative to its parent.

touchable#

bool touchable

True if this drawable should receive touch events.

visible#

bool visible

True if this drawable should be drawn.