Package io.flutter.embedding.engine

# Class FlutterEngine

java.lang.Object
io.flutter.embedding.engine.FlutterEngine

All Implemented Interfaces:
  `ViewUtils.DisplayUpdater`

public class FlutterEngine extends Object implements ViewUtils.DisplayUpdater
A single Flutter execution environment.

The `FlutterEngine` is the container through which Dart code can be run in an Android application.

Dart code in a `FlutterEngine` can execute in the background, or it can be render to the screen by using the accompanying `FlutterRenderer` and Dart code using the Flutter framework on the Dart side. Rendering can be started and stopped, thus allowing a `FlutterEngine` to move from UI interaction to data-only processing and then back to UI interaction.

Multiple `FlutterEngine`s may exist, execute Dart code, and render UIs within a single Android app. For better memory performance characteristics, construct multiple `FlutterEngine`s via `FlutterEngineGroup` rather than via `FlutterEngine`'s constructor directly.

To start running Dart and/or Flutter within this `FlutterEngine`, get a reference to this engine's `DartExecutor` and then use `DartExecutor.executeDartEntrypoint(DartExecutor.DartEntrypoint)`. The `DartExecutor.executeDartEntrypoint(DartExecutor.DartEntrypoint)` method must not be invoked twice on the same `FlutterEngine`.

To start rendering Flutter content to the screen, use `getRenderer()` to obtain a `FlutterRenderer` and then attach a `RenderSurface`. Consider using a `FlutterView` as a `RenderSurface`.

