Application

touchgfx/Application.hpp

The Application class is the main interface for manipulating screen contents. It holds a pointer to the currently displayed Screen, and delegates draw requests and events to that Screen. Additionally it contains some global application settings.

Inherits from: UIEventListener

Inherited by: MVPApplication

Protected Classes

class	TimerWidgets
	A class to handle and manage timer widgets.

Protected Types

typedef Vector< Rect, 8 >	RectVector_t
	Type to ensure the same number of rects are in the Vector.

Public Functions

Screen *	getCurrentScreen()
	Gets the current screen.
DebugPrinter *	getDebugPrinter()
	Returns the DebugPrinter object associated with the application.
Application *	getInstance()
	Gets the single instance application.
void	invalidateDebugRegion()
	Sets the debug string to be displayed onscreen on top of the framebuffer.
void	setDebugPrinter(DebugPrinter * printer)
	Sets the DebugPrinter object to be used by the application to print debug messages.
void	setDebugString(const char * string)
	Sets the debug string to be displayed onscreen on top of the framebuffer.
virtual void	appSwitchScreen(uint8_t screenId)
	An application specific function for switching screen.
virtual void	changeToStartScreen()
	This function can be called to send your application back to the start screen.
void	clearAllTimerWidgets()
	Clears all currently registered timer widgets.
virtual void	clearCachedAreas()
	Clears the cached areas so coming calls to invalidate are collected for future drawing.
void	copyInvalidatedAreasFromTFTToClientBuffer()
	This function copies the parts that were updated in the previous frame (in the TFT buffer) to the active framebuffer (client buffer).
virtual void	drawCachedAreas()
	Draws all cached, invalidated areas on the screen.
const Vector< Rect, 8 > &	getInvalidatedAreas()
	Get list of the invalidated areas in the current frame.
uint16_t	getNumberOfRegisteredTimerWidgets() const
	gets the number of timer widgets that are registered and active.
uint16_t	getTimerWidgetCountForDrawable(const Drawable * w) const
	Gets the number of timer events registered to a widget, i.e.
virtual void	handleClickEvent(const ClickEvent & event)
	Handle a click event.
virtual void	handleDragEvent(const DragEvent & event)
	Handle drag events.
virtual void	handleGestureEvent(const GestureEvent & event)
	Handle gestures.
virtual void	handleKeyEvent(uint8_t c)
	Handle an incoming character received by the HAL layer.
virtual void	handlePendingScreenTransition()
	Evaluates the pending Callback instances.
virtual void	handleTickEvent()
	Handle tick.
virtual void	invalidate()
	Invalidates the entire screen.
virtual void	invalidateArea(Rect area)
	Invalidates the given area.
void	registerTimerWidget(Drawable * w)
	Adds a widget to the list of widgets receiving ticks every frame (typically 16.67ms)
virtual void	requestRedraw()
	An application specific function for requesting redraw of entire screen.
virtual void	requestRedraw(Rect & rect)
	An application specific function for requesting redraw of given Rect.
virtual void	switchScreen(Screen * newScreen)
	Switch to another Screen.
void	unregisterTimerWidget(const Drawable * w)
	Removes a widget from the list of widgets receiving ticks every frame (typically 16.67ms) milliseconds.

Protected Functions

	Application()
	Protected constructor.
virtual void	draw()
	Initiate a draw operation of the entire screen.
virtual void	draw(Rect & rect)
	Initiate a draw operation of the specified region of the screen.

Public Attributes

const uint8_t	MAX_TIMER_WIDGETS
	Maximum number of widgets receiving ticks.
const uint16_t	TICK_INTERVAL_MS
	Deprecated, do not use this constant. Tick interval depends on VSYNC of your target platform.

Protected Attributes

RectVector_t	cachedDirtyAreas
	When draw caching is enabled, these rects keeps track of the dirty screen area.
RectVector_t	lastRects
	The dirty areas from last frame that needs to be redrawn because we have swapped frame buffers.
Rect	redraw
	Rect describing application requested invalidate area.
class touchgfx::Application::TimerWidgets	timerWidgets
	The timer widgets.
bool	transitionHandled
	True if the transition is done and Screen::afterTransition has been called.
Screen *	currentScreen
	Pointer to currently displayed Screen.
Transition *	currentTransition
	Pointer to current transition.
DebugPrinter *	debugPrinter
	Pointer to the DebugPrinter instance.
