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 FlutterEngines may exist, execute Dart code, and render UIs within a single Android app. For better memory performance characteristics, construct multiple FlutterEngines 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 FlutterEngines 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.

  • 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

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

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

    • getActivityControlSurface

      @NonNull public ActivityControlSurface getActivityControlSurface()

    • getServiceControlSurface

      @NonNull public ServiceControlSurface getServiceControlSurface()

    • getBroadcastReceiverControlSurface

      @NonNull public BroadcastReceiverControlSurface getBroadcastReceiverControlSurface()

    • getContentProviderControlSurface

      @NonNull public ContentProviderControlSurface getContentProviderControlSurface()

    • 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