DsScreen is class of type DsView (inherits from DsView) that implements a physical screen. More...

#include <ds_screen.h>

Inheritance diagram for DsScreen:

Public Member Functions
	DsScreen (int32_t phys_width, int32_t phys_height, DsRotation rotation, DsColorMode cmode, uint8_t linebuffer, uint8_t aa_linebuffer, uint32_t framebuffer_alignment, bool triple_buffered)
	Creates a DsScreen object.

DsRotation	getRotation (void) const
	Returns the logical rotation of the screen.

DsSurface *	allocSurface (int32_t width, int32_t height, DsColorMode cmode, size_t palette_size=0, bool palette_has_alpha=false)
	Allocates a DsSurface object using the screen's allocator and rotation.

void	setFocusedView (DsView *view)
	Sets the focused view.

DsView *	getFocusedView (void) const
	Returns the focused view.

void	registerView (DsView view, const char id)
	Registers a view with the view stack manager.

DsView *	getView (const char *id)
	Returns the view based on its identifier.

bool	pushView (const char *id, bool on_top=false)
	Pushes a new view to the stack.

bool	popView (void)
	Pops the top view from the stack.

bool	popView (const char *id)
	Pops the top named view from the stack.

bool	topViewIs (const char *id)
	Returns true if the view on the top of the stack has the specified id.

bool	unrollViewStack (const char *id)
	Unrolls the view stack to a specific view ID.

bool	unrollViewStack (size_t level)
	Unrolls the view stack to a specific level.

size_t	getViewStackSize (void) const
	Returns the number of views in the view stack.

void	createKeyboard (const ds_bitmap_font_t *font)
	Creates the on screen keyboard object.

DsKeyboard &	getKeyboard (void)
	Returns a reference to the on screen keyboard.

void	run (void)
	Executes the event loop.

DsRenderer	createRenderer (DsSurface &surface)
	Creates a temporary DsRendered using the specified surface.

bool	isUiThread (void) const
	Returns true if the caller is running in the UI thread.

bool	isTouchTimeoutExpired (void) const
	Is the touch timer expired?

void	kickTouchTimeout (uint32_t timeout_ms)
	Kick the touch timeout while setting a new timeout value.

void	queueExitLoopEvent (void)
	Queues an screen vertical sync event into the event loop.

void	queueVSyncEvent (void)
	Queues an VSYNC event into the event loop.

void	queueVSyncEventFromISR (int32_t *woken)
	Queues an screen vertical sync event into the event loop. It can be used from an interrupt handler.

void	queueTouchEvent (const DsTouchEvent::Mode &mode, const DsPoint &pos, uint32_t timestamp)
	Queues a touch event into the event loop.

void	queueTouchEventFromISR (const DsTouchEvent::Mode &mode, const DsPoint &pos, uint32_t timestamp, int32_t *woken)
	Queues a touch event into the event loop. It can be used from an interrupt handler.

void	queueKeyboardEvent (int32_t key)
	Queues a keyboard event into the event loop.

void	queueLambda (const lambda< void(void), 64 > &lambda)
	Queues a lambda to get executed in the UI thread event loop.

void	queueLambdaFromISR (const lambda< void(void), 64 > &lambda, int32_t *woken)
	Queues a lambda to get executed in the UI thread event loop. It can be used from an interrupt handler.

void	lcdSurfaceUpdateFinished (void)
	Called from the LCD driver when the surface update is finished.

void	lcdSurfaceUpdateFinishedFromISR (int32_t *woken)

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.

virtual DsSize	fitContent (void)
	Calculates the minimum size required by the view.

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.

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

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

Protected Member Functions
virtual void	lcdSurfaceUpdate (DsSurface *surface)=0
	Updates the front framebuffer of the screen. Must be implemented in a derived class.

virtual void	onStart (void)
	Called by the UI thread before the main event loop is entered. Can be implemented in a derived class.

virtual void	onFinish (void)
	Called by the UI thread after the main event loop exits. Can be implemented in a derived class.

