DsLabel is a class that represents a text label view. More...

#include <ds_label.h>

Inheritance diagram for DsLabel:

Public Member Functions
	DsLabel (DsView parent, const DsPoint &pos, const DsSize &size, const ds_bitmap_font_t font=nullptr, size_t max_text_length=15, DsColor text_color=WHITE, const DsAlignment &text_alignment=DS_ALIGN_CENTER_LEFT)
	Creates a DsLabel view which owns a DsString object containing the text to be rendered.

	DsLabel (DsView parent, const DsPoint &pos, const DsSize &size, const ds_bitmap_font_t font=nullptr, const char *text=nullptr, DsColor text_color=WHITE, const DsAlignment &text_alignment=DS_ALIGN_CENTER_LEFT)
	Creates a DsLabel view which uses an externally allocated string containing the text to be rendered.

	DsLabel (DsView parent, const ds_bitmap_font_t font=nullptr, const char *text=nullptr, DsColor text_color=WHITE, const DsAlignment &text_alignment=DS_ALIGN_CENTER_LEFT)
	Creates a DsLabel view which uses an externally allocated string containing the text to be rendered.

DsLabel *	setAutoFit (bool enabled)
	Enables or disables the auto-fitment feature.

DsLabel *	setLineAlignment (const DsAlignment &alignment)
	Sets the alignment used between each line of a multiline text.

DsLabel *	setTextAlignment (const DsAlignment &alignment)
	Sets the alignment used for the text inside the view.

DsLabel *	setTextMarginLeft (int16_t margin)
	Sets the left text margin.

DsLabel *	setTextMarginRight (int16_t margin)
	Sets the right text margin.

DsLabel *	setTextMarginTop (int16_t margin)
	Sets the top text margin.

DsLabel *	setTextMarginBottom (int16_t margin)
	Sets the bottom text margin.

DsLabel *	setRowSpacing (float row_spacing)
	Sets the text row spacing.

void	setText (const char *text)
	Sets the DsLabel text.

size_t	setTextFormat (const char *format,...)
	Sets the DsLabel text in printf() style format.

size_t	setTextFormat (const char *format, va_list args)
	Sets the DsLabel text in vprintf() style format.

DsLabel *	setFont (const ds_bitmap_font_t *font)
	Sets the font.

DsLabel *	setTextColor (DsColor color)
	Sets the text color.

DsSize	fitContent (void) override
	Runs the auto-fitment algorithm. Sets the size of the DsLabel to fit the size required to render the text.

Public Member Functions inherited from DsView
	DsView (DsView *parent, const DsPoint &pos=DsPoint(), const DsSize &size=DsSize())
	Creates a DsView with an optional position and size.

	DsView (DsView *parent, DsOrientation layout_orientation)
	Creates a DsView with the auto-layout mode active. This view can align it's children automatically.

void	addChild (DsView *view)
	Adds a child to the current DsView.

void	removeChild (DsView *view)
	Removes a child to the current DsView.

void	removeAllChildren (void)
	Removes all children of the current DsView.

void	bringFront (void)
	Brings the current view to the top of the drawing order.

void	sendBack (void)
	Sends the current view to the bottom of the drawing order.

DsView *	getParent (void) const
	Returns the parent of the current view.

void	setParent (DsView *parent)
	Sets a new parent to the view.

const DsPoint &	getPosition (void) const
	Returns the position of the view in parent coordinates.

DsFPoint	getCenterPoint (void) const
	Returns the center point of the view in current coordinates.

DsPoint	translatePositionInParentCoordinates (const DsView *parent, DsPoint pos) const
	Translates position (x, y) in parent coordinate system.

DsPoint	translatePositionInParentCoordinates (uint32_t parent_level, DsPoint pos) const
	Translates position (x, y) in parent coordinate system.

DsPoint	getPositionInParentCoordinates (const DsView *parent) const
	Returns the position in the parent's coordinate system.

void	setPosition (const DsPoint &pos)
	Sets the position of the view in parent coordinates.

void	setCenterPosition (const DsPoint &pos)
	Sets the position of the center of the view in parent coordinates.

void	centerVertically (DsView *view)
	Aligns vertically the center of the current view with the center of another view.

void	centerHorizontally (DsView *view)
	Aligns horizontally the center of the current view with the center of another view.

const DsSize &	getParentSize (void) const
	Returns the size of the parent view.

const DsSize &	getSize (void) const
	Returns the size of the view.

void	setMinimumSize (const DsSize &size)
	Returns the minimum size of the view.

void	setSize (const DsSize &size)
	Sets the size of the view.

void	setWidth (int32_t width)
	Sets the width of the view.

void	setHeight (int32_t height)
	Sets the height of the view.

DsRect	getRegion (void) const
	Returns a rectangle describing the space occupied by the current view in it's own coordinate system (X and Y coordinates are 0).

DsRect	getRegionInParentCoordinates (const DsView *parent) const
	Returns a rectangle describing the space occupied by the current view in the parent's coordinate system.

void	alignInParent (void)
	Aligns the view relative to it's parent.

void	alignInParent (const DsAlignment &alignment, int32_t padding_top, int32_t padding_left, int32_t padding_bottom, int32_t padding_right)
	Aligns the view relative to it's parent.

DsView *	setPaddingTop (int16_t padding, uint16_t proportion=0)
	Sets the top padding used by the auto-layout.

DsView *	setPaddingBottom (int16_t padding, uint16_t proportion=0)
	Sets the bottom padding used by the auto-layout.

DsView *	setPaddingLeft (int32_t padding, uint16_t proportion=0)
	Sets the left padding used by the auto-layout.

DsView *	setPaddingRight (int16_t padding, uint16_t proportion=0)
	Sets the right padding used by the auto-layout.

DsView *	setPadding (int16_t padding, uint16_t proportion=0)
	Sets the padding used by the auto-layout.

DsView *	setPaddingHorizontal (int16_t padding, uint16_t proportion=0)
	Sets the horizontal padding used by the auto-layout.

DsView *	setPaddingVertical (int16_t padding, uint16_t proportion=0)
	Sets the vertical padding used by the auto-layout.

DsView *	setProportion (uint32_t proportion)
	Sets the view proportion used by the auto-layout.

DsAlignment	getParentAlignment (void) const
	Returns parent alignment mode of the view.

DsView *	setParentAlignment (const DsAlignment &alignment)
	Sets parent alignment mode of the view.

void	reserveSpace (bool state)
	Configures if during auto-layout the view will reserve space even if it's hidden.

void	setAutoLayout (DsOrientation orientation, bool enable)
	Enables or disables the auto-layout mode and sets the primary orientation.

void	doLayout (void)
	Runs the auto-layout algorithm.

void	setBackgroundColor (DsColor color)
	Sets the background color of the view.

void	setBackgroundImage (const DsSurface *surface)
	Sets the background image.

void	setPanelColor (DsColor color)
	Sets the color of the panel.

void	setPanelBorderColor (DsColor color)
	Sets the color of the panel border.

void	setPanelCornerRadius (uint16_t radius)
	Sets the radius of the panel corners.

void	setPanelBorderThickness (uint8_t thickness)
	Sets the thickness of the panel border.

DsScreen &	getScreen (void)
	Returns a reference to the screen to which this view belongs.

bool	isFocused (void)
	Is the view focused?

bool	getIsVisible (void) const
	Is the view visibility enabled?

bool	isVisible (void) const
	Is the view actually visible on the screen?

bool	isParentVisible (void) const
	Is the parent view actually visible on the screen?

bool	show (void)
	Shortcut to setVisible(true).

bool	hide (void)
	Shortcut to setVisible(false).

bool	setVisible (bool is_visible)
	Changes the visibility of the view.

virtual void	onShow (void)
	This virtual method is called when the view becomes visible on the screen.

virtual void	onHide (void)
	This virtual method is called when the view becomes invisible (hidden) on the screen.

void	enable (bool state)
	Enables or disables the view.

bool	isEnabled (void) const
	Is the view enabled?

void	enableTouch (bool state)
	Enables or disables processing of touch events.

bool	isTouchEnabled (void) const
	Is the view enabled to process touch events?

void	sendTap (DsPoint pos)
	Sends a tap event to the view.

void	setOnTapCallback (const lambda< void(const DsPoint &p)> &cb)
	Sets the lambda to be executed when the user taps on the view.

void	setOnLongTapCallback (const lambda< void(const DsPoint &p)> &cb)
	Sets the lambda to be executed when the user taps the view and holds for a specific time (set with setLongTapDetection()).

void	setOnTouchActiveCallback (const lambda< void(const DsPoint &p)> &cb)
	Sets the lambda to be executed when the user touches the view.

void	setOnTouchReleaseCallback (const lambda< void(void)> &cb)
	Sets the lambda to be executed when the user touch is released.

void	setLongTapDetection (uint32_t delay_ms)
	Configures the long tap detection.

bool	isInputInside (void) const
	Returns if there is user input (touch) inside the view.

const DsPoint &	getTouchPosition (void) const
	Returns the location of the user touch input inside the view.

void	enableHorizontalScroll (bool state)
	Enables or disables the horizontal scroll of the view contents.

void	enableVerticalScroll (bool state)
	Enables or disables the vertical scroll of the view contents.

void	setScrollbarColor (DsColor color)
	Configure the color of the scroll bars.

