Application states

Most Cascades applications have a similar lifecycle, which includes three possible states: fullscreen, thumbnail, and invisible. Depending on the permissions granted to your app, these states can mean different things in regards to whether an application is running or not.


In the fullscreen state, the application is running in the foreground and can use all the resources that it requires in terms of memory allocation and processor time.

When the app enters this state, the fullscreen() signal is emitted.

Screen showing a fullscreen Cascades app.


In the thumbnail state, the application is running in the background as an Active Frame. By default, the Active Frame image (also called the cover) is a scaled-down version of what the app's UI looked like when it was sent to the background. However, it's recommended that you create your own Active Frames if you want to add that bit of extra flare to your app.

When your app is in this state, it should stop any extraneous processing and use only the resources it needs to update the cover. Your app should stop other threads, such as networking and data access threads, that aren't required when running in the background.

When the app enters this state, the thumbnail() signal is emitted.

Screen showing a thumbnailed Cascades app.


In the invisible state, the app (and its Active Frame) are no longer visible on the screen. The app might enter this state if the device backlight is off or if another app is brought to the foreground.

When your app is in this state and doesn't have permission to run in the background, it is stopped and won't receive any processing time. If your app has permission to run in the background, your app should stop any rendering operations (for example, updating the UI) and any other unnecessary operations. Your app should listen only for the events that it needs to respond to and process these events when they occur.

When the app enters this state, the invisible() signal is emitted.

Screen showing an invisible Cascades app.

Allowing your app to run in the background

Most apps do all their work while they're running in the foreground, in response to some sort of user input. However, sometimes it's necessary for your app to also be able perform actions in the background, when it's running as an Active Frame. This type of app might listen for a particular event to occur on the device and then respond by notifying the user. All applications have this capability, provided that the Active Frame is currently visible to the user.

If the Active Frame is not visible, the application enters the invisible state. By default, processor time isn't allocated to apps that are in this state, and this approach helps to minimize battery power consumption and maximize the performance of the device. To allow an app to continue running while it's not visible, you need to specify the run_when_backgrounded permission in your project's bar-descriptor.xml file.


The following diagram shows how an application can move from state to state:

A diagram that illustrates the application lifecycle for Cascades apps.

Headless applications

Headless apps are another type of application that is able to run in the background. A headless app is made up of two parts: a UI application and a headless process that runs in the background. Typically, the headless process works in cooperation with the UI, performing some sort of task in the background and notifying the user when an event occurs.

Headless apps have a different lifecycle than standard applications. For more information about headless apps and their application states, see Headless apps.

Closing your app

When a user closes your app, you might want to perform some final clean-up operations before the app closes. For example, you can save the user's data, shut down your threads in a particular way, or close database or network connections manually. The Application class includes several functions and signals that you can use to detect the termination of your app and delay it long enough to perform any final tasks your app needs.


The setAutoExit(bool autoExit) function sets the value of the autoExit property, which indicates whether your app should close automatically or should receive a signal when a user closes your app. If you set this property to false using this function, your app receives the manualExit() signal (described below) when a user closes your app. You should remember that if you set the autoExit property to false, you must call quit() to terminate the app when you finish any final clean-up operations.


The manualExit() signal is emitted if the autoExit property is set to false by calling setAutoExit(). Your app can respond to this signal and perform any clean-up operations that are required before closing. After this signal is emitted, your app has a short amount of time (approximately three seconds) to perform any final tasks and terminate itself before the operating system terminates it forcibly. You can request more time to complete your tasks by calling extendTerminationTimeout().


The extendTerminationTimeout() function requests additional time to perform clean-up operations before your app is terminated forcibly. When you call this function, your app has about two seconds to finish its tasks and terminate itself. Note that calling this function doesn't add two seconds to the existing timeout period. Instead, it resets the timeout period to two seconds from the time this function is called. You can call this function as many times as you need to extend the timeout period.

Last modified: 2014-11-17

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus