States that an application can be in once it is running.
States not supported on a platform will be synthesized by the framework when transitioning between states which are supported, so that all implementations share the same state machine.
For historical and name collision reasons, Flutter's application state names
do not correspond one to one with the state names on all platforms. On
Android, for instance, when the OS calls
Flutter will enter the inactive state, but when Android calls
Flutter enters the paused state. See the individual state's documentation
for descriptions of what they mean on each platform.
The current application state can be obtained from
SchedulerBinding.instance.lifecycleState, and changes to the state can be
observed by creating an AppLifecycleListener, or by using a
WidgetsBindingObserver by overriding the
Applications should not rely on always receiving all possible notifications.
For example, if the application is killed with a task manager, a kill signal, the user pulls the power from the device, or there is a rapid unscheduled disassembly of the device, no notification will be sent before the application is suddenly terminated, and some states may be skipped.
- AppLifecycleListener, an object used observe the lifecycle state that provides state transition callbacks.
- WidgetsBindingObserver, for a mechanism to observe the lifecycle state from the widgets layer.
- iOS's IOKit activity lifecycle documentation.
- Android's activity lifecycle documentation.
- macOS's AppKit activity lifecycle documentation.
- detached → const AppLifecycleState
The application is still hosted by a Flutter engine but is detached from any host views.
The application defaults to this state before it initializes, and can be in this state (on Android and iOS only) after all views have been detached.
When the application is in this state, the engine is running without a view.
This state is only entered on iOS and Android, although on all platforms it is the default state before the application begins running.
- resumed → const AppLifecycleState
On all platforms, this state indicates that the application is in the default running mode for a running application that has input focus and is visible.
On Android, this state corresponds to the Flutter host view having focus (
Activity.onWindowFocusChangedwas called with true) while in Android's "resumed" state. It is possible for the Flutter app to be in the inactive state while still being in Android's "onResume" state if the app has lost focus (
Activity.onWindowFocusChangedwas called with false), but hasn't had
Activity.onPausecalled on it.
On iOS and macOS, this corresponds to the app running in the foreground active state.
- inactive → const AppLifecycleState
At least one view of the application is visible, but none have input focus. The application is otherwise running normally.
On non-web desktop platforms, this corresponds to an application that is not in the foreground, but still has visible windows.
On the web, this corresponds to an application that is running in a window or tab that does not have input focus.
On iOS and macOS, this state corresponds to the Flutter host view running in the foreground inactive state. Apps transition to this state when in a phone call, when responding to a TouchID request, when entering the app switcher or the control center, or when the UIViewController hosting the Flutter app is transitioning.
On Android, this corresponds to the Flutter host view running in Android's paused state (i.e.
Activity.onPausehas been called), or in Android's "resumed" state (i.e.
Activity.onResumehas been called) but does not have window focus. Examples of when apps transition to this state include when the app is partially obscured or another activity is focused, a app running in a split screen that isn't the current app, an app interrupted by a phone call, a picture-in-picture app, a system dialog, another view. It will also be inactive when the notification window shade is down, or the application switcher is visible.
All views of an application are hidden, either because the application is about to be paused (on iOS and Android), or because it has been minimized or placed on a desktop that is no longer visible (on non-web desktop), or is running in a window or tab that is no longer visible (on the web).
On iOS and Android, in order to keep the state machine the same on all platforms, a transition to this state is synthesized before the paused state is entered when coming from inactive, and before the inactive state is entered when coming from paused. This allows cross-platform implementations that want to know when an app is conceptually "hidden" to only write one handler.
- paused → const AppLifecycleState
The application is not currently visible to the user, and not responding to user input.
This state is only entered on iOS and Android.