Package io.flutter.embedding.engine

Class 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 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 Detail

      • 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,
                     @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,
                     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().

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

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

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