| Flutter iOS Embedder |

Instance Methods | Properties | List of all members
FlutterEngine Class Reference

`#import <FlutterEngine.h>`

Inheritance diagram for FlutterEngine:

## Instance Methods
(instancetype) | - init
(instancetype) | - initWithName:
(instancetype) | - initWithName:project:
(instancetype) | - initWithName:project:allowHeadlessExecution:
(instancetype) | - initWithName:project:allowHeadlessExecution:restorationEnabled:
(BOOL) | - run
(BOOL) | - runWithEntrypoint:
(BOOL) | - runWithEntrypoint:initialRoute:
(BOOL) | - runWithEntrypoint:libraryURI:
(BOOL) | - runWithEntrypoint:libraryURI:initialRoute:
(BOOL) | - runWithEntrypoint:libraryURI:initialRoute:entrypointArgs:
(void) | - destroyContext
(void) | - ensureSemanticsEnabled
(NSURL *observatoryUrl) | - FLUTTER_DEPRECATED
(flutter::Shell &) | - shell
(flutter::PlatformViewIOS *) | - platformView
(void) | - setBinaryMessenger:
(flutter::IOSRenderingAPI) | - platformViewsRenderingAPI
(void) | - waitForFirstFrame:callback:
(FlutterEngine *) | - spawnWithEntrypoint:libraryURI:initialRoute:entrypointArgs:
(const flutter::ThreadHost &) | - threadHost
(void) | - updateDisplays
(void) | - flutterTextInputView:performAction:withClient:
(void) | - sceneWillEnterForeground:
(void) | - sceneDidEnterBackground:
(void) | - applicationWillEnterForeground:
(void) | - applicationDidEnterBackground:
Instance Methods inherited from <FlutterPluginRegistry>
(nullable NSObject< FlutterPluginRegistrar > *) | - registrarForPlugin:
(BOOL) | - hasPlugin:
(nullable NSObject *) | - valuePublishedByPlugin:

## Properties
FlutterViewController * | viewController
FlutterMethodChannel * | localizationChannel
FlutterMethodChannel * | navigationChannel
FlutterMethodChannel * | restorationChannel
FlutterMethodChannel * | platformChannel
FlutterMethodChannel * | textInputChannel
FlutterBasicMessageChannel * | lifecycleChannel
FlutterBasicMessageChannel * | systemChannel
FlutterBasicMessageChannel * | settingsChannel
FlutterBasicMessageChannel * | keyEventChannel
NSURL * | vmServiceUrl
NSObject< FlutterBinaryMessenger > * | binaryMessenger
NSObject< FlutterTextureRegistry > * | textureRegistry
NSString * | isolateId
BOOL | isGpuDisabled
FlutterEngineProcTable & | embedderAPI
BOOL | enableEmbedderAPI

## Detailed Description

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

Definition at line 61 of file FlutterEngine.h.

## Method Documentation

## ◆ applicationDidEnterBackground:

- (void) applicationDidEnterBackground: |  | (NSNotification *) | notification |

Provided by category FlutterEngine(Test).

## ◆ applicationWillEnterForeground:

- (void) applicationWillEnterForeground: |  | (NSNotification *) | notification |

Provided by category FlutterEngine(Test).

## ◆ destroyContext

- (void) destroyContext |  |  |

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.

Definition at line 161 of file FlutterEngine.mm.

500 {
501 [self resetChannels];
502 self.isolateId = nil;
503 _shell.reset();
504 _profiler.reset();
505 _threadHost.reset();
506 _platformViewsController = nil;
507 }
_profiler
std::shared_ptr< flutter::SamplingProfiler > _profiler
Definition: FlutterEngine.mm:157
_shell
std::unique_ptr< flutter::Shell > _shell
Definition: FlutterEngine.mm:152

## ◆ ensureSemanticsEnabled

- (void) ensureSemanticsEnabled |  |  |

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

Definition at line 161 of file FlutterEngine.mm.

443 {
444 if (!self.platformView) {
445 return;
446 }
447 self.platformView->SetSemanticsEnabled(true);
448 }
-[FlutterEngine(Test) platformView]
flutter::PlatformViewIOS * platformView()

