Skip to main content
Version: 4.16

Application

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

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

Public Functions#

DebugPrinter *getDebugPrinter()
Returns the DebugPrinter object associated with the application.
Application *getInstance()
Gets the single instance application.
voidinvalidateDebugRegion()
Sets the debug string to be displayed onscreen on top of the framebuffer.
voidsetDebugPrinter(DebugPrinter * printer)
Sets the DebugPrinter object to be used by the application to print debug messages.
voidsetDebugString(const char * string)
Sets the debug string to be displayed onscreen on top of the framebuffer.
virtual voidappSwitchScreen(uint8_t screenId)
An application specific function for switching screen.
virtual voidcacheDrawOperations(bool enableCache)
This function allows for deferring draw operations to a later time.
voidclearAllTimerWidgets()
Clears all currently registered timer widgets.
voidcopyInvalidatedAreasFromTFTToClientBuffer()
This function copies the parts that were updated in the previous frame (in the tft buffer) to the active framebuffer (client buffer).
virtual voiddraw()
Initiate a draw operation of the entire screen.
virtual voiddraw(Rect & rect)
Initiate a draw operation of the specified region of the screen.
Screen *getCurrentScreen()
Gets the current screen.
uint16_tgetNumberOfRegisteredTimerWidgets() const
gets the number of timer widgets that has been registered.
uint16_tgetTimerWidgetCountForDrawable(const Drawable * w) const
Gets the number of timer events registered to a widget, i.e.
virtual voidhandleClickEvent(const ClickEvent & evt)
Handle a click event.
virtual voidhandleDragEvent(const DragEvent & evt)
Handle drag events.
virtual voidhandleGestureEvent(const GestureEvent & evt)
Handle gestures.
virtual voidhandleKeyEvent(uint8_t c)
Handle an incoming character received by the HAL layer.
virtual voidhandlePendingScreenTransition()
Evaluates the pending Callback instances.
virtual voidhandleTickEvent()
Handle tick.
voidregisterTimerWidget(Drawable * w)
Adds a widget to the list of widgets receiving ticks every frame (typically 16.67ms)
virtual voidrequestRedraw()
An application specific function for requesting redraw of entire screen.
virtual voidrequestRedraw(Rect & rect)
An application specific function for requesting redraw of given Rect.
virtual voidswitchScreen(Screen * newScreen)
Switch to another Screen.
voidunregisterTimerWidget(const Drawable * w)
Removes a widget from the list of widgets receiving ticks every frame (typically 16.67ms) milliseconds.

Protected Functions#

Application()
Protected constructor.
voidinvalidateArea(Rect area)
Invalidates this area.

Public Attributes#

const uint8_tMAX_TIMER_WIDGETS
Maximum number of widgets receiving ticks.
const uint16_tTICK_INTERVAL_MS
Deprecated, do not use this constant. Tick interval depends on VSYNC of your target platform.

Protected Attributes#

RectVector_tcachedDirtyAreas
When draw caching is enabled, these rects keeps track of the dirty screen area.
booldrawCacheEnabled
True when draw caching is active.
RectVector_tlastRects
The dirty areas from last frame that needs to be redrawn because we have swapped frame buffers.
Rectredraw
Rect describing application requested invalidate area.
uint8_ttimerWidgetCounter
A counter for each potentially registered timer widget. Increase when registering for timer events, decrease when unregistering.
Vector< Drawable *, MAX_TIMER_WIDGETS >timerWidgets
List of widgets that receive timer ticks.
booltransitionHandled
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.
RectdebugRegionInvalidRect
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#

getDebugPrinter#

static DebugPrinter * getDebugPrinter()

Returns the DebugPrinter object associated with the application.

Returns:

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:
printerThe 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:
stringThe debug string to display onscreen.

appSwitchScreen#

virtual void appSwitchScreen(uint8_tscreenId)

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:
screenIdAn id that maps to the desired screen.

cacheDrawOperations#

virtual void cacheDrawOperations(boolenableCache)

This function allows for deferring draw operations to a later time.

If active, calls to draw will simply note that the specified area is dirty, but not perform any actual drawing. When disabling the draw cache, the dirty area will be flushed (drawn) immediately.

Parameters:
enableCacheif true, all future draw operations will be cached. If false draw caching is disabled, and the current cache (if not empty) is drawn immediately.

clearAllTimerWidgets#

Clears all currently registered timer widgets.

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.

draw#

virtual void draw()

Initiate a draw operation of the entire screen.

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

Deprecated

Use draw(Rect&)

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

getCurrentScreen#

Screen * getCurrentScreen()

Gets the current screen.

Returns:

The current screen.

getNumberOfRegisteredTimerWidgets#

gets the number of timer widgets that has been registered.

Returns:

The size of timerWidgets.

getTimerWidgetCountForDrawable#

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:
wThe 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 &evt)

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:
evtThe ClickEvent.

Reimplements: touchgfx::UIEventListener::handleClickEvent

handleDragEvent#

virtual void handleDragEvent(const DragEvent &evt)

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:
evtThe drag event, expressed in absolute coordinates.

Reimplements: touchgfx::UIEventListener::handleDragEvent

handleGestureEvent#

virtual void handleGestureEvent(const GestureEvent &evt)

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:
evtThe gesture event.

Reimplements: touchgfx::UIEventListener::handleGestureEvent

handleKeyEvent#

virtual void handleKeyEvent(uint8_tc)

Handle an incoming character received by the HAL layer.

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

Parameters:
cThe incomming character to handle.

Reimplements: touchgfx::UIEventListener::handleKeyEvent

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

registerTimerWidget#

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

Parameters:
wThe widget to add.
Note

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

See also:

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:
rectThe 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:
newScreenA pointer to the new screen.

unregisterTimerWidget#

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

Parameters:
wThe 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#

Protected constructor.

invalidateArea#

void invalidateArea(Rectarea)

Invalidates this area.

Parameters:
areaThe area to invalidate.

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.

drawCacheEnabled#

bool drawCacheEnabled

True when draw caching is active.

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.

timerWidgetCounter#

uint8_t timerWidgetCounter

A counter for each potentially registered timer widget. Increase when registering for timer events, decrease when unregistering.

timerWidgets#

Vector< Drawable *, MAX_TIMER_WIDGETS > timerWidgets

List of widgets that receive timer ticks.

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.