Drawable

touchgfx/Drawable.hpp

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

void	center()
	Centers the Drawable inside its parent.
void	centerX()
	Center the Drawable horizontally inside its parent.
void	centerY()
	Center the Drawable vertically inside its parent.
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.
void	expand(int margin =0)
	Expands the Drawable to have the same size as its parent with a given margin around the edge.
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	invalidateContent() const
	Tell the framework that the contents of the 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.
virtual void	setHeight(int16_t height)
	Sets the height of this 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.
virtual void	setWidth(int16_t width)
	Sets the width of this drawable.
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 & other)
	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

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

center

void center	(			)

Centers the Drawable inside its parent.

centerX

void centerX	(			)

Center the Drawable horizontally inside its parent.

centerY

void centerY	(			)

Center the Drawable vertically inside its parent.

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

virtual void draw	(	const Rect &	invalidatedArea	)

Draw this drawable.

It is a requirement that the draw implementation does not draw outside the region specified by invalidatedArea.

Parameters:

invalidatedArea	The sub-region of this drawable that needs to be redrawn, expressed in coordinates relative to its parent (e.g. for a complete redraw, invalidatedArea will be (0, 0, width, height).

Reimplemented by: touchgfx::TouchArea::draw, touchgfx::Transition::FullSolidRect::draw, touchgfx::Box::draw, touchgfx::BoxWithBorder::draw, touchgfx::ButtonWithLabel::draw, touchgfx::TextArea::draw, touchgfx::TextAreaWithWildcardBase::draw, touchgfx::Container::draw, touchgfx::Button::draw, touchgfx::ButtonWithIcon::draw, touchgfx::CanvasWidget::draw, touchgfx::GraphElementGridBase::draw, touchgfx::GraphElementVerticalGapLine::draw, touchgfx::GraphElementHistogram::draw, touchgfx::GraphElementBoxes::draw, touchgfx::GraphLabelsBase::draw, touchgfx::GraphTitle::draw, touchgfx::Image::draw, touchgfx::Keyboard::draw, touchgfx::PixelDataWidget::draw, touchgfx::QRCode::draw, touchgfx::RadioButton::draw, touchgfx::ScalableImage::draw, touchgfx::SnapshotWidget::draw, touchgfx::SVGImage::draw, touchgfx::TextureMapper::draw, touchgfx::TiledImage::draw, touchgfx::VideoWidget::draw

Drawable

Drawable	(			)

Initializes a new instance of the Drawable class.

drawToDynamicBitmap

void drawToDynamicBitmap	(	BitmapId	id	)

Render the Drawable object into a dynamic bitmap.

Parameters:

id	The target dynamic bitmap to use for rendering.

expand

void expand	(	int	margin =0	)

Expands the Drawable to have the same size as its parent with a given margin around the edge.

If there is no parent, the position is set to the size of the entire display.

Parameters:

margin	(Optional) The margin.

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:

getRect, translateRectToAbsolute

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:

Container::getFirstChild

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_t	x ,		=0
		int16_t	y ,		=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:

x	The point of intersection expressed in coordinates relative to the parent.
y	The point of intersection expressed in coordinates relative to the parent.
last	Last (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:

getAbsoluteRect

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 must be returned. Failing to return the correct rectangle may result in errors on the display.

Reimplemented by: touchgfx::Container::getSolidRect, touchgfx::Transition::FullSolidRect::getSolidRect, touchgfx::Box::getSolidRect, touchgfx::Button::getSolidRect, touchgfx::CanvasWidget::getSolidRect, touchgfx::Image::getSolidRect, touchgfx::PixelDataWidget::getSolidRect, touchgfx::QRCode::getSolidRect, touchgfx::RadioButton::getSolidRect, touchgfx::ScalableImage::getSolidRect, touchgfx::SnapshotWidget::getSolidRect, touchgfx::SVGImage::getSolidRect, touchgfx::TextArea::getSolidRect, touchgfx::TextureMapper::getSolidRect, touchgfx::TiledImage::getSolidRect, touchgfx::TouchArea::getSolidRect, touchgfx::VideoWidget::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:

rect	The 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

virtual void handleClickEvent	(	const ClickEvent &	event	)

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:

event	The ClickEvent received from the HAL.

Reimplemented by: touchgfx::ClickButtonTrigger::handleClickEvent, touchgfx::RepeatButtonTrigger::handleClickEvent, touchgfx::ToggleButtonTrigger::handleClickEvent, touchgfx::TouchButtonTrigger::handleClickEvent, touchgfx::ScrollableContainer::handleClickEvent, touchgfx::ScrollList::handleClickEvent, touchgfx::ScrollWheelBase::handleClickEvent, touchgfx::Slider::handleClickEvent, touchgfx::SwipeContainer::handleClickEvent, touchgfx::AbstractButton::handleClickEvent, touchgfx::AbstractDataGraph::handleClickEvent, touchgfx::Keyboard::handleClickEvent, touchgfx::RadioButton::handleClickEvent, touchgfx::RepeatButton::handleClickEvent, touchgfx::ToggleButton::handleClickEvent, touchgfx::TouchArea::handleClickEvent

handleDragEvent

virtual void handleDragEvent	(	const DragEvent &	event	)

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:

event	The DragEvent received from the HAL.

Reimplemented by: touchgfx::TouchArea::handleDragEvent, touchgfx::ScrollableContainer::handleDragEvent, touchgfx::ScrollBase::handleDragEvent, touchgfx::ScrollWheelBase::handleDragEvent, touchgfx::Slider::handleDragEvent, touchgfx::SwipeContainer::handleDragEvent, touchgfx::AbstractDataGraph::handleDragEvent, touchgfx::Keyboard::handleDragEvent

handleGestureEvent

virtual void handleGestureEvent	(	const GestureEvent &	event	)

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:

event	The GestureEvent received from the HAL.

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

handleTickEvent

virtual void handleTickEvent	(			)

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

See also:

Application::registerTimerWidget

Reimplemented by: touchgfx::RepeatButtonTrigger::handleTickEvent, touchgfx::AbstractProgressIndicator::handleTickEvent, touchgfx::ScrollableContainer::handleTickEvent, touchgfx::ScrollBase::handleTickEvent, touchgfx::SlideMenu::handleTickEvent, touchgfx::SwipeContainer::handleTickEvent, touchgfx::ZoomAnimationImage::handleTickEvent, touchgfx::MoveAnimator::handleTickEvent, touchgfx::AnimatedImage::handleTickEvent, touchgfx::AnimationTextureMapper::handleTickEvent, touchgfx::RepeatButton::handleTickEvent, touchgfx::VideoWidget::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()) as argument.

See also:

invalidateRect

Reimplemented by: touchgfx::CanvasWidget::invalidate

invalidateContent

virtual void invalidateContent	(			)	const

Tell the framework that the contents of the Drawable needs to be redrawn.

If the Drawable is invisible, nothing happens. Subclasses of Drawable are encouraged to implement this function and invalidate as little as possible, i.e. the smallest rectangle covering the visual element(s) drawn by the widget.

Reimplemented by: touchgfx::CacheableContainer::invalidateContent, touchgfx::AnalogClock::invalidateContent, touchgfx::DigitalClock::invalidateContent, touchgfx::AbstractProgressIndicator::invalidateContent, touchgfx::ZoomAnimationImage::invalidateContent, touchgfx::Box::invalidateContent, touchgfx::Button::invalidateContent, touchgfx::Line::invalidateContent, touchgfx::Gauge::invalidateContent, touchgfx::AbstractDataGraph::invalidateContent, touchgfx::Image::invalidateContent, touchgfx::PixelDataWidget::invalidateContent, touchgfx::RadioButton::invalidateContent, touchgfx::SnapshotWidget::invalidateContent, touchgfx::SVGImage::invalidateContent, touchgfx::TextArea::invalidateContent, touchgfx::TextAreaWithWildcardBase::invalidateContent, touchgfx::TextureMapper::invalidateContent, touchgfx::TouchArea::invalidateContent

invalidateRect

virtual void invalidateRect	(	Rect &	invalidatedArea	)

Request that a region of this drawable is redrawn.

All invalidated regions are collected and possibly merged with other regions that have been invalidated. Before the next tick, these regions will then be redrawn by the drawables, widgets and containers, covering the regions.

To invalidate the entire Drawable, use invalidate()

Parameters:

invalidatedArea	The area of this drawable to redraw expressed in relative coordinates.

See also:

invalidate

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:

setTouchable

isVisible

bool isVisible	(			)	const

Gets whether this Drawable is visible.

Returns:

true if the Drawable is visible.

See also:

setVisible

moveRelative

virtual void moveRelative	(	int16_t	x ,
		int16_t	y
		)

Moves the drawable.

Parameters:

x	The relative position to move to.
y	The relative position to move to.

Note

Will redraw the appropriate areas of the screen.

See also:

moveTo, setXY

moveTo

virtual void moveTo	(	int16_t	x ,
		int16_t	y
		)

Moves the drawable.

Parameters:

x	The absolute position to move to.
y	The absolute position to move to.

Note

Will redraw the appropriate areas of the screen.

See also:

moveRelative, setXY

setHeight

virtual void setHeight	(	int16_t	height	)

Sets the height of this drawable.

Parameters:

height	The 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::ScrollList::setHeight, touchgfx::ScrollWheelWithSelectionStyle::setHeight, touchgfx::ZoomAnimationImage::setHeight, touchgfx::Gauge::setHeight, touchgfx::AbstractDataGraph::setHeight, touchgfx::TextArea::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:

drawable	The Drawable.

See also:

setPosition(int16_t,int16_t,int16_t,int16_t)

setPosition

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.

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

Parameters:

x	The x coordinate of this Drawable relative to its parent.
y	The y coordinate of this Drawable relative to its parent.
width	The width of this Drawable.
height	The height of this Drawable.

Note

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

See also:

setXY,setWidthHeight,setPosition(const Drawable&)

setTouchable

void setTouchable	(	bool	touch	)

Controls whether this Drawable receives touch events or not.

Parameters:

touch	If true it will receive touch events, if false it will not.

setVisible

void setVisible	(	bool	vis	)

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:

vis	true 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_t	width	)