Instatiating the first `FlutterEngine` per process will also load the Flutter engine's native library and start the Dart VM. Subsequent `FlutterEngine`s will run on the same VM instance but will have their own Dart Isolate when the `DartExecutor` is run. Each Isolate is a self-contained Dart environment and cannot communicate with each other except via Isolate ports.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `FlutterEngine.EngineLifecycleListener`
  Lifecycle callbacks for Flutter engine lifecycle events.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FlutterEngine(Context context)`
  Constructs a new `FlutterEngine`.
  `FlutterEngine(Context context, FlutterLoader flutterLoader, FlutterJNI flutterJNI)`
  Same as `FlutterEngine(Context, FlutterLoader, FlutterJNI, String[], boolean)` but with no Dart VM flags and automatically registers plugins.
  `FlutterEngine(Context context, FlutterLoader flutterLoader, FlutterJNI flutterJNI, PlatformViewsController platformViewsController, String[] dartVmArgs, boolean automaticallyRegisterPlugins)`
  Same as `FlutterEngine(Context, FlutterLoader, FlutterJNI, String[], boolean)`, plus the ability to provide a custom `PlatformViewsController`.
  `FlutterEngine(Context context, FlutterLoader flutterLoader, FlutterJNI flutterJNI, PlatformViewsController platformViewsController, String[] dartVmArgs, boolean automaticallyRegisterPlugins, boolean waitForRestorationData)`
  Fully configurable `FlutterEngine` constructor.
  `FlutterEngine(Context context, FlutterLoader flutterLoader, FlutterJNI flutterJNI, PlatformViewsController platformViewsController, String[] dartVmArgs, boolean automaticallyRegisterPlugins, boolean waitForRestorationData, FlutterEngineGroup group)`
  `FlutterEngine(Context context, FlutterLoader flutterLoader, FlutterJNI flutterJNI, String[] dartVmArgs, boolean automaticallyRegisterPlugins)`
  Same as `FlutterEngine(Context, FlutterLoader, FlutterJNI)`, plus Dart VM flags in `dartVmArgs`, and control over whether plugins are automatically registered with this `FlutterEngine` in `automaticallyRegisterPlugins`.
  `FlutterEngine(Context context, String[] dartVmArgs)`
  Same as `FlutterEngine(Context)` with added support for passing Dart VM arguments.
  `FlutterEngine(Context context, String[] dartVmArgs, boolean automaticallyRegisterPlugins)`
  Same as `FlutterEngine(Context)` with added support for passing Dart VM arguments and avoiding automatic plugin registration.
  `FlutterEngine(Context context, String[] dartVmArgs, boolean automaticallyRegisterPlugins, boolean waitForRestorationData)`
  Same as `FlutterEngine(Context, String[], boolean)` with added support for configuring whether the engine will receive restoration data.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addEngineLifecycleListener(FlutterEngine.EngineLifecycleListener listener)`
  Adds a `listener` to be notified of Flutter engine lifecycle events, e.g., `onPreEngineStart()`.
  `void`
  `destroy()`
  Cleans up all components within this `FlutterEngine` and destroys the associated Dart Isolate.
  `static FlutterEngine`
  `engineForId(long handle)`
  Returns engine for the given identifier or null if identifier is not valid.
  `AccessibilityChannel`
  `getAccessibilityChannel()`
  System channel that sends accessibility requests and events from Flutter to Android.
  `ActivityControlSurface`
  `getActivityControlSurface()`
  `BackGestureChannel`
  `getBackGestureChannel()`
  System channel that sends back gesture commands from Android to Flutter.
  `BroadcastReceiverControlSurface`
  `getBroadcastReceiverControlSurface()`
  `ContentProviderControlSurface`
  `getContentProviderControlSurface()`
  `DartExecutor`
  `getDartExecutor()`
  The Dart execution context associated with this `FlutterEngine`.
  `DeferredComponentChannel`
  `getDeferredComponentChannel()`
  System channel that allows manual installation and state querying of deferred components.
  `long`
  `getEngineId()`
  Returns unique identifier for this engine.
  `LifecycleChannel`
  `getLifecycleChannel()`
  System channel that sends Android lifecycle events to Flutter.
  `LocalizationChannel`
  `getLocalizationChannel()`
  System channel that sends locale data from Android to Flutter.
  `io.flutter.plugin.localization.LocalizationPlugin`
  `getLocalizationPlugin()`
  The LocalizationPlugin this FlutterEngine created.
  `MouseCursorChannel`
  `getMouseCursorChannel()`
  System channel that sends and receives text input requests and state.
  `NavigationChannel`
  `getNavigationChannel()`
  System channel that sends Flutter navigation commands from Android to Flutter.
  `PlatformChannel`
  `getPlatformChannel()`
  System channel that sends platform-oriented requests and information to Flutter, e.g., requests to play sounds, requests for haptics, system chrome settings, etc.
  `PlatformViewsController`
  `getPlatformViewsController()`
  `PlatformViewsController`, which controls all platform views running within this `FlutterEngine`.
  `PlatformViewsController2`
  `getPlatformViewsController2()`
  `PluginRegistry`
  `getPlugins()`
  Plugin registry, which registers plugins that want to be applied to this `FlutterEngine`.
  `ProcessTextChannel`
  `getProcessTextChannel()`
  System channel that sends text processing requests from Flutter to Android.
  `FlutterRenderer`
  `getRenderer()`
  The rendering system associated with this `FlutterEngine`.
  `RestorationChannel`
  `getRestorationChannel()`
  System channel to exchange restoration data between framework and engine.
  `ScribeChannel`
  `getScribeChannel()`
  System channel that sends and receives Scribe requests and results.
  `ServiceControlSurface`
  `getServiceControlSurface()`
  `SettingsChannel`
  `getSettingsChannel()`
  System channel that sends platform/user settings from Android to Flutter, e.g., time format, scale factor, etc.
  `SpellCheckChannel`
  `getSpellCheckChannel()`
  System channel that sends and receives spell check requests and results.
  `SystemChannel`
  `getSystemChannel()`
  System channel that sends memory pressure warnings from Android to Flutter.
  `TextInputChannel`
  `getTextInputChannel()`
  System channel that sends and receives text input requests and state.
  `void`
  `removeEngineLifecycleListener(FlutterEngine.EngineLifecycleListener listener)`
  Removes a `listener` that was previously added with `addEngineLifecycleListener(EngineLifecycleListener)`.
  `static void`
  `resetNextEngineId()`
  `void`
  `updateDisplayMetrics(float width, float height, float density)`
  Publishes display metrics to Dart code in Flutter.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### FlutterEngine

    public FlutterEngine(@NonNull Context context)
    Constructs a new `FlutterEngine`.

    A new `FlutterEngine` does not execute any Dart code automatically. See `getDartExecutor()` and `DartExecutor.executeDartEntrypoint(DartExecutor.DartEntrypoint)` to begin executing Dart code within this `FlutterEngine`.

    A new `FlutterEngine` will not display any UI until a `RenderSurface` is registered. See `getRenderer()` and `FlutterRenderer.startRenderingToSurface(Surface, boolean)`.

    A new `FlutterEngine` automatically attaches all plugins. See `getPlugins()`.

    A new `FlutterEngine` does come with all default system channels attached.

    The first `FlutterEngine` instance constructed per process will also load the Flutter native library and start a Dart VM.

    In order to pass Dart VM initialization arguments (see `FlutterShellArgs`) when creating the VM, manually set the initialization arguments by calling `FlutterLoader.startInitialization(Context)` and `FlutterLoader.ensureInitializationComplete(Context, String[])` before constructing the engine.

  - ### FlutterEngine

    public FlutterEngine(@NonNull Context context, @Nullable String[] dartVmArgs)
    Same as `FlutterEngine(Context)` with added support for passing Dart VM arguments.

    If the Dart VM has already started, the given arguments will have no effect.

  - ### FlutterEngine

    public FlutterEngine(@NonNull Context context, @Nullable String[] dartVmArgs, boolean automaticallyRegisterPlugins)
    Same as `FlutterEngine(Context)` with added support for passing Dart VM arguments and avoiding automatic plugin registration.

    If the Dart VM has already started, the given arguments will have no effect.

  - ### FlutterEngine

    public FlutterEngine(@NonNull Context context, @Nullable String[] dartVmArgs, boolean automaticallyRegisterPlugins, boolean waitForRestorationData)
    Same as `FlutterEngine(Context, String[], boolean)` with added support for configuring whether the engine will receive restoration data.

    The `waitForRestorationData` flag controls whether the engine delays responding to requests from the framework for restoration data until that data has been provided to the engine via `RestorationChannel.setRestorationData(byte[] data)`. If the flag is false, the framework may temporarily initialize itself to default values before the restoration data has been made available to the engine. Setting `waitForRestorationData` to true avoids this extra work by delaying initialization until the data is available.

    When `waitForRestorationData` is set, `RestorationChannel.setRestorationData(byte[] data)` must be called at a later point in time. If it later turns out that no restoration data is available to restore the framework from, that method must still be called with null as an argument to indicate "no data".

    If the framework never requests the restoration data, this flag has no effect.

  - ### FlutterEngine

    public FlutterEngine(@NonNull Context context, @Nullable FlutterLoader flutterLoader, @NonNull FlutterJNI flutterJNI)
    Same as `FlutterEngine(Context, FlutterLoader, FlutterJNI, String[], boolean)` but with no Dart VM flags and automatically registers plugins.

    `flutterJNI` should be a new instance that has never been attached to an engine before.

  - ### FlutterEngine

    public FlutterEngine(@NonNull Context context, @Nullable FlutterLoader flutterLoader, @NonNull FlutterJNI flutterJNI, @Nullable String[] dartVmArgs, boolean automaticallyRegisterPlugins)
    Same as `FlutterEngine(Context, FlutterLoader, FlutterJNI)`, plus Dart VM flags in `dartVmArgs`, and control over whether plugins are automatically registered with this `FlutterEngine` in `automaticallyRegisterPlugins`. If plugins are automatically registered, then they are registered during the execution of this constructor.

  - ### FlutterEngine

    public FlutterEngine(@NonNull Context context, @Nullable FlutterLoader flutterLoader, @NonNull FlutterJNI flutterJNI, @NonNull PlatformViewsController platformViewsController, @Nullable String[] dartVmArgs, boolean automaticallyRegisterPlugins)
    Same as `FlutterEngine(Context, FlutterLoader, FlutterJNI, String[], boolean)`, plus the ability to provide a custom `PlatformViewsController`.

  - ### FlutterEngine

    public FlutterEngine(@NonNull Context context, @Nullable FlutterLoader flutterLoader, @NonNull FlutterJNI flutterJNI, @NonNull PlatformViewsController platformViewsController, @Nullable String[] dartVmArgs, boolean automaticallyRegisterPlugins, boolean waitForRestorationData)
    Fully configurable `FlutterEngine` constructor.

  - ### FlutterEngine

    @VisibleForTesting(otherwise=3) public FlutterEngine(@NonNull Context context, @Nullable FlutterLoader flutterLoader, @NonNull FlutterJNI flutterJNI, @NonNull PlatformViewsController platformViewsController, @Nullable String[] dartVmArgs, boolean automaticallyRegisterPlugins, boolean waitForRestorationData, @Nullable FlutterEngineGroup group)