Rect	debugRegionInvalidRect
	Invalidated Debug Region.
Application *	instance
	Pointer to the instance of the Application-derived subclass.

Additional inherited members

Public Functions inherited from UIEventListener

virtual	~UIEventListener()
	Finalizes an instance of the UIEventListener class.

Protected Types Documentation

RectVector_t

typedef Vector< Rect, 8 > RectVector_t

Type to ensure the same number of rects are in the Vector.

Public Functions Documentation

getCurrentScreen

static Screen * getCurrentScreen	(			)

Gets the current screen.

Returns:

The current screen.

getDebugPrinter

static DebugPrinter * getDebugPrinter	(			)

Returns the DebugPrinter object associated with the application.

Returns:

DebugPrinter The DebugPrinter object.

getInstance

static Application * getInstance	(			)

Gets the single instance application.

Returns:

The instance of this application.

invalidateDebugRegion

static void invalidateDebugRegion	(			)

Sets the debug string to be displayed onscreen on top of the framebuffer.

setDebugPrinter

static void setDebugPrinter	(	DebugPrinter *	printer	)

Sets the DebugPrinter object to be used by the application to print debug messages.

Parameters:

printer	The debug printer to configure.

setDebugString

static void setDebugString	(	const char *	string	)

Sets the debug string to be displayed onscreen on top of the framebuffer.

Parameters:

string	The debug string to display onscreen.

appSwitchScreen

virtual void appSwitchScreen	(	uint8_t	screenId	)

An application specific function for switching screen.

Overloading this can provide a means to switch screen from places that does not have access to a pointer to the new screen. Base implementation is empty.

Parameters:

screenId	An id that maps to the desired screen.

changeToStartScreen

virtual void changeToStartScreen	(			)

This function can be called to send your application back to the start screen.

The simulator will call this function when F5 is pressed. To make this work, please implement this function in FrontendApplication.

Note

The application will not make a complete restart - if your Model contains data, this will not be reset, unless this is explicitly done in your FrontendApplication::changeToStartScreen().

clearAllTimerWidgets

void clearAllTimerWidgets	(			)

Clears all currently registered timer widgets.

clearCachedAreas

virtual void clearCachedAreas	(			)

Clears the cached areas so coming calls to invalidate are collected for future drawing.

See also:

drawCachedAreas

copyInvalidatedAreasFromTFTToClientBuffer

void copyInvalidatedAreasFromTFTToClientBuffer	(			)

This function copies the parts that were updated in the previous frame (in the TFT buffer) to the active framebuffer (client buffer).

This function only copies pixels in double buffering mode.

drawCachedAreas

virtual void drawCachedAreas	(			)

Draws all cached, invalidated areas on the screen.

See also:

clearCachedAreas

getInvalidatedAreas

const Vector< Rect, 8 > & getInvalidatedAreas	(			)

Get list of the invalidated areas in the current frame.

The list is cleared in the beginning of HAL::tick.

The list can be usefull on some platforms where the information can be used to reduce the amount of pixels sent to the display.

Returns:

Const reference to the list.

getNumberOfRegisteredTimerWidgets

uint16_t getNumberOfRegisteredTimerWidgets	(			)	const

gets the number of timer widgets that are registered and active.

Returns:

The size of timerWidgets.

getTimerWidgetCountForDrawable

uint16_t getTimerWidgetCountForDrawable	(	const Drawable *	w	)

Gets the number of timer events registered to a widget, i.e.

how many times a drawable must be unregistered until it no longer receives timer ticks.

Parameters:

w	The widget to to get count from.

Returns:

0 if the drawable is not registered as a timer widget, otherwise returns how many times the drawable is currently registered.

handleClickEvent

virtual void handleClickEvent	(	const ClickEvent &	event	)

Handle a click event.

Standard implementation is to delegate the event to the current screen. Called by the framework when a click is detected by some platform specific means.

Parameters:

event	The ClickEvent.

Reimplements: touchgfx::UIEventListener::handleClickEvent

handleDragEvent

virtual void handleDragEvent	(	const DragEvent &	event	)

Handle drag events.

Called by the framework when a drag is detected by some platform specific means. Standard implementation is to delegate drag event to current screen.

Parameters:

event	The drag event, expressed in absolute coordinates.

Reimplements: touchgfx::UIEventListener::handleDragEvent

handleGestureEvent

virtual void handleGestureEvent	(	const GestureEvent &	event	)