virtual void	invalidate (void)
	Invalidates the view.

virtual void	invalidateRegion (DsRect region)
	Invalidates only a region of the view.

void	addStateObserver (StateObserver *observer)
	Adds a state observer object.

void	removeStateObserver (StateObserver *observer)
	Removes a state observer object.

Protected Member Functions
void	onPaint (DsRenderer &renderer)
	This virtual method will be called when the view needs to repaint it's content.

Protected Member Functions inherited from DsView
virtual void	onChildAdd (DsView *child)
	This virtual method will be called when a new child had been added to the view.

virtual void	onSizeChange (void)
	This virtual method will be called when the size of the view changes.

virtual void	onPaintOver (DsRenderer &renderer)
	This virtual method will be called when the view needs to repaint it's content, but after the view and it's children had been painted.

virtual bool	onTouch (const DsTouchEvent &event)
	This virtual method will be called when there is touch user input.

virtual void	onVSync (void)
	This virtual method is be called at every vertical sync period.

virtual void	onKeyboard (int32_t key)
	This virtual method is called when there is a keyboard event that needs to be processed.

void	inputCapture (void)
	Captures the touch input.

bool	isInputCaptured (void) const
	Is the input captured?

void	skipInput (void)
	Skips receiving touch inputs until the end of the current touch event.

void	forAllChildren (const lambda< void(DsView *child)> &lambda)
	Calls the supplied lambda for every view in the children list.

void	forAllChildrenBackwards (const lambda< void(DsView *child)> &lambda)
	Calls the supplied lambda for every view in the children list.

Additional Inherited Members
Protected Attributes inherited from DsView
DsPoint	mScrollPosition

DsPoint	mPreviousScrollPosition

DsPoint	mScrollPositionBase

DsColor	mScrollbarColor

DsPoint	mTouchPos

uint32_t	mTouchTimestamp

Detailed Description

DsLabel is a class that represents a text label view.

It can draw aligned multi-line text inside a rectangular area using the specified alignment. The source of the text can be either a pointer to an externally stores C string or a DsString object owned by the view.

Constructor & Destructor Documentation

◆ DsLabel() [1/3]

DsLabel::DsLabel	(	DsView *	parent,
		const DsPoint &	pos,
		const DsSize &	size,
		const ds_bitmap_font_t *	font = `nullptr`,
		size_t	max_text_length = `15`,
		DsColor	text_color = `WHITE`,
		const DsAlignment &	text_alignment = `DS_ALIGN_CENTER_LEFT`
	)

Creates a DsLabel view which owns a DsString object containing the text to be rendered.

Parameters

parent	The parent view
pos	The position of the view in the parent coordinate system
size	The size of the view
font	Font used for rendering the label
max_text_length	Size of the maximum string to be rendered. The owned DsString will use this size to allocate enough space.
text_color	Color of the text
text_alignment	Alignment of the text inside the DsLabel view

◆ DsLabel() [2/3]

DsLabel::DsLabel	(	DsView *	parent,
		const DsPoint &	pos,
		const DsSize &	size,
		const ds_bitmap_font_t *	font = `nullptr`,
		const char *	text = `nullptr`,
		DsColor	text_color = `WHITE`,
		const DsAlignment &	text_alignment = `DS_ALIGN_CENTER_LEFT`
	)

Creates a DsLabel view which uses an externally allocated string containing the text to be rendered.

Parameters

parent	The parent view of the DsLabel
pos	The position of the DsLabel in the parent coordinate system
size	The size of the DsView
font	Font used for rendering the label
text	Pointer to the C string to be rendered
text_color	Color of the text
text_alignment	Alignment of the text inside the DsLabel view

◆ DsLabel() [3/3]

DsLabel::DsLabel	(	DsView *	parent,
		const ds_bitmap_font_t *	font = `nullptr`,
		const char *	text = `nullptr`,
		DsColor	text_color = `WHITE`,
		const DsAlignment &	text_alignment = `DS_ALIGN_CENTER_LEFT`
	)

Creates a DsLabel view which uses an externally allocated string containing the text to be rendered.

The position will be initialized to (0, 0) and the size will be calculated to fit the text. This constructor is used for labels that will be positioned automatically by the auto-layout feature of the parent view.

Parameters

parent	The parent view of the DsLabel
font	Font used for rendering the label
text	Pointer to the C string to be rendered
text_color	Color of the text
text_alignment	Alignment of the text inside the DsLabel view

Member Function Documentation

◆ fitContent()

DsSize DsLabel::fitContent ( void )

overridevirtual

Runs the auto-fitment algorithm. Sets the size of the DsLabel to fit the size required to render the text.

Reimplemented from DsView.

◆ onPaint()

void DsLabel::onPaint ( DsRenderer & renderer )

protectedvirtual

This virtual method will be called when the view needs to repaint it's content.

A derived class must override it and implement it's own content painting. In the default implementation, it implements the window scrolling mechanism.

Paint events are propagated recursively, from top down. First the view's own onPaint() is called, followed by painting it's children and finally its own onPaintAfter(). Views only receive the onPaint() event if they need to repaint their contents.

Parameters

renderer A DsRenderer object that can be used for painting operations. This object already has a DsSurface attached to it. This DsSurface object is a subsurface of the framebuffer representing only the area used by the view. All coordinates are zero based (in the current view coordinate system).

Reimplemented from DsView.

◆ setAutoFit()

DsLabel * DsLabel::setAutoFit ( bool enabled )

Enables or disables the auto-fitment feature.

Parameters

enabled If true the view will calculate its size to fit the text whenver the fitContent() method is called by a parent view auto-layout algorithm

Returns: THIS pointer. This way, other calls to member functions can be daisy chained.

◆ setFont()

DsLabel * DsLabel::setFont ( const ds_bitmap_font_t * font )

Sets the font.

Parameters

font	New font used for rendering

Returns: THIS pointer. This way, other calls to member functions can be daisy chained.

◆ setLineAlignment()

DsLabel * DsLabel::setLineAlignment ( const DsAlignment & alignment )

Sets the alignment used between each line of a multiline text.

Parameters

alignment Line alignment

Returns: THIS pointer. This way, other calls to member functions can be daisy chained.

◆ setRowSpacing()

DsLabel * DsLabel::setRowSpacing ( float row_spacing )

Sets the text row spacing.

Parameters

row_spacing Text row spacing. The default is 1.0 which is the standard row spacing for the font.

Returns: THIS pointer. This way, other calls to member functions can be daisy chained.

◆ setText()

void DsLabel::setText ( const char * text )

Sets the DsLabel text.

If the DsLabel was created to own its DsString object, the text pointer to by the parameter will be copied inside the DsString object. If the DsLabel is using an externally storef string, it will store the parameter and display the text at that location.

Parameters

text	Pointer to the C string

◆ setTextAlignment()

DsLabel * DsLabel::setTextAlignment ( const DsAlignment & alignment )

Sets the alignment used for the text inside the view.

Parameters

alignment Text alignment

Returns: THIS pointer. This way, other calls to member functions can be daisy chained.

◆ setTextColor()

DsLabel * DsLabel::setTextColor ( DsColor color )

Sets the text color.

Parameters

color Text color

Returns: THIS pointer. This way, other calls to member functions can be daisy chained.

◆ setTextFormat() [1/2]

size_t DsLabel::setTextFormat	(	const char *	format,
		va_list	args
	)

Sets the DsLabel text in vprintf() style format.

This method only works if the DsLabel owns it's string.

Parameters

format	vprintf() style format
args	Variable argument list

◆ setTextFormat() [2/2]

size_t DsLabel::setTextFormat	(	const char *	format,
			...
	)

Sets the DsLabel text in printf() style format.

This method only works if the DsLabel owns it's string.

Parameters

format printf() style format

◆ setTextMarginBottom()

DsLabel * DsLabel::setTextMarginBottom ( int16_t margin )

Sets the bottom text margin.

Parameters

margin Bottom text margin

Returns: THIS pointer. This way, other calls to member functions can be daisy chained.

◆ setTextMarginLeft()

DsLabel * DsLabel::setTextMarginLeft ( int16_t margin )

Sets the left text margin.

Parameters

margin Left text margin

Returns: THIS pointer. This way, other calls to member functions can be daisy chained.

◆ setTextMarginRight()

DsLabel * DsLabel::setTextMarginRight ( int16_t margin )

Sets the right text margin.

Parameters

right Right text margin

Returns: THIS pointer. This way, other calls to member functions can be daisy chained.

◆ setTextMarginTop()

DsLabel * DsLabel::setTextMarginTop ( int16_t margin )

Sets the top text margin.

Parameters

margin Top text margin

Returns: THIS pointer. This way, other calls to member functions can be daisy chained.

The documentation for this class was generated from the following file:

inc/ds_label.h

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ DsLabel() [1/3]

◆ DsLabel() [2/3]

◆ DsLabel() [3/3]

Member Function Documentation

◆ fitContent()

◆ onPaint()

◆ setAutoFit()

◆ setFont()

◆ setLineAlignment()

◆ setRowSpacing()

◆ setText()

◆ setTextAlignment()

◆ setTextColor()

◆ setTextFormat() [1/2]

◆ setTextFormat() [2/2]

◆ setTextMarginBottom()

◆ setTextMarginLeft()

◆ setTextMarginRight()

◆ setTextMarginTop()