Line

touchgfx/widgets/canvas/Line.hpp

Simple CanvasWidget capable of drawing a line from one point to another point. The end points can be moved to new locations and the line width can be set and changed. A 10 pixel long line along the top of the screen with a width on 1 pixel has endpoints in (0, 0.5) and (10, 0.5) and line width 1. The Line class calculates the corners of the shape, which in this case would be (0, 0), (10, 0), (10, 1) and (0, 1) and tells CanvasWidgetRenderer to moveTo() the first coordinate and then lineTo() the next coordinates in order. Finally it tells CWR to render the inside of the shape using the set Painter object.

The Line class caches the four corners of the shape to speed up redrawing. In general, drawing lines involve some extra mathematics for calculating the normal vector of the line and this computation would slow down re-draws if not cached.

Note: All coordinates are internally handled as CWRUtil::Q5 which means that floating point values are rounded down to a fixed number of binary digits, for example:

Line line;
line.setStart(1.1f, 1.1f); // Will use (35/32, 35/32) = (1.09375f, 1.09375f)
int x, y;
line.getStart(&x, &y); // Will return (1, 1)

Inherits from: CanvasWidget, Widget, Drawable

Public Types


enum	LINE_ENDING_STYLE { BUTT_CAP_ENDING, ROUND_CAP_ENDING, SQUARE_CAP_ENDING }
	Values that represent line ending styles.

Public Functions


virtual bool	drawCanvasWidget(const Rect & invalidatedArea) const
	Draw canvas widget for the given invalidated area.

template <typename T > void	getEnd(T & x, T & y) const
	Gets the endpoint coordinates for the line.

LINE_ENDING_STYLE	getLineEndingStyle() const
	Gets line ending style.

template <typename T > T	getLineWidth() const
	Gets line width.

template <typename T > void	getLineWidth(T & width) const
	Gets line width.

virtual Rect	getMinimalRect() const
	Gets minimal rectangle containing the shape drawn by this widget.

template <typename T > void	getStart(T & x, T & y) const
	Gets the starting point of the line as either integers or floats.

virtual void	invalidateContent() const
	Tell the framework that the contents of the Drawable needs to be redrawn.

	Line()


void	setCapPrecision(int precision)
	Sets a precision of the arc at the ends of the Line.

void	setEnd(CWRUtil::Q5 xQ5, CWRUtil::Q5 yQ5)
	Sets the endpoint coordinates of the line.

template <typename T > void	setEnd(T x, T y)
	Sets the endpoint coordinates of the line.

template <typename T > void	setLine(T startX, T startY, T endX, T endY)
	Sets the starting point and ending point of the line.

void	setLineEndingStyle(LINE_ENDING_STYLE lineEnding)
	Sets line ending style.

void	setLineWidth(CWRUtil::Q5 widthQ5)
	Sets the width for this Line.

template <typename T > void	setLineWidth(T width)
	Sets the width for this Line.

void	setStart(CWRUtil::Q5 xQ5, CWRUtil::Q5 yQ5)
	Sets the starting point of the line.

template <typename T > void	setStart(T x, T y)
	Sets the starting point of the line.

void	updateEnd(CWRUtil::Q5 xQ5, CWRUtil::Q5 yQ5)
	Update the endpoint for this Line.

template <typename T > void	updateEnd(T x, T y)
	Update the endpoint for this Line.

void	updateLengthAndAngle(CWRUtil::Q5 length, CWRUtil::Q5 angle)
	Update the end point for this Line given the new length and angle in degrees.

void	updateLineWidth(CWRUtil::Q5 widthQ5)
	Update the width for this Line.

template <typename T > void	updateLineWidth(T width)
	Update the width for this Line and invalidates the minimal rectangle surrounding the line on screen.

void	updateStart(CWRUtil::Q5 xQ5, CWRUtil::Q5 yQ5)
	Update the start point for this Line.

template <typename T > void	updateStart(T x, T y)
	Update the start point for this Line.

Additional inherited members

Public Functions inherited from CanvasWidget


	CanvasWidget()


virtual void	draw(const Rect & invalidatedArea) const
	Draws the given invalidated area.

virtual uint8_t	getAlpha() const
	Gets the current alpha value of the widget.

const AbstractPainter *	getPainter() const
	Gets the current painter for the CanvasWidget.

virtual Rect	getSolidRect() const
	Gets the largest solid (non-transparent) rectangle.

virtual void	invalidate() const
	Invalidates the area covered by this CanvasWidget.

virtual void	setAlpha(uint8_t newAlpha)
	Sets the opacity (alpha value).

void	setPainter(const AbstractPainter & painter)
	Sets a painter for the CanvasWidget.

Protected Attributes inherited from CanvasWidget


uint8_t	alpha
	The Alpha for this CanvasWidget.


