FlutterEngine

Objective-C

@interface FlutterEngine : NSObject <FlutterPluginRegistry>

Swift

class FlutterEngine : NSObject, FlutterPluginRegistry

The FlutterEngine class coordinates a single instance of execution for a FlutterDartProject. It may have zero or one FlutterViewController at a time, which can be specified via -setViewController:. FlutterViewController‘s initWithEngine initializer will automatically call -setViewController: for itself.

A FlutterEngine can be created independently of a FlutterViewController for headless execution. It can also persist across the lifespan of multiple FlutterViewController instances to maintain state and/or asynchronous tasks (such as downloading a large file).

A FlutterEngine can also be used to prewarm the Dart execution environment and reduce the latency of showing the Flutter screen when a FlutterViewController is created and presented. See http://flutter.dev/docs/development/add-to-app/performance for more details on loading performance.

Alternatively, you can simply create a new FlutterViewController with only a FlutterDartProject. That FlutterViewController will internally manage its own instance of a FlutterEngine, but will not guarantee survival of the engine beyond the life of the ViewController.

A newly initialized FlutterEngine will not actually run a Dart Isolate until either -runWithEntrypoint: or -runWithEntrypoint:libraryURI is invoked. One of these methods must be invoked before calling -setViewController:.

  • Default initializer for a FlutterEngine.

    Threads created by this FlutterEngine will appear as “FlutterEngine #” in Instruments. The prefix can be customized using initWithName.

    The engine will execute the project located in the bundle with the identifier “io.flutter.flutter.app” (the default for Flutter projects).

    A newly initialized engine will not run until either -runWithEntrypoint: or -runWithEntrypoint:libraryURI: is called.

    FlutterEngine created with this method will have allowHeadlessExecution set to YES. This means that the engine will continue to run regardless of whether a FlutterViewController is attached to it or not, until -destroyContext: is called or the process finishes.

    Declaration

    Objective-C

    - (nonnull instancetype)init;

    Swift

    convenience init()

  • Initialize this FlutterEngine.

    The engine will execute the project located in the bundle with the identifier “io.flutter.flutter.app” (the default for Flutter projects).

    A newly initialized engine will not run until either -runWithEntrypoint: or -runWithEntrypoint:libraryURI: is called.

    FlutterEngine created with this method will have allowHeadlessExecution set to YES. This means that the engine will continue to run regardless of whether a FlutterViewController is attached to it or not, until -destroyContext: is called or the process finishes.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithName:(nonnull NSString *)labelPrefix;

    Swift

    convenience init(name labelPrefix: String)

    Parameters

    labelPrefix

    The label prefix used to identify threads for this instance. Should be unique across FlutterEngine instances, and is used in instrumentation to label the threads used by this FlutterEngine.

  • Initialize this FlutterEngine with a FlutterDartProject.

    If the FlutterDartProject is not specified, the FlutterEngine will attempt to locate the project in a default location (the flutter_assets folder in the iOS application bundle).

    A newly initialized engine will not run the FlutterDartProject until either -runWithEntrypoint: or -runWithEntrypoint:libraryURI: is called.

    FlutterEngine created with this method will have allowHeadlessExecution set to YES. This means that the engine will continue to run regardless of whether a FlutterViewController is attached to it or not, until -destroyContext: is called or the process finishes.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithName:(nonnull NSString *)labelPrefix
                             project:(nullable FlutterDartProject *)project;

    Swift

    convenience init(name labelPrefix: String, project: FlutterDartProject?)

    Parameters

    labelPrefix

    The label prefix used to identify threads for this instance. Should be unique across FlutterEngine instances, and is used in instrumentation to label the threads used by this FlutterEngine.
    project

    The FlutterDartProject to run.

  • Initialize this FlutterEngine with a FlutterDartProject.

    If the FlutterDartProject is not specified, the FlutterEngine will attempt to locate the project in a default location (the flutter_assets folder in the iOS application bundle).

    A newly initialized engine will not run the FlutterDartProject until either -runWithEntrypoint: or -runWithEntrypoint:libraryURI: is called.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithName:(nonnull NSString *)labelPrefix
                             project:(nullable FlutterDartProject *)project
              allowHeadlessExecution:(BOOL)allowHeadlessExecution;

    Swift

    convenience init(name labelPrefix: String, project: FlutterDartProject?, allowHeadlessExecution: Bool)

    Parameters

    labelPrefix

    The label prefix used to identify threads for this instance. Should be unique across FlutterEngine instances, and is used in instrumentation to label the threads used by this FlutterEngine.
    project

    The FlutterDartProject to run.
    allowHeadlessExecution

    Whether or not to allow this instance to continue running after passing a nil FlutterViewController to -setViewController:.

  • Initialize this FlutterEngine with a FlutterDartProject.

    If the FlutterDartProject is not specified, the FlutterEngine will attempt to locate the project in a default location (the flutter_assets folder in the iOS application bundle).

    A newly initialized engine will not run the FlutterDartProject until either -runWithEntrypoint: or -runWithEntrypoint:libraryURI: is called.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithName:(nonnull NSString *)labelPrefix
                             project:(nullable FlutterDartProject *)project
              allowHeadlessExecution:(BOOL)allowHeadlessExecution
                  restorationEnabled:(BOOL)restorationEnabled;

    Swift

    init(name labelPrefix: String, project: FlutterDartProject?, allowHeadlessExecution: Bool, restorationEnabled: Bool)

    Parameters

    labelPrefix

    The label prefix used to identify threads for this instance. Should be unique across FlutterEngine instances, and is used in instrumentation to label the threads used by this FlutterEngine.
    project

    The FlutterDartProject to run.
    allowHeadlessExecution

    Whether or not to allow this instance to continue running after passing a nil FlutterViewController to -setViewController:.
    restorationEnabled

    Whether state restoration is enabled. When true, the framework will wait for the attached view controller to provide restoration data.

  • Runs a Dart program on an Isolate from the main Dart library (i.e. the library that contains main()), using main() as the entrypoint (the default for Flutter projects), and using “/” (the default route) as the initial route.

    The first call to this method will create a new Isolate. Subsequent calls will return immediately and have no effect.

    Declaration

    Objective-C

    - (BOOL)run;

    Swift

    func run() -> Bool

    Return Value

    YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.

  • Runs a Dart program on an Isolate from the main Dart library (i.e. the library that contains main()), using “/” (the default route) as the initial route.

    The first call to this method will create a new Isolate. Subsequent calls will return immediately and have no effect.

    Declaration

    Objective-C

    - (BOOL)runWithEntrypoint:(nullable NSString *)entrypoint;

    Swift

    func run(withEntrypoint entrypoint: String?) -> Bool

    Parameters

    entrypoint

    The name of a top-level function from the same Dart library that contains the app’s main() function. If this is FlutterDefaultDartEntrypoint (or nil) it will default to main(). If it is not the app’s main() function, that function must be decorated with @pragma(vm:entry-point) to ensure the method is not tree-shaken by the Dart compiler.

    Return Value

    YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.

  • Runs a Dart program on an Isolate from the main Dart library (i.e. the library that contains main()).

    The first call to this method will create a new Isolate. Subsequent calls will return immediately and have no effect.

    Declaration

    Objective-C

    - (BOOL)runWithEntrypoint:(nullable NSString *)entrypoint
             initialRoute:(nullable NSString *)initialRoute;

    Swift

    func run(withEntrypoint entrypoint: String?, initialRoute: String?) -> Bool

    Parameters

    entrypoint

    The name of a top-level function from the same Dart library that contains the app’s main() function. If this is FlutterDefaultDartEntrypoint (or nil), it will default to main(). If it is not the app’s main() function, that function must be decorated with @pragma(vm:entry-point) to ensure the method is not tree-shaken by the Dart compiler.
    initialRoute

    The name of the initial Flutter Navigator Route to load. If this is FlutterDefaultInitialRoute (or nil), it will default to the “/” route.

    Return Value

    YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.

  • Runs a Dart program on an Isolate using the specified entrypoint and Dart library, which may not be the same as the library containing the Dart program’s main() function.

    The first call to this method will create a new Isolate. Subsequent calls will return immediately and have no effect.

    Declaration

    Objective-C

    - (BOOL)runWithEntrypoint:(nullable NSString *)entrypoint
               libraryURI:(nullable NSString *)uri;

    Swift

    func run(withEntrypoint entrypoint: String?, libraryURI uri: String?) -> Bool

    Parameters

    entrypoint

    The name of a top-level function from a Dart library. If this is FlutterDefaultDartEntrypoint (or nil); this will default to main(). If it is not the app’s main() function, that function must be decorated with @pragma(vm:entry-point) to ensure the method is not tree-shaken by the Dart compiler.
    uri

    The URI of the Dart library which contains the entrypoint method (example “package:foo_package/main.dart”). If nil, this will default to the same library as the main() function in the Dart program.

    Return Value

    YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.

  • Runs a Dart program on an Isolate using the specified entrypoint and Dart library, which may not be the same as the library containing the Dart program’s main() function.

    The first call to this method will create a new Isolate. Subsequent calls will return immediately and have no effect.

    Declaration

    Objective-C

    - (BOOL)runWithEntrypoint:(nullable NSString *)entrypoint
               libraryURI:(nullable NSString *)libraryURI
             initialRoute:(nullable NSString *)initialRoute;

    Swift

    func run(withEntrypoint entrypoint: String?, libraryURI: String?, initialRoute: String?) -> Bool

    Parameters

    entrypoint

    The name of a top-level function from a Dart library. If this is FlutterDefaultDartEntrypoint (or nil); this will default to main(). If it is not the app’s main() function, that function must be decorated with @pragma(vm:entry-point) to ensure the method is not tree-shaken by the Dart compiler.
    libraryURI

    The URI of the Dart library which contains the entrypoint method (example “package:foo_package/main.dart”). If nil, this will default to the same library as the main() function in the Dart program.
    initialRoute

    The name of the initial Flutter Navigator Route to load. If this is FlutterDefaultInitialRoute (or nil), it will default to the “/” route.

    Return Value

    YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.

  • Runs a Dart program on an Isolate using the specified entrypoint and Dart library, which may not be the same as the library containing the Dart program’s main() function.

    The first call to this method will create a new Isolate. Subsequent calls will return immediately and have no effect.

    Declaration

    Objective-C

    - (BOOL)runWithEntrypoint:(nullable NSString *)entrypoint
               libraryURI:(nullable NSString *)libraryURI
             initialRoute:(nullable NSString *)initialRoute
           entrypointArgs:(nullable NSArray<NSString *> *)entrypointArgs;

    Swift

    func run(withEntrypoint entrypoint: String?, libraryURI: String?, initialRoute: String?, entrypointArgs: [String]?) -> Bool

    Parameters

    entrypoint

    The name of a top-level function from a Dart library. If this is FlutterDefaultDartEntrypoint (or nil); this will default to main(). If it is not the app’s main() function, that function must be decorated with @pragma(vm:entry-point) to ensure the method is not tree-shaken by the Dart compiler.
    libraryURI

    The URI of the Dart library which contains the entrypoint method (example “package:foo_package/main.dart”). If nil, this will default to the same library as the main() function in the Dart program.
    initialRoute

    The name of the initial Flutter Navigator Route to load. If this is FlutterDefaultInitialRoute (or nil), it will default to the “/” route.
    entrypointArgs

    Arguments passed as a list of string to Dart’s entrypoint function.

    Return Value

    YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.

  • Destroy running context for an engine.

    This method can be used to force the FlutterEngine object to release all resources. After sending this message, the object will be in an unusable state until it is deallocated. Accessing properties or sending messages to it will result in undefined behavior or runtime errors.

    Declaration

    Objective-C

    - (void)destroyContext;

    Swift

    func destroyContext()

  • Ensures that Flutter will generate a semantics tree.

    This is enabled by default if certain accessibility services are turned on by the user, or when using a Simulator. This method allows a user to turn semantics on when they would not ordinarily be generated and the performance overhead is not a concern, e.g. for UI testing. Note that semantics should never be programmatically turned off, as it would potentially disable accessibility services an end user has requested.

    This method must only be called after launching the engine via -runWithEntrypoint: or -runWithEntryPoint:libraryURI.

    Although this method returns synchronously, it does not guarantee that a semantics tree is actually available when the method returns. It synchronously ensures that the next frame the Flutter framework creates will have a semantics tree.

    You can subscribe to semantics updates via NSNotificationCenter by adding an observer for the name FlutterSemanticsUpdateNotification. The object parameter will be the FlutterViewController associated with the semantics update. This will asynchronously fire after a semantics tree has actually built (which may be some time after the frame has been rendered).

    Declaration

    Objective-C

    - (void)ensureSemanticsEnabled;

    Swift

    func ensureSemanticsEnabled()

  • Sets the FlutterViewController for this instance. The FlutterEngine must be running (e.g. a successful call to -runWithEntrypoint: or -runWithEntrypoint:libraryURI) before calling this method. Callers may pass nil to remove the viewController and have the engine run headless in the current process.

    A FlutterEngine can only have one FlutterViewController at a time. If there is already a FlutterViewController associated with this instance, this method will replace the engine’s current viewController with the newly specified one.

    Setting the viewController will signal the engine to start animations and drawing, and unsetting it will signal the engine to stop animations and drawing. However, neither will impact the state of the Dart program’s execution.

    Declaration

    Objective-C

    @property (nonatomic, weak) FlutterViewController *_Nullable viewController;

    Swift

    weak var viewController: FlutterViewController? { get set }

  • The FlutterMethodChannel used for localization related platform messages, such as setting the locale.

    Can be nil after destroyContext is called.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) FlutterMethodChannel *localizationChannel;

    Swift

    var localizationChannel: FlutterMethodChannel? { get }

  • The FlutterMethodChannel used for navigation related platform messages.

    Can be nil after destroyContext is called.

    See

    Navigation Channel

    See

    Navigator Widget

    Declaration

    Objective-C

    @property (nonatomic, readonly) FlutterMethodChannel *_Nonnull navigationChannel;

    Swift

    var navigationChannel: FlutterMethodChannel { get }

  • The FlutterMethodChannel used for restoration related platform messages.

    Can be nil after destroyContext is called.

    See

    Restoration Channel

    Declaration

    Objective-C

    @property (nonatomic, readonly) FlutterMethodChannel *_Nonnull restorationChannel;

    Swift

    var restorationChannel: FlutterMethodChannel { get }

  • The FlutterMethodChannel used for core platform messages, such as information about the screen orientation.

    Can be nil after destroyContext is called.

    Declaration

    Objective-C

    @property (nonatomic, readonly) FlutterMethodChannel *_Nonnull platformChannel;

    Swift

    var platformChannel: FlutterMethodChannel { get }

  • The FlutterMethodChannel used to communicate text input events to the Dart Isolate.

    Can be nil after destroyContext is called.

    See

    Text Input Channel

    Declaration

    Objective-C

    @property (nonatomic, readonly) FlutterMethodChannel *_Nonnull textInputChannel;

    Swift

    var textInputChannel: FlutterMethodChannel { get }

  • The FlutterBasicMessageChannel used to communicate app lifecycle events to the Dart Isolate.

    Can be nil after destroyContext is called.

    See

    Lifecycle Channel

    Declaration

    Objective-C

    @property (nonatomic, readonly) FlutterBasicMessageChannel *_Nonnull lifecycleChannel;

    Swift

    var lifecycleChannel: FlutterBasicMessageChannel { get }

  • The FlutterBasicMessageChannel used for communicating system events, such as memory pressure events.

    Can be nil after destroyContext is called.

    See

    System Channel

    Declaration

    Objective-C

    @property (nonatomic, readonly) FlutterBasicMessageChannel *_Nonnull systemChannel;

    Swift

    var systemChannel: FlutterBasicMessageChannel { get }

  • The FlutterBasicMessageChannel used for communicating user settings such as clock format and text scale.

    Can be nil after destroyContext is called.

    Declaration

    Objective-C

    @property (nonatomic, readonly) FlutterBasicMessageChannel *_Nonnull settingsChannel;

    Swift

    var settingsChannel: FlutterBasicMessageChannel { get }

  • The FlutterBasicMessageChannel used for communicating key events from physical keyboards

    Can be nil after destroyContext is called.

    Declaration

    Objective-C

    @property (nonatomic, readonly) FlutterBasicMessageChannel *_Nonnull keyEventChannel;

    Swift

    var keyEventChannel: FlutterBasicMessageChannel { get }

  • Deprecated

    Use vmServiceUrl instead

    The depcreated NSURL of the Dart VM Service for the service isolate.

    This is only set in debug and profile runtime modes, and only after the Dart VM Service is ready. In release mode or before the Dart VM Service has started, it returns nil.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSURL *observatoryUrl;

    Swift

    var observatoryUrl: URL? { get }

  • The NSURL of the Dart VM Service for the service isolate.

    This is only set in debug and profile runtime modes, and only after the Dart VM Service is ready. In release mode or before the Dart VM Service has started, it returns nil.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSURL *vmServiceUrl;

    Swift

    var vmServiceUrl: URL? { get }

  • The FlutterBinaryMessenger associated with this FlutterEngine (used for communicating with channels).

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSObject<FlutterBinaryMessenger> *_Nonnull binaryMessenger;

    Swift

    var binaryMessenger: FlutterBinaryMessenger { get }

  • The FlutterTextureRegistry associated with this FlutterEngine (used to register textures).

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSObject<FlutterTextureRegistry> *_Nonnull textureRegistry;

    Swift

    var textureRegistry: FlutterTextureRegistry { get }

  • The UI Isolate ID of the engine.

    This property will be nil if the engine is not running.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSString *isolateId;

    Swift

    var isolateId: String? { get }

  • Whether or not GPU calls are allowed.

    Typically this is set when the app is backgrounded and foregrounded.

    Declaration

    Objective-C

    @property (nonatomic) BOOL isGpuDisabled;

    Swift

    var isGpuDisabled: Bool { get set }