## ◆ FLUTTER_DEPRECATED

- (NSURL* observatoryUrl) FLUTTER_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`.

## ◆ flutterTextInputView:performAction:withClient:

- (void) flutterTextInputView: |  | (FlutterTextInputView *) | textInputView
performAction: |  | (FlutterTextInputAction) | action
withClient: |  | (int) | client

Provided by category FlutterEngine(Test).

## ◆ init

- (instancetype) init |  |  |

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.

Reimplemented in FlutterHeadlessDartRunner.

Definition at line 161 of file FlutterEngine.mm.

168 {
169 return [self initWithName:@"FlutterEngine" project:nil allowHeadlessExecution:YES];
170 }

## ◆ initWithName:

- (instancetype) initWithName: |  | (NSString*) | labelPrefix |

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.

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.

Definition at line 161 of file FlutterEngine.mm.

172 :(NSString*)labelPrefix {
173 return [self initWithName:labelPrefix project:nil allowHeadlessExecution:YES];
174 }

## ◆ initWithName:project:

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

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.

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.

## ◆ initWithName:project:allowHeadlessExecution:

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

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.

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

## ◆ initWithName:project:allowHeadlessExecution:restorationEnabled:

- (instancetype) initWithName: |  | (NSString *) | labelPrefix
project: |  | (nullable FlutterDartProject *) | project
allowHeadlessExecution: |  | (BOOL) | allowHeadlessExecution
restorationEnabled: |  | (BOOL) | NS_DESIGNATED_INITIALIZER

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.

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.

## ◆ platformView

- (PlatformViewIOS* FlutterEngine(Test)): |  |  |

Provided by category FlutterEngine(Test).

## ◆ platformViewsRenderingAPI

- (IOSRenderingAPI FlutterEngine(Test)): |  |  |

Provided by category FlutterEngine(Test).

## ◆ run

- (BOOL) run |  |  |

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.

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

Definition at line 783 of file FlutterEngine.mm.

897 {
898 return [self runWithEntrypoint:FlutterDefaultDartEntrypoint
899 libraryURI:nil
900 initialRoute:FlutterDefaultInitialRoute];
901 }

## ◆ runWithEntrypoint:

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

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.

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.

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

## ◆ runWithEntrypoint:initialRoute:

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

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.

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.

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

## ◆ runWithEntrypoint:libraryURI:

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

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.

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.

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

## ◆ runWithEntrypoint:libraryURI:initialRoute:

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

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.

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.

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

## ◆ runWithEntrypoint:libraryURI:initialRoute:entrypointArgs:

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

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.

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.

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

## ◆ sceneDidEnterBackground:

- (void) sceneDidEnterBackground: |  | (ios(13.0)) | API_AVAILABLE |

Provided by category FlutterEngine(Test).

## ◆ sceneWillEnterForeground:

- (void) sceneWillEnterForeground: |  | (ios(13.0)) | API_AVAILABLE |

Provided by category FlutterEngine(Test).

## ◆ setBinaryMessenger:

- (void) setBinaryMessenger: |  | (FlutterBinaryMessengerRelay *) | binaryMessenger |

Provided by category FlutterEngine(Test).

## ◆ shell

- (Shell& FlutterEngine(Test)): |  |  |

Provided by category FlutterEngine(Test).

## ◆ spawnWithEntrypoint:libraryURI:initialRoute:entrypointArgs:

- (FlutterEngine*) spawnWithEntrypoint: |  | (/*nullable */NSString *) | entrypoint
libraryURI: |  | (/*nullable */NSString *) | libraryURI
initialRoute: |  | (/*nullable */NSString *) | initialRoute
entrypointArgs: |  | (/*nullable */NSArray< NSString * > *) | entrypointArgs

Provided by category FlutterEngine(Test).

## ◆ threadHost

- (const ThreadHost& FlutterEngine(Test)): |  |  |

Provided by category FlutterEngine(Test).

## ◆ updateDisplays

- (void) updateDisplays |  |  |

Provided by category FlutterEngine(Test).

## ◆ waitForFirstFrame:callback:

- (void) waitForFirstFrame: |  | (NSTimeInterval) | timeout
callback: |  | (void(^)(BOOL didTimeout)) | callback

Provided by category FlutterEngine(Test).

## Property Documentation

## ◆ binaryMessenger

- (NSObject< FlutterBinaryMessenger > *) binaryMessenger
| readnonatomicassign

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

Definition at line 437 of file FlutterEngine.h.

## ◆ embedderAPI

- (FlutterEngineProcTable&) embedderAPI
| readnonatomicassign

Provided by category FlutterEngine(Test).

Definition at line 24 of file FlutterEngine_Test.h.

## ◆ enableEmbedderAPI

- (BOOL) enableEmbedderAPI
| readnonatomicassign

Provided by category FlutterEngine(Test).

Definition at line 25 of file FlutterEngine_Test.h.

## ◆ isGpuDisabled

- (BOOL) isGpuDisabled
| readwritenonatomicassign

Whether or not GPU calls are allowed.

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

Definition at line 456 of file FlutterEngine.h.

## ◆ isolateId

- (NSString*) isolateId
| readnonatomiccopy

The UI Isolate ID of the engine.

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

Definition at line 449 of file FlutterEngine.h.

## ◆ keyEventChannel

- (FlutterBasicMessageChannel*) keyEventChannel
| readnonatomicassign

The `FlutterBasicMessageChannel` used for communicating key events from physical keyboards

Can be nil after `destroyContext` is called.

Definition at line 412 of file FlutterEngine.h.

## ◆ lifecycleChannel

- (FlutterBasicMessageChannel*) lifecycleChannel
| readnonatomicassign

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

Can be nil after `destroyContext` is called.

See also
  Lifecycle Channel

Definition at line 385 of file FlutterEngine.h.

## ◆ localizationChannel

- (FlutterMethodChannel*) localizationChannel
| readnonatomicassign

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

Can be nil after `destroyContext` is called.

Definition at line 335 of file FlutterEngine.h.

## ◆ navigationChannel

- (FlutterMethodChannel*) navigationChannel
| readnonatomicassign

The `FlutterMethodChannel` used for navigation related platform messages.

Can be nil after `destroyContext` is called.

See also
  Navigation Channel
  Navigator Widget

Definition at line 345 of file FlutterEngine.h.

## ◆ platformChannel

- (FlutterMethodChannel*) platformChannel
| readnonatomicassign

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

Can be nil after `destroyContext` is called.

Definition at line 363 of file FlutterEngine.h.

## ◆ restorationChannel

- (FlutterMethodChannel*) restorationChannel
| readnonatomicassign

The `FlutterMethodChannel` used for restoration related platform messages.

Can be nil after `destroyContext` is called.

See also
  Restoration Channel

Definition at line 355 of file FlutterEngine.h.

## ◆ settingsChannel

- (FlutterBasicMessageChannel*) settingsChannel
| readnonatomicassign

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

Can be nil after `destroyContext` is called.

Definition at line 404 of file FlutterEngine.h.

## ◆ systemChannel

- (FlutterBasicMessageChannel*) systemChannel
| readnonatomicassign

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

Can be nil after `destroyContext` is called.

See also
  System Channel

Definition at line 396 of file FlutterEngine.h.

## ◆ textInputChannel

- (FlutterMethodChannel*) textInputChannel
| readnonatomicassign

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

Can be nil after `destroyContext` is called.

See also
  Text Input Channel

Definition at line 374 of file FlutterEngine.h.

## ◆ textureRegistry

- (NSObject< FlutterTextureRegistry > *) textureRegistry
| readnonatomicassign

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

Definition at line 442 of file FlutterEngine.h.

## ◆ viewController

- (FlutterViewController*) viewController
| readwritenonatomicweak

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.

Definition at line 327 of file FlutterEngine.h.

Referenced by FlutterViewController::loadDefaultSplashScreenView.

## ◆ vmServiceUrl

- (NSURL *) vmServiceUrl
| readnonatomicassign

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

Definition at line 431 of file FlutterEngine.h.

The documentation for this class was generated from the following files:

- shell/platform/darwin/ios/framework/Headers/FlutterEngine.h
- shell/platform/darwin/ios/framework/Source/FlutterEngine.mm