virtual void	getLastChild(int16_t , int16_t , Drawable ** last)
	Since a Widget is only one Drawable, Widget::getLastChild simply yields itself as result, but only if the Widget isVisible and isTouchable.

Public Functions inherited from Drawable


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	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 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 Types Documentation

LINE_ENDING_STYLE

Values that represent line ending styles.


BUTT_CAP_ENDING	The line ending is cut 90 degrees at the end of the line.
ROUND_CAP_ENDING	The line ending is rounded as a circle with center at the end of the line.
SQUARE_CAP_ENDING	The line ending is cut 90 degrees, but extends half the width of the line.

Public Functions Documentation

drawCanvasWidget

Draw canvas widget for the given invalidated area.

Similar to draw(), but might be invoked several times with increasingly smaller areas to due to memory constraints from the underlying CanvasWidgetRenderer.

Parameters:


invalidatedArea	The invalidated area.

Returns:

true if the widget was drawn properly, false if not.

See also:

draw

Reimplements: touchgfx::CanvasWidget::drawCanvasWidget

getEnd


void getEnd	(	T &	x ,	const
		T &	y	const
		)	const

Gets the endpoint coordinates for the line.

Template Parameters:


T	Generic type parameter, either int or float.

Parameters:


x	The x coordinate rounded down to the precision of T.
y	The y coordinate rounded down to the precision of T.

See also:

setEnd, updateEnd

getLineEndingStyle


LINE_ENDING_STYLE getLineEndingStyle	(			)	const

Gets line ending style.

Returns:

The line ending style.

See also:

LINE_ENDING_STYLE, setLineEndingStyle

getLineWidth


T getLineWidth	(			)	const

Gets line width.

Template Parameters:


T	Generic type parameter, either int or float.

Returns:

The line width rounded down to the precision of T.

See also:

setLineWidth

getLineWidth

Gets line width.

Template Parameters:


T	Generic type parameter, either int or float.

Parameters:


width	The line width rounded down to the precision of T.

See also:

setLineWidth

getMinimalRect


virtual Rect getMinimalRect	(			)	const

Gets minimal rectangle containing the shape drawn by this widget.

Default implementation returns the size of the entire widget, but this function should be overwritten in subclasses and return the minimal rectangle containing the shape. See classes such as Circle for example implementations.

Returns:

The minimal rectangle containing the shape drawn.

Reimplements: touchgfx::CanvasWidget::getMinimalRect

getStart


void getStart	(	T &	x ,	const
		T &	y	const
		)	const

Gets the starting point of the line as either integers or floats.

Template Parameters:


T	Generic type parameter, either int or float.

Parameters:


x	The x coordinate rounded down to the precision of T.
y	The y coordinate rounded down to the precision of T.

See also:

setStart, setLine

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.

Reimplements: touchgfx::Drawable::invalidateContent

Line


Line	(			)

setCapPrecision

Sets a precision of the arc at the ends of the Line.

This only works for ROUND_CAP_ENDING. The precision is given in degrees where 18 is the default which results in a nice half circle with 10 line segments. 90 will draw "an arrow head", 180 will look exactly like a BUTT_CAP_ENDING.

Parameters:


precision	The new ROUND_CAP_ENDING precision.

Note

The line is not invalidated. This is only used if line ending is set to ROUND_CAP_ENDING.

setEnd

Sets the endpoint coordinates of the line.

Parameters:


xQ5	The x coordinate of the end point in Q5 format.
yQ5	The y coordinate of the end point in Q5 format.

Note

The area containing the Line is not invalidated.

See also:

updateEnd, getEnd

setEnd

Sets the endpoint coordinates of the line.

Template Parameters:


T	Generic type parameter, either int or float.

Parameters:


x	The x coordinate of the end point.
y	The y coordinate of the end point.

Note

The area containing the Line is not invalidated.

See also:

updateEnd, getEnd

setLine

Sets the starting point and ending point of the line.

Template Parameters:


T	Generic type parameter, either int or float.

Parameters:


startX	The x coordinate of the start point.
startY	The y coordinate of the start point.
endX	The x coordinate of the end point.
endY	The y coordinate of the end point.

Note

The area containing the Line is not invalidated.

See also:

setStart, setEnd

setLineEndingStyle

Sets line ending style.

The same style is applied to both ends of the line.

Parameters:


lineEnding	The line ending style.

Note

The area containing the Line is not invalidated.

See also:

LINE_ENDING_STYLE, getLineEndingStyle

setLineWidth

Sets the width for this Line.

Parameters:


widthQ5	The width of the line measured in pixels in Q5 format.

Note

The area containing the Line is not invalidated.

See also:

updateLineWidth

setLineWidth

Sets the width for this Line.

Template Parameters:


T	Generic type parameter, either int or float.

Parameters:


width	The width of the line measured in pixels.

Note