Sets the width of this drawable.

Parameters:

width	The 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::ScrollList::setWidth, touchgfx::ScrollWheelWithSelectionStyle::setWidth, touchgfx::ZoomAnimationImage::setWidth, touchgfx::Gauge::setWidth, touchgfx::AbstractDataGraph::setWidth, touchgfx::TextArea::setWidth

setWidthHeight

void setWidthHeight	(	const Bitmap &	bitmap	)

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

Parameters:

bitmap	The Bitmap to copy the width and height from.

See also:

setWidthHeight(int16_t,int16_t)

setWidthHeight

void setWidthHeight	(	const Drawable &	drawable	)

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

Parameters:

drawable	The Drawable to copy the width and height from.

See also:

setWidthHeight(int16_t,int16_t)

setWidthHeight

void setWidthHeight	(	const Rect &	other	)

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

Parameters:

other	The Rect to copy the width and height from.

See also:

setWidthHeight(int16_t,int16_t)

setWidthHeight

void setWidthHeight	(	int16_t	width ,
		int16_t	height
		)

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

Parameters:

width	The width.
height	The height.

setX

virtual void setX	(	int16_t	x	)

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

Parameters:

x	The 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:

drawable	The Drawable to copy the x and y coordinates from.

See also:

setXY(int16_t,int16_t)

setXY

void setXY	(	int16_t	x ,
		int16_t	y
		)

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

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

Parameters:

x	The new x value, relative to the parent. A negative value is allowed.
y	The 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:

moveTo

setY

virtual void setY	(	int16_t	y	)

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

Parameters:

y	The 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:

r	The 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.