- ## Method Details

  - ### resetNextEngineId

    @VisibleForTesting(otherwise=3) public static void resetNextEngineId()

  - ### destroy

    public void destroy()
    Cleans up all components within this `FlutterEngine` and destroys the associated Dart Isolate. All state held by the Dart Isolate, such as the Flutter Elements tree, is lost.

    This `FlutterEngine` instance should be discarded after invoking this method.

  - ### addEngineLifecycleListener

    public void addEngineLifecycleListener(@NonNull FlutterEngine.EngineLifecycleListener listener)
    Adds a `listener` to be notified of Flutter engine lifecycle events, e.g., `onPreEngineStart()`.

  - ### removeEngineLifecycleListener

    public void removeEngineLifecycleListener(@NonNull FlutterEngine.EngineLifecycleListener listener)
    Removes a `listener` that was previously added with `addEngineLifecycleListener(EngineLifecycleListener)`.

  - ### getDartExecutor

    @NonNull public DartExecutor getDartExecutor()
    The Dart execution context associated with this `FlutterEngine`.

    The `DartExecutor` can be used to start executing Dart code from a given entrypoint. See `DartExecutor.executeDartEntrypoint(DartExecutor.DartEntrypoint)`.

    Use the `DartExecutor` to connect any desired message channels and method channels to facilitate communication between Android and Dart/Flutter.

  - ### getRenderer

    @NonNull public FlutterRenderer getRenderer()
    The rendering system associated with this `FlutterEngine`.

    To render a Flutter UI that is produced by this `FlutterEngine`'s Dart code, attach a `RenderSurface` to this `FlutterRenderer`.

  - ### getAccessibilityChannel

    @NonNull public AccessibilityChannel getAccessibilityChannel()
    System channel that sends accessibility requests and events from Flutter to Android.

  - ### getLifecycleChannel

    @NonNull public LifecycleChannel getLifecycleChannel()
    System channel that sends Android lifecycle events to Flutter.

  - ### getLocalizationChannel

    @NonNull public LocalizationChannel getLocalizationChannel()
    System channel that sends locale data from Android to Flutter.

  - ### getNavigationChannel

    @NonNull public NavigationChannel getNavigationChannel()
    System channel that sends Flutter navigation commands from Android to Flutter.

  - ### getBackGestureChannel

    @NonNull public BackGestureChannel getBackGestureChannel()
    System channel that sends back gesture commands from Android to Flutter.

  - ### getPlatformChannel

    @NonNull public PlatformChannel getPlatformChannel()
    System channel that sends platform-oriented requests and information to Flutter, e.g., requests to play sounds, requests for haptics, system chrome settings, etc.

  - ### getProcessTextChannel

    @NonNull public ProcessTextChannel getProcessTextChannel()
    System channel that sends text processing requests from Flutter to Android.

  - ### getRestorationChannel

    @NonNull public RestorationChannel getRestorationChannel()
    System channel to exchange restoration data between framework and engine.

    The engine can obtain the current restoration data from the framework via this channel to store it on disk and - when the app is relaunched - provide the stored data back to the framework to recreate the original state of the app.

  - ### getSettingsChannel

    @NonNull public SettingsChannel getSettingsChannel()
    System channel that sends platform/user settings from Android to Flutter, e.g., time format, scale factor, etc.

  - ### getDeferredComponentChannel

    @NonNull public DeferredComponentChannel getDeferredComponentChannel()
    System channel that allows manual installation and state querying of deferred components.

  - ### getSystemChannel

    @NonNull public SystemChannel getSystemChannel()
    System channel that sends memory pressure warnings from Android to Flutter.

  - ### getMouseCursorChannel

    @NonNull public MouseCursorChannel getMouseCursorChannel()
    System channel that sends and receives text input requests and state.

  - ### getTextInputChannel

    @NonNull public TextInputChannel getTextInputChannel()
    System channel that sends and receives text input requests and state.

  - ### getScribeChannel

    @NonNull public ScribeChannel getScribeChannel()
    System channel that sends and receives Scribe requests and results.

  - ### getSpellCheckChannel

    @NonNull public SpellCheckChannel getSpellCheckChannel()
    System channel that sends and receives spell check requests and results.

  - ### getPlugins

    @NonNull public PluginRegistry getPlugins()
    Plugin registry, which registers plugins that want to be applied to this `FlutterEngine`.

  - ### getLocalizationPlugin

    @NonNull public io.flutter.plugin.localization.LocalizationPlugin getLocalizationPlugin()
    The LocalizationPlugin this FlutterEngine created.

  - ### getPlatformViewsController

    @NonNull public PlatformViewsController getPlatformViewsController()
    `PlatformViewsController`, which controls all platform views running within this `FlutterEngine`.

  - ### getPlatformViewsController2

    @NonNull public PlatformViewsController2 getPlatformViewsController2()

  - ### getActivityControlSurface

    @NonNull public ActivityControlSurface getActivityControlSurface()

  - ### getServiceControlSurface

    @NonNull public ServiceControlSurface getServiceControlSurface()

  - ### getBroadcastReceiverControlSurface

    @NonNull public BroadcastReceiverControlSurface getBroadcastReceiverControlSurface()

  - ### getContentProviderControlSurface

    @NonNull public ContentProviderControlSurface getContentProviderControlSurface()

  - ### getEngineId

    public long getEngineId()
    Returns unique identifier for this engine.

  - ### engineForId

    @Nullable @VisibleForTesting(otherwise=3) public static FlutterEngine engineForId(long handle)
    Returns engine for the given identifier or null if identifier is not valid. The handle can be obtained through

        PlatformDispatcher.instance.engineId

    Must be called on the UI thread.

  - ### updateDisplayMetrics

    public void updateDisplayMetrics(float width, float height, float density)
    Description copied from interface: `ViewUtils.DisplayUpdater`
    Publishes display metrics to Dart code in Flutter.
    Specified by:
      `updateDisplayMetrics` in interface `ViewUtils.DisplayUpdater`