virtual void	onTouchTimeout (bool expired)
	Called whenever the touch timeout expiration flag changes. Can be implemented in a derived class.

virtual void	onEventProcessStart (void)
	Called by the UI thread before processing an event. Can be implemented in a derived class.

virtual void	onEventProcessFinish (void)
	Called by the UI thread after processing an event. Can be implemented in a derived class.

void	enableCoalescePaintEvents (bool enabled)
	Enables or disables the coalescing of the paint events.

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

Protected Attributes
volatile bool	mDirty

volatile bool	mLocked

bool	mCoalescePaintEvents

uint8_t	mCoalescePaintEventsCounter

const uint32_t	mFrameBufferAlignment

DsSurface *	mFrontSurface

DsSurface *	mBackSurfaceActive

DsSurface *	mBackSurfacePending

DsRect	mSurfaceUserRect [3]

DsRenderer	mRenderer

DsRotation	mScreenRotation

Protected Attributes inherited from DsView
DsPoint	mScrollPosition

DsPoint	mPreviousScrollPosition

DsPoint	mScrollPositionBase

DsColor	mScrollbarColor

DsPoint	mTouchPos

uint32_t	mTouchTimestamp

Friends
class	DsView

Detailed Description

DsScreen is class of type DsView (inherits from DsView) that implements a physical screen.

DsScreen implements the following features:

Event loop
View stack
DsSurface allocator
On Screen Keyboard management
Lambda scheduler

Constructor & Destructor Documentation

◆ DsScreen()

DsScreen::DsScreen	(	int32_t	phys_width,
		int32_t	phys_height,
		DsRotation	rotation,
		DsColorMode	cmode,
		uint8_t *	linebuffer,
		uint8_t *	aa_linebuffer,
		uint32_t	framebuffer_alignment,
		bool	triple_buffered
	)

Creates a DsScreen object.

Parameters

phys_width	Physical width of the screen in pixels, in the memory orientation of the framebuffer (the orientation used by the LCD controller)
phys_height	Physical height of the screen in pixels, in the memory orientation of the framebuffer (the orientation used by the LCD controller)
rotation	The logical screen orientation. The screen will appear to all views as if it's rotated
cmode	Color mode used by the screen
linebuffer	Pointer to a memory buffer of size max(width, height) in bytes. It has to be aligned to 4 bytes. This is used by the AA renderer.
aa_linebuffer	Pointer to a memory buffer of size 2 * max(width, height) in bytes. It has to be aligned to 4 bytes.
framebuffer_alignment	This is the aligment to use when allocating framebuffers.
triple_buffered	Use tripple buffer mode instead of double buffer.

Member Function Documentation

◆ allocSurface()

DsSurface * DsScreen::allocSurface	(	int32_t	width,
		int32_t	height,
		DsColorMode	cmode,
		size_t	palette_size = `0`,
		bool	palette_has_alpha = `false`
	)

Allocates a DsSurface object using the screen's allocator and rotation.

Parameters

width	Width of the surface in pixels
height	Height of the surface in pixels
cmode	Color mode (ARGB888, RGB888, RGB565, ...)
palette_has_alpha	Does the palette contain the alpha channel?
palette_size	Number of entries in the color palette (if palette is not used the value does not matter)

◆ createKeyboard()

void DsScreen::createKeyboard ( const ds_bitmap_font_t * font )

Creates the on screen keyboard object.

Parameters

font	Font to use for the keyboard

◆ createRenderer()

DsRenderer DsScreen::createRenderer ( DsSurface & surface )

Creates a temporary DsRendered using the specified surface.

Parameters

surface Surface to create a temporary renderer for

Returns: Renderer object

◆ enableCoalescePaintEvents()

void DsScreen::enableCoalescePaintEvents ( bool enabled )

protected

Enables or disables the coalescing of the paint events.

If enabled, paint events that arrive in a burst are coalesced together and treated as a single pain event for a larger area. If disabled, each paint event is treated separately.

Parameters

enabled True to enable

◆ getFocusedView()

DsView * DsScreen::getFocusedView ( void ) const

Returns the focused view.

\retuen The focused view or nullptr if no view has focus.

◆ getKeyboard()

DsKeyboard & DsScreen::getKeyboard ( void )

Returns a reference to the on screen keyboard.

If the keyboard object has not been created, calling this method will return an invalid reference. This is undefined behavior.

Returns: Reference to the keyboard object

◆ getRotation()

DsRotation DsScreen::getRotation ( void ) const

Returns the logical rotation of the screen.

Returns: Logical rotation

◆ getView()

DsView * DsScreen::getView ( const char * id )

Returns the view based on its identifier.

Parameters

id	C string to use as identifier for accessing this view in the future

Returns: Requested view or nullptr if the identifier does not exist

◆ getViewStackSize()

size_t DsScreen::getViewStackSize ( void ) const

Returns the number of views in the view stack.

Returns: View stack size

◆ isTouchTimeoutExpired()

bool DsScreen::isTouchTimeoutExpired ( void ) const

Is the touch timer expired?

Returns: True if the touch timeout is expired. If the touch timeout is not enabled it returns false.

◆ isUiThread()

bool DsScreen::isUiThread ( void ) const

Returns true if the caller is running in the UI thread.

Returns: True if running in UI thread, false otherwise

◆ kickTouchTimeout()

void DsScreen::kickTouchTimeout ( uint32_t timeout_ms )

Kick the touch timeout while setting a new timeout value.

Parameters

timeout_ms New timeout in milliseconds. If zero, the touch timeout is disabled.

◆ lcdSurfaceUpdate()

virtual void DsScreen::lcdSurfaceUpdate ( DsSurface * surface )

protectedpure virtual

Updates the front framebuffer of the screen. Must be implemented in a derived class.

Parameters

surface The surface that needs to be pushed on the screen

◆ onFinish()

virtual void DsScreen::onFinish ( void )

protectedvirtual

Called by the UI thread after the main event loop exits. Can be implemented in a derived class.

Can be used to delete views or free any other resources used. Typically this will never be called in an embedded system.

◆ onStart()

virtual void DsScreen::onStart ( void )

protectedvirtual

Called by the UI thread before the main event loop is entered. Can be implemented in a derived class.

Can be used to create views, initialize hardware, ...

◆ onTouchTimeout()

virtual void DsScreen::onTouchTimeout ( bool expired )

protectedvirtual

Called whenever the touch timeout expiration flag changes. Can be implemented in a derived class.

It is used to turn the screen off, reduce brightnes or do anything required whenever the touch timeout expires.

Parameters

expired True if the touch timer expired. This can be uses to turn the screen off or reduce it's brightness. False if the touch timer was expired but the system is required to turn the screen back on or increase the brightness.

◆ popView() [1/2]

bool DsScreen::popView ( const char * id )

Pops the top named view from the stack.

Popping a view will hide it and make the previous view in the stack visible. The view at the top of the stack will only be popped if it's ID matches the supplied ID.

Parameters

id	C string identifier of the view

Returns: True if the view was found and popped, false if the top view does not match the 'id' parameter

◆ popView() [2/2]

bool DsScreen::popView ( void )

Pops the top view from the stack.

Popping a view will hide it and make the previous view in the stack visible.

Returns: True if the view was popped, false if the view stack is empty

◆ pushView()

bool DsScreen::pushView	(	const char *	id,
		bool	on_top = `false`
	)

Pushes a new view to the stack.

When pushing a view, the previous view will be hidden and the new view will become visible. If on_top is true, the previous view will stay visible.

Parameters

id	C string identifier of the view
on_top	True if the new view will appear on top of the old one

Returns: True if the view was found and made visible, false otherwise

◆ queueKeyboardEvent()

void DsScreen::queueKeyboardEvent ( int32_t key )

Queues a keyboard event into the event loop.

Parameters

key	ASCII code of the key

◆ queueLambda()

void DsScreen::queueLambda ( const lambda< void(void), 64 > & lambda )

Queues a lambda to get executed in the UI thread event loop.

Parameters

lambda Lambda of type void(void)

◆ queueLambdaFromISR()

void DsScreen::queueLambdaFromISR	(	const lambda< void(void), 64 > &	lambda,
		int32_t *	woken
	)

Queues a lambda to get executed in the UI thread event loop. It can be used from an interrupt handler.

Parameters

	lambda	Lambda of type `void(void)`
[out]	woken	Will be set to true if a task will be woken as a result of this call

◆ queueTouchEvent()

void DsScreen::queueTouchEvent	(	const DsTouchEvent::Mode &	mode,
		const DsPoint &	pos,
		uint32_t	timestamp
	)

Queues a touch event into the event loop.

Parameters

mode	Touch mode
pos	Touch position
timestamp	Touch timestamp in milliseconds

◆ queueTouchEventFromISR()

void DsScreen::queueTouchEventFromISR	(	const DsTouchEvent::Mode &	mode,
		const DsPoint &	pos,
		uint32_t	timestamp,
		int32_t *	woken
	)

Queues a touch event into the event loop. It can be used from an interrupt handler.

Parameters

	mode	Touch mode
	pos	Touch position
	timestamp	Touch timestamp in milliseconds
[out]	woken	Will be set to true if a task will be woken as a result of this call

◆ queueVSyncEventFromISR()

void DsScreen::queueVSyncEventFromISR ( int32_t * woken )

Queues an screen vertical sync event into the event loop. It can be used from an interrupt handler.

Parameters

[out] woken Will be set to true if a task will be woken as a result of this call

◆ registerView()

void DsScreen::registerView	(	DsView *	view,
		const char *	id
	)

Registers a view with the view stack manager.

Parameters

view	View to register
id	C string to use as identifier for accessing this view in the future

◆ run()

void DsScreen::run ( void )

Executes the event loop.

This method will not return until an EXIT event is processed.

◆ setFocusedView()

void DsScreen::setFocusedView ( DsView * view )

Sets the focused view.

Parameters

view	View to bring focus to or nullptr to take focus away from all views.

◆ topViewIs()

bool DsScreen::topViewIs ( const char * id )

Returns true if the view on the top of the stack has the specified id.

Parameters

id	C string identifier of the view

Returns: True if the top view has the specified ID

◆ unrollViewStack() [1/2]

bool DsScreen::unrollViewStack ( const char * id )

Unrolls the view stack to a specific view ID.

Parameters

id	C string identifier of the view

Returns: True if the specified view exists in the stack and the stack was unrolled. False otherwise.

◆ unrollViewStack() [2/2]

bool DsScreen::unrollViewStack ( size_t level )

Unrolls the view stack to a specific level.

Parameters

level Number of levels to leave in the stack. Passing zero will empty the stack.

Returns: True if the the stack was unrolled. False otherwise.

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

inc/ds_screen.h

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ DsScreen()

Member Function Documentation

◆ allocSurface()

◆ createKeyboard()

◆ createRenderer()

◆ enableCoalescePaintEvents()

◆ getFocusedView()

◆ getKeyboard()

◆ getRotation()

◆ getView()

◆ getViewStackSize()

◆ isTouchTimeoutExpired()

◆ isUiThread()

◆ kickTouchTimeout()

◆ lcdSurfaceUpdate()

◆ onFinish()

◆ onStart()

◆ onTouchTimeout()

◆ popView() [1/2]

◆ popView() [2/2]

◆ pushView()

◆ queueKeyboardEvent()

◆ queueLambda()

◆ queueLambdaFromISR()

◆ queueTouchEvent()

◆ queueTouchEventFromISR()

◆ queueVSyncEventFromISR()

◆ registerView()

◆ run()

◆ setFocusedView()

◆ topViewIs()

◆ unrollViewStack() [1/2]

◆ unrollViewStack() [2/2]