public class FlutterEngine extends Object
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. Flutter at this point makes no guarantees on the performance of running multiple
engines. Use at your own risk. See https://github.com/flutter/flutter/issues/37644 for details.
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.
Modifier and Type | Class and Description |
---|---|
static interface |
FlutterEngine.EngineLifecycleListener
Lifecycle callbacks for Flutter engine lifecycle events.
|
Constructor and Description |
---|
FlutterEngine(Context context)
Constructs a new
FlutterEngine . |
FlutterEngine(Context context,
FlutterLoader flutterLoader,
FlutterJNI flutterJNI)
Same as
#FlutterEngine(Context, FlutterLoader, FlutterJNI, String[]) but with no Dart
VM flags. |
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. |
Modifier and Type | Method and 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) . |
public FlutterEngine(@NonNull Context context)
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(RenderSurface)
.
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.
public FlutterEngine(@NonNull Context context, @Nullable String[] dartVmArgs)
FlutterEngine(Context)
with added support for passing Dart VM arguments.
If the Dart VM has already started, the given arguments will have no effect.
public FlutterEngine(@NonNull Context context, @Nullable String[] dartVmArgs, boolean automaticallyRegisterPlugins)
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.
public FlutterEngine(@NonNull Context context, @Nullable String[] dartVmArgs, boolean automaticallyRegisterPlugins, boolean waitForRestorationData)
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.
public FlutterEngine(@NonNull Context context, @Nullable FlutterLoader flutterLoader, @NonNull FlutterJNI flutterJNI)
#FlutterEngine(Context, FlutterLoader, FlutterJNI, String[])
but with no Dart
VM flags.
flutterJNI
should be a new instance that has never been attached to an engine
before.
public FlutterEngine(@NonNull Context context, @Nullable FlutterLoader flutterLoader, @NonNull FlutterJNI flutterJNI, @Nullable String[] dartVmArgs, boolean automaticallyRegisterPlugins)
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.public FlutterEngine(@NonNull Context context, @Nullable FlutterLoader flutterLoader, @NonNull FlutterJNI flutterJNI, @NonNull PlatformViewsController platformViewsController, @Nullable String[] dartVmArgs, boolean automaticallyRegisterPlugins)
FlutterEngine(Context, FlutterLoader, FlutterJNI, String[], boolean)
, plus the
ability to provide a custom PlatformViewsController
.public FlutterEngine(@NonNull Context context, @Nullable FlutterLoader flutterLoader, @NonNull FlutterJNI flutterJNI, @NonNull PlatformViewsController platformViewsController, @Nullable String[] dartVmArgs, boolean automaticallyRegisterPlugins, boolean waitForRestorationData)
FlutterEngine
constructor.public void destroy()
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.
public void addEngineLifecycleListener(@NonNull FlutterEngine.EngineLifecycleListener listener)
listener
to be notified of Flutter engine lifecycle events, e.g., onPreEngineStart()
.public void removeEngineLifecycleListener(@NonNull FlutterEngine.EngineLifecycleListener listener)
listener
that was previously added with addEngineLifecycleListener(EngineLifecycleListener)
.@NonNull public DartExecutor getDartExecutor()
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.
@NonNull public FlutterRenderer getRenderer()
FlutterEngine
.
To render a Flutter UI that is produced by this FlutterEngine
's Dart code, attach a
RenderSurface
to this FlutterRenderer
.
@NonNull public AccessibilityChannel getAccessibilityChannel()
@NonNull public KeyEventChannel getKeyEventChannel()
@NonNull public LifecycleChannel getLifecycleChannel()
@NonNull public LocalizationChannel getLocalizationChannel()
@NonNull public NavigationChannel getNavigationChannel()
@NonNull public PlatformChannel getPlatformChannel()
@NonNull public RestorationChannel getRestorationChannel()
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.
@NonNull public SettingsChannel getSettingsChannel()
@NonNull public DeferredComponentChannel getDeferredComponentChannel()
@NonNull public SystemChannel getSystemChannel()
@NonNull public MouseCursorChannel getMouseCursorChannel()
@NonNull public TextInputChannel getTextInputChannel()
@NonNull public PluginRegistry getPlugins()
FlutterEngine
.@NonNull public io.flutter.plugin.localization.LocalizationPlugin getLocalizationPlugin()
@NonNull public PlatformViewsController getPlatformViewsController()
PlatformViewsController
, which controls all platform views running within this FlutterEngine
.@NonNull public ActivityControlSurface getActivityControlSurface()
@NonNull public ServiceControlSurface getServiceControlSurface()
@NonNull public BroadcastReceiverControlSurface getBroadcastReceiverControlSurface()
@NonNull public ContentProviderControlSurface getContentProviderControlSurface()