跳轉到主要內容

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

voidcenter()
Centers the Drawable inside its parent.
voidcenterX()
Center the Drawable horizontally inside its parent.
voidcenterY()
Center the Drawable vertically inside its parent.
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.
voidexpand(int margin =0)
Expands the Drawable to have the same size as its parent with a given margin around the edge.
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 & event)
Defines the event handler interface for ClickEvents.
virtual voidhandleDragEvent(const DragEvent & event)
Defines the event handler interface for DragEvents.
virtual voidhandleGestureEvent(const GestureEvent & event)
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 voidinvalidateContent() const
Tell the framework that the contents of the 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 & other)
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

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

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.

expand

void expand(intmargin =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:

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 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:
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 &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:
eventThe 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:
eventThe 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()) as argument.

See also:

Reimplemented by: touchgfx::CanvasWidget::invalidate

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

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.

See also:

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

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 &other)

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

Parameters:
otherThe 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.