The area containing the Line is not invalidated.

See also:

updateLineWidth

setStart

Sets the starting point of the line.

Parameters:


xQ5	The x coordinate of the start point in Q5 format.
yQ5	The y coordinate of the start point in Q5 format.

Note

The area containing the Line is not invalidated.

See also:

updateStart, getStart, setLine, setEnd

setStart

Sets the starting point of the line.

Template Parameters:


T	Generic type parameter, either int or float.

Parameters:


x	The x coordinate of the start point.
y	The y coordinate of the start point.

Note

The area containing the Line is not invalidated.

See also:

updateStart, getStart, setLine, setEnd

updateEnd

Update the endpoint for this Line.

The rectangle that surrounds the line before and after will be invalidated.

Parameters:


xQ5	The x coordinate of the end point in Q5 format.
yQ5	The y coordinate of the end point in Q5 format.

Note

The area containing the Line is invalidated before and after the change.

See also:

setEnd, updateStart

updateEnd

Update the endpoint for this Line.

The rectangle that surrounds the line before and after will be invalidated.

Template Parameters:


T	Generic type parameter, either int or float.

Parameters:


x	The x coordinate of the end point.
y	The y coordinate of the end point.

Note

The area containing the Line is invalidated before and after the change.

See also:

setEnd, updateStart

updateLengthAndAngle

Update the end point for this Line given the new length and angle in degrees.

The rectangle that surrounds the line before and after will be invalidated. The starting coordinates will be fixed but the ending point will be updated. This is simply a different way to update the ending point.

Parameters:


length	The new length of the line in Q5 format.
angle	The new angle of the line in Q5 format.

Note

The area containing the Line is invalidated before and after the change. Angles are given in degrees, so a full circle is 360.

See also:

updateEnd

updateLineWidth

Update the width for this Line.

Update the width for this Line and invalidates the minimal rectangle surrounding the line on screen.

Parameters:


widthQ5	The width of the line measured in pixels in Q5 format.

Note

The area containing the Line is invalidated before and after the change.

See also:

setLineWidth

updateLineWidth

Update the width for this Line and invalidates the minimal rectangle surrounding the line on screen.

Template Parameters:


T	Generic type parameter, either int or float.

Parameters:


width	The width of the line measured in pixels.

Note

The area containing the Line is invalidated before and after the change.

See also:

setLineWidth

updateStart

Update the start point for this Line.

The rectangle that surrounds the line before and after will be invalidated.

Parameters:


xQ5	The x coordinate of the start point in CWRUtil::Q5 format.
yQ5	The y coordinate of the start point in CWRUtil::Q5 format.

Note

The area containing the Line is invalidated before and after the change.

See also:

setStart, updateEnd

updateStart

Update the start point for this Line.

The rectangle that surrounds the line before and after will be invalidated.

Template Parameters:


T	Generic type parameter, either int or float.

Parameters:


x	The x coordinate of the start point.
y	The y coordinate of the start point.

Note

The area containing the Line is invalidated before and after the change.

See also:

setStart, updateEnd


void setLine	(	T	startX ,
		T	startY ,
		T	endX ,
		T	endY
		)

Public Types​

Public Functions​

Additional inherited members​

Public Functions inherited from CanvasWidget​

Protected Attributes inherited from CanvasWidget​

Public Functions inherited from Widget​

Public Functions inherited from Drawable​

Protected Attributes inherited from Drawable​

Public Types Documentation​

LINE_ENDING_STYLE​

Public Functions Documentation​

drawCanvasWidget​

getEnd​

getLineEndingStyle​

getLineWidth​

getLineWidth​

getMinimalRect​

getStart​

invalidateContent​

Line​

setCapPrecision​

Note

setEnd​

Note

setEnd​

Note

setLine​

Note

setLineEndingStyle​

Note

setLineWidth​

Note

setLineWidth​

Note

setStart​

Note

setStart​

Note

updateEnd​

Note

updateEnd​

Note

updateLengthAndAngle​

Note

updateLineWidth​

Note

updateLineWidth​

Note

updateStart​

Note

updateStart​

Note

Public Types

Public Functions

Additional inherited members

Public Functions inherited from CanvasWidget

Protected Attributes inherited from CanvasWidget

Public Functions inherited from Widget

Public Functions inherited from Drawable

Protected Attributes inherited from Drawable

Public Types Documentation

LINE_ENDING_STYLE

Public Functions Documentation

drawCanvasWidget

getEnd

getLineEndingStyle

getLineWidth

getLineWidth

getMinimalRect

getStart

invalidateContent

Line

setCapPrecision

setEnd

setEnd

setLine

setLineEndingStyle

setLineWidth

setLineWidth

setStart

setStart

updateEnd

updateEnd

updateLengthAndAngle

updateLineWidth

updateLineWidth

updateStart

updateStart