Package io.flutter.embedding.engine

## Class FlutterEngine

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

-     public class FlutterEngine
      extends Object

  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, 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

    All Methods Instance Methods Concrete Methods
    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.
    `AccessibilityChannel` | `getAccessibilityChannel()` | System channel that sends accessibility requests and events from Flutter to Android.
    `ActivityControlSurface` | `getActivityControlSurface()` |
    `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.
    `KeyEventChannel` | `getKeyEventChannel()` | System channel that sends key events from Android to Flutter.
    `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`.
    `PluginRegistry` | `getPlugins()` | Plugin registry, which registers plugins that want to be applied to this `FlutterEngine`.
    `FlutterRenderer` | `getRenderer()` | The rendering system associated with this `FlutterEngine`.
    `RestorationChannel` | `getRestorationChannel()` | System channel to exchange restoration data between framework and engine.
    `ServiceControlSurface` | `getServiceControlSurface()` |
    `SettingsChannel` | `getSettingsChannel()` | System channel that sends platform/user settings from Android to Flutter, e.g., time format, scale factor, etc.
    `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)`.

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

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

- - ### Constructor Detail

    - #### 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)`.

      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.

  - ### Method Detail

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

    - #### getKeyEventChannel

          @NonNull
          public KeyEventChannel getKeyEventChannel()

      System channel that sends key events from Android to Flutter.

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

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

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

    - #### 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`.

    - #### getActivityControlSurface

          @NonNull
          public ActivityControlSurface getActivityControlSurface()

    - #### getServiceControlSurface

          @NonNull
          public ServiceControlSurface getServiceControlSurface()

    - #### getBroadcastReceiverControlSurface

          @NonNull
          public BroadcastReceiverControlSurface getBroadcastReceiverControlSurface()

    - #### getContentProviderControlSurface

          @NonNull
          public ContentProviderControlSurface getContentProviderControlSurface()