Handle gestures.

Called by the framework when a gesture is detected by some platform specific means. Standard implementation is to delegate drag event to current screen.

Parameters:

event	The gesture event.

Reimplements: touchgfx::UIEventListener::handleGestureEvent

handleKeyEvent

virtual void handleKeyEvent	(	uint8_t	c	)

Handle an incoming character received by the HAL layer.

Standard implementation delegates to current screen (which, in turn, does nothing).

Parameters:

c	The incoming character to handle.

Reimplements: touchgfx::UIEventListener::handleKeyEvent

handlePendingScreenTransition

virtual void handlePendingScreenTransition	(			)

Evaluates the pending Callback instances.

If a callback is valid, it is executed and a Screen transition is executed. This base implementation is empty and does nothing.

Reimplements: touchgfx::UIEventListener::handlePendingScreenTransition

Reimplemented by: touchgfx::MVPApplication::handlePendingScreenTransition

handleTickEvent

virtual void handleTickEvent	(			)

Handle tick.

Standard implementation is to delegate tick to the widgets that have registered to receive one. Called by some platform specific means.

Reimplements: touchgfx::UIEventListener::handleTickEvent

invalidate

virtual void invalidate	(			)

Invalidates the entire screen.

invalidateArea

virtual void invalidateArea	(	Rect	area	)

Invalidates the given area.

Parameters:

area	The area to invalidate.

registerTimerWidget

void registerTimerWidget	(	Drawable *	w	)

Adds a widget to the list of widgets receiving ticks every frame (typically 16.67ms)

Parameters:

w	The widget to add.

Note

The framework keeps track of the number of times a specific widget is registered.

See also:

unregisterTimerWidget

requestRedraw

virtual void requestRedraw	(			)

An application specific function for requesting redraw of entire screen.

requestRedraw

virtual void requestRedraw	(	Rect &	rect	)

An application specific function for requesting redraw of given Rect.

Parameters:

rect	The Rect that must be redrawn.

switchScreen

virtual void switchScreen	(	Screen *	newScreen	)

Switch to another Screen.

Will call tearDownScreen on current Screen before switching, and subsequently call setupScreen and draw automatically for the new Screen.

Parameters:

newScreen	A pointer to the new screen.

unregisterTimerWidget

void unregisterTimerWidget	(	const Drawable *	w	)

Removes a widget from the list of widgets receiving ticks every frame (typically 16.67ms) milliseconds.

Parameters:

w	The widget to remove.

Note

If widget has been registered multiple times, an equal number of calls to unregister are required to stop widget from receiving tick events.

Protected Functions Documentation

Application

Application	(			)

Protected constructor.

draw

virtual void draw	(			)

Initiate a draw operation of the entire screen.

Standard implementation is to delegate draw request to the current Screen.

draw

virtual void draw	(	Rect &	rect	)

Initiate a draw operation of the specified region of the screen.

Standard implementation is to delegate draw request to the current Screen.

Parameters:

rect	The area to draw.

Note

Unlike Widget::draw this is safe to call from user code as it will properly traverse widgets in z-order. The coordinates given must be absolute coordinates.

Public Attributes Documentation

MAX_TIMER_WIDGETS

const uint8_t MAX_TIMER_WIDGETS = 32

Maximum number of widgets receiving ticks.

TICK_INTERVAL_MS

const uint16_t TICK_INTERVAL_MS = 10

Deprecated, do not use this constant. Tick interval depends on VSYNC of your target platform.

Protected Attributes Documentation

cachedDirtyAreas

RectVector_t cachedDirtyAreas

When draw caching is enabled, these rects keeps track of the dirty screen area.

lastRects

RectVector_t lastRects

The dirty areas from last frame that needs to be redrawn because we have swapped frame buffers.

redraw

Rect redraw

Rect describing application requested invalidate area.

timerWidgets

class touchgfx::Application::TimerWidgets timerWidgets

The timer widgets.

transitionHandled

bool transitionHandled

True if the transition is done and Screen::afterTransition has been called.

currentScreen

Screen * currentScreen

Pointer to currently displayed Screen.

currentTransition

Transition * currentTransition

Pointer to current transition.

debugPrinter

DebugPrinter * debugPrinter

Pointer to the DebugPrinter instance.

debugRegionInvalidRect

Rect debugRegionInvalidRect

Invalidated Debug Region.

instance

Application * instance

Pointer to the instance of the Application-derived subclass.