| Flutter iOS Embedder |

FlutterEngine.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4
5 #ifndef FLUTTER_FLUTTERENGINE_H_
6 #define FLUTTER_FLUTTERENGINE_H_
7
8 #import <Foundation/Foundation.h>
9 #import <UIKit/UIKit.h>
10
11 #import "FlutterBinaryMessenger.h"
12 #import "FlutterDartProject.h"
13 #import "FlutterMacros.h"
14 #import "FlutterPlugin.h"
15 #import "FlutterTexture.h"
16
17 @class FlutterViewController;
18
19 NS_ASSUME_NONNULL_BEGIN
20
21 /**
22 * The dart entrypoint that is associated with `main()`. This is to be used as an argument to the
23 * `runWithEntrypoint*` methods.
24 */
25 extern NSString* const FlutterDefaultDartEntrypoint;
26
27 /**
28 * The default Flutter initial route ("/").
29 */
30 extern NSString* const FlutterDefaultInitialRoute;
31
32 /**
33 * The FlutterEngine class coordinates a single instance of execution for a
34 * `FlutterDartProject`. It may have zero or one `FlutterViewController` at a
35 * time, which can be specified via `-setViewController:`.
36 * `FlutterViewController`'s `initWithEngine` initializer will automatically call
37 * `-setViewController:` for itself.
38 *
39 * A FlutterEngine can be created independently of a `FlutterViewController` for
40 * headless execution. It can also persist across the lifespan of multiple
41 * `FlutterViewController` instances to maintain state and/or asynchronous tasks
42 * (such as downloading a large file).
43 *
44 * A FlutterEngine can also be used to prewarm the Dart execution environment and reduce the
45 * latency of showing the Flutter screen when a `FlutterViewController` is created and presented.
46 * See http://flutter.dev/docs/development/add-to-app/performance for more details on loading
47 * performance.
48 *
49 * Alternatively, you can simply create a new `FlutterViewController` with only a
50 * `FlutterDartProject`. That `FlutterViewController` will internally manage its
51 * own instance of a FlutterEngine, but will not guarantee survival of the engine
52 * beyond the life of the ViewController.
53 *
54 * A newly initialized FlutterEngine will not actually run a Dart Isolate until
55 * either `-runWithEntrypoint:` or `-runWithEntrypoint:libraryURI` is invoked.
56 * One of these methods must be invoked before calling `-setViewController:`.
57 */
58 FLUTTER_DARWIN_EXPORT
59 @interface FlutterEngine : NSObject <FlutterPluginRegistry>
60
61 /**
62 * Default initializer for a FlutterEngine.
63 *
64 * Threads created by this FlutterEngine will appear as "FlutterEngine #" in
65 * Instruments. The prefix can be customized using `initWithName`.
66 *
67 * The engine will execute the project located in the bundle with the identifier
68 * "io.flutter.flutter.app" (the default for Flutter projects).
69 *
70 * A newly initialized engine will not run until either `-runWithEntrypoint:` or
71 * `-runWithEntrypoint:libraryURI:` is called.
72 *
73 * FlutterEngine created with this method will have allowHeadlessExecution set to `YES`.
74 * This means that the engine will continue to run regardless of whether a `FlutterViewController`
75 * is attached to it or not, until `-destroyContext:` is called or the process finishes.
76 */
77 - (instancetype)init;
78
79 /**
80 * Initialize this FlutterEngine.
81 *
82 * The engine will execute the project located in the bundle with the identifier
83 * "io.flutter.flutter.app" (the default for Flutter projects).
84 *
85 * A newly initialized engine will not run until either `-runWithEntrypoint:` or
86 * `-runWithEntrypoint:libraryURI:` is called.
87 *
88 * FlutterEngine created with this method will have allowHeadlessExecution set to `YES`.
89 * This means that the engine will continue to run regardless of whether a `FlutterViewController`
90 * is attached to it or not, until `-destroyContext:` is called or the process finishes.
91 *
92 * @param labelPrefix The label prefix used to identify threads for this instance. Should
93 * be unique across FlutterEngine instances, and is used in instrumentation to label
94 * the threads used by this FlutterEngine.
95 */
96 - (instancetype)initWithName:(NSString*)labelPrefix;
97
98 /**
99 * Initialize this FlutterEngine with a `FlutterDartProject`.
100 *
101 * If the FlutterDartProject is not specified, the FlutterEngine will attempt to locate
102 * the project in a default location (the flutter_assets folder in the iOS application
103 * bundle).
104 *
105 * A newly initialized engine will not run the `FlutterDartProject` until either
106 * `-runWithEntrypoint:` or `-runWithEntrypoint:libraryURI:` is called.
107 *
108 * FlutterEngine created with this method will have allowHeadlessExecution set to `YES`.
109 * This means that the engine will continue to run regardless of whether a `FlutterViewController`
110 * is attached to it or not, until `-destroyContext:` is called or the process finishes.
111 *
112 * @param labelPrefix The label prefix used to identify threads for this instance. Should
113 * be unique across FlutterEngine instances, and is used in instrumentation to label
114 * the threads used by this FlutterEngine.
115 * @param project The `FlutterDartProject` to run.
116 */
117 - (instancetype)initWithName:(NSString*)labelPrefix project:(nullable FlutterDartProject*)project;
118
119 /**
120 * Initialize this FlutterEngine with a `FlutterDartProject`.
121 *
122 * If the FlutterDartProject is not specified, the FlutterEngine will attempt to locate
123 * the project in a default location (the flutter_assets folder in the iOS application
124 * bundle).
125 *
126 * A newly initialized engine will not run the `FlutterDartProject` until either
127 * `-runWithEntrypoint:` or `-runWithEntrypoint:libraryURI:` is called.
128 *
129 * @param labelPrefix The label prefix used to identify threads for this instance. Should
130 * be unique across FlutterEngine instances, and is used in instrumentation to label
131 * the threads used by this FlutterEngine.
132 * @param project The `FlutterDartProject` to run.
133 * @param allowHeadlessExecution Whether or not to allow this instance to continue
134 * running after passing a nil `FlutterViewController` to `-setViewController:`.
135 */
136 - (instancetype)initWithName:(NSString*)labelPrefix
137 project:(nullable FlutterDartProject*)project
138 allowHeadlessExecution:(BOOL)allowHeadlessExecution;
139
140 /**
141 * Initialize this FlutterEngine with a `FlutterDartProject`.
142 *
143 * If the FlutterDartProject is not specified, the FlutterEngine will attempt to locate
144 * the project in a default location (the flutter_assets folder in the iOS application
145 * bundle).
146 *
147 * A newly initialized engine will not run the `FlutterDartProject` until either
148 * `-runWithEntrypoint:` or `-runWithEntrypoint:libraryURI:` is called.
149 *
150 * @param labelPrefix The label prefix used to identify threads for this instance. Should
151 * be unique across FlutterEngine instances, and is used in instrumentation to label
152 * the threads used by this FlutterEngine.
153 * @param project The `FlutterDartProject` to run.
154 * @param allowHeadlessExecution Whether or not to allow this instance to continue
155 * running after passing a nil `FlutterViewController` to `-setViewController:`.
156 * @param restorationEnabled Whether state restoration is enabled. When true, the framework will
157 * wait for the attached view controller to provide restoration data.
158 */
159 - (instancetype)initWithName:(NSString*)labelPrefix
160 project:(nullable FlutterDartProject*)project
161 allowHeadlessExecution:(BOOL)allowHeadlessExecution
162 restorationEnabled:(BOOL)restorationEnabled NS_DESIGNATED_INITIALIZER;
163
164 /**
165 * Runs a Dart program on an Isolate from the main Dart library (i.e. the library that
166 * contains `main()`), using `main()` as the entrypoint (the default for Flutter projects),
167 * and using "/" (the default route) as the initial route.
168 *
169 * The first call to this method will create a new Isolate. Subsequent calls will return
170 * immediately and have no effect.
171 *
172 * @return YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.
173 */
174 - (BOOL)run;
175
176 /**
177 * Runs a Dart program on an Isolate from the main Dart library (i.e. the library that
178 * contains `main()`), using "/" (the default route) as the initial route.
179 *
180 * The first call to this method will create a new Isolate. Subsequent calls will return
181 * immediately and have no effect.
182 *
183 * @param entrypoint The name of a top-level function from the same Dart
184 * library that contains the app's main() function. If this is FlutterDefaultDartEntrypoint (or
185 * nil) it will default to `main()`. If it is not the app's main() function, that function must
186 * be decorated with `@pragma(vm:entry-point)` to ensure the method is not tree-shaken by the Dart
187 * compiler.
188 * @return YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.
189 */
190 - (BOOL)runWithEntrypoint:(nullable NSString*)entrypoint;
191
192 /**
193 * Runs a Dart program on an Isolate from the main Dart library (i.e. the library that
194 * contains `main()`).
195 *
196 * The first call to this method will create a new Isolate. Subsequent calls will return
197 * immediately and have no effect.
198 *
199 * @param entrypoint The name of a top-level function from the same Dart
200 * library that contains the app's main() function. If this is FlutterDefaultDartEntrypoint (or
201 * nil), it will default to `main()`. If it is not the app's main() function, that function must
202 * be decorated with `@pragma(vm:entry-point)` to ensure the method is not tree-shaken by the Dart
203 * compiler.
204 * @param initialRoute The name of the initial Flutter `Navigator` `Route` to load. If this is
205 * FlutterDefaultInitialRoute (or nil), it will default to the "/" route.
206 * @return YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.
207 */
208 - (BOOL)runWithEntrypoint:(nullable NSString*)entrypoint
209 initialRoute:(nullable NSString*)initialRoute;
210
211 /**
212 * Runs a Dart program on an Isolate using the specified entrypoint and Dart library,
213 * which may not be the same as the library containing the Dart program's `main()` function.
214 *
215 * The first call to this method will create a new Isolate. Subsequent calls will return
216 * immediately and have no effect.
217 *
218 * @param entrypoint The name of a top-level function from a Dart library. If this is
219 * FlutterDefaultDartEntrypoint (or nil); this will default to `main()`. If it is not the app's
220 * main() function, that function must be decorated with `@pragma(vm:entry-point)` to ensure the
221 * method is not tree-shaken by the Dart compiler.
222 * @param uri The URI of the Dart library which contains the entrypoint method
223 * (example "package:foo_package/main.dart"). If nil, this will default to
224 * the same library as the `main()` function in the Dart program.
225 * @return YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.
226 */
227 - (BOOL)runWithEntrypoint:(nullable NSString*)entrypoint libraryURI:(nullable NSString*)uri;
228
229 /**
230 * Runs a Dart program on an Isolate using the specified entrypoint and Dart library,
231 * which may not be the same as the library containing the Dart program's `main()` function.
232 *
233 * The first call to this method will create a new Isolate. Subsequent calls will return
234 * immediately and have no effect.
235 *
236 * @param entrypoint The name of a top-level function from a Dart library. If this is
237 * FlutterDefaultDartEntrypoint (or nil); this will default to `main()`. If it is not the app's
238 * main() function, that function must be decorated with `@pragma(vm:entry-point)` to ensure the
239 * method is not tree-shaken by the Dart compiler.
240 * @param libraryURI The URI of the Dart library which contains the entrypoint
241 * method (example "package:foo_package/main.dart"). If nil, this will
242 * default to the same library as the `main()` function in the Dart program.
243 * @param initialRoute The name of the initial Flutter `Navigator` `Route` to load. If this is
244 * FlutterDefaultInitialRoute (or nil), it will default to the "/" route.
245 * @return YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.
246 */
247 - (BOOL)runWithEntrypoint:(nullable NSString*)entrypoint
248 libraryURI:(nullable NSString*)libraryURI
249 initialRoute:(nullable NSString*)initialRoute;
250
251 /**
252 * Runs a Dart program on an Isolate using the specified entrypoint and Dart library,
253 * which may not be the same as the library containing the Dart program's `main()` function.
254 *
255 * The first call to this method will create a new Isolate. Subsequent calls will return
256 * immediately and have no effect.
257 *
258 * @param entrypoint The name of a top-level function from a Dart library. If this is
259 * FlutterDefaultDartEntrypoint (or nil); this will default to `main()`. If it is not the app's
260 * main() function, that function must be decorated with `@pragma(vm:entry-point)` to ensure the
261 * method is not tree-shaken by the Dart compiler.
262 * @param libraryURI The URI of the Dart library which contains the entrypoint
263 * method (example "package:foo_package/main.dart"). If nil, this will
264 * default to the same library as the `main()` function in the Dart program.
265 * @param initialRoute The name of the initial Flutter `Navigator` `Route` to load. If this is
266 * FlutterDefaultInitialRoute (or nil), it will default to the "/" route.
267 * @param entrypointArgs Arguments passed as a list of string to Dart's entrypoint function.
268 * @return YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.
269 */
270 - (BOOL)runWithEntrypoint:(nullable NSString*)entrypoint
271 libraryURI:(nullable NSString*)libraryURI
272 initialRoute:(nullable NSString*)initialRoute
273 entrypointArgs:(nullable NSArray<NSString*>*)entrypointArgs;
274
275 /**
276 * Destroy running context for an engine.
277 *
278 * This method can be used to force the FlutterEngine object to release all resources.
279 * After sending this message, the object will be in an unusable state until it is deallocated.
280 * Accessing properties or sending messages to it will result in undefined behavior or runtime
281 * errors.
282 */
283 - (void)destroyContext;
284
285 /**
286 * Ensures that Flutter will generate a semantics tree.
287 *
288 * This is enabled by default if certain accessibility services are turned on by
289 * the user, or when using a Simulator. This method allows a user to turn
290 * semantics on when they would not ordinarily be generated and the performance
291 * overhead is not a concern, e.g. for UI testing. Note that semantics should
292 * never be programmatically turned off, as it would potentially disable
293 * accessibility services an end user has requested.
294 *
295 * This method must only be called after launching the engine via
296 * `-runWithEntrypoint:` or `-runWithEntryPoint:libraryURI`.
297 *
298 * Although this method returns synchronously, it does not guarantee that a
299 * semantics tree is actually available when the method returns. It
300 * synchronously ensures that the next frame the Flutter framework creates will
301 * have a semantics tree.
302 *
303 * You can subscribe to semantics updates via `NSNotificationCenter` by adding
304 * an observer for the name `FlutterSemanticsUpdateNotification`. The `object`
305 * parameter will be the `FlutterViewController` associated with the semantics
306 * update. This will asynchronously fire after a semantics tree has actually
307 * built (which may be some time after the frame has been rendered).
308 */
309 - (void)ensureSemanticsEnabled;
310
311 /**
312 * Sets the `FlutterViewController` for this instance. The FlutterEngine must be
313 * running (e.g. a successful call to `-runWithEntrypoint:` or `-runWithEntrypoint:libraryURI`)
314 * before calling this method. Callers may pass nil to remove the viewController
315 * and have the engine run headless in the current process.
316 *
317 * A FlutterEngine can only have one `FlutterViewController` at a time. If there is
318 * already a `FlutterViewController` associated with this instance, this method will replace
319 * the engine's current viewController with the newly specified one.
320 *
321 * Setting the viewController will signal the engine to start animations and drawing, and unsetting
322 * it will signal the engine to stop animations and drawing. However, neither will impact the state
323 * of the Dart program's execution.
324 */
325 @property(nonatomic, weak) FlutterViewController* viewController;
326
327 /**
328 * The `FlutterMethodChannel` used for localization related platform messages, such as
329 * setting the locale.
330 *
331 * Can be nil after `destroyContext` is called.
332 */
333 @property(nonatomic, readonly, nullable) FlutterMethodChannel* localizationChannel;
334 /**
335 * The `FlutterMethodChannel` used for navigation related platform messages.
336 *
337 * Can be nil after `destroyContext` is called.
338 *
339 * @see [Navigation
340 * Channel](https://api.flutter.dev/flutter/services/SystemChannels/navigation-constant.html)
341 * @see [Navigator Widget](https://api.flutter.dev/flutter/widgets/Navigator-class.html)
342 */
343 @property(nonatomic, readonly) FlutterMethodChannel* navigationChannel;
344
345 /**
346 * The `FlutterMethodChannel` used for restoration related platform messages.
347 *
348 * Can be nil after `destroyContext` is called.
349 *
350 * @see [Restoration
351 * Channel](https://api.flutter.dev/flutter/services/SystemChannels/restoration-constant.html)
352 */
353 @property(nonatomic, readonly) FlutterMethodChannel* restorationChannel;
354
355 /**
356 * The `FlutterMethodChannel` used for core platform messages, such as
357 * information about the screen orientation.
358 *
359 * Can be nil after `destroyContext` is called.
360 */
361 @property(nonatomic, readonly) FlutterMethodChannel* platformChannel;
362
363 /**
364 * The `FlutterMethodChannel` used to communicate text input events to the
365 * Dart Isolate.
366 *
367 * Can be nil after `destroyContext` is called.
368 *
369 * @see [Text Input
370 * Channel](https://api.flutter.dev/flutter/services/SystemChannels/textInput-constant.html)
371 */
372 @property(nonatomic, readonly) FlutterMethodChannel* textInputChannel;
373
374 /**
375 * The `FlutterBasicMessageChannel` used to communicate app lifecycle events
376 * to the Dart Isolate.
377 *
378 * Can be nil after `destroyContext` is called.
379 *
380 * @see [Lifecycle
381 * Channel](https://api.flutter.dev/flutter/services/SystemChannels/lifecycle-constant.html)
382 */
383 @property(nonatomic, readonly) FlutterBasicMessageChannel* lifecycleChannel;
384
385 /**
386 * The `FlutterBasicMessageChannel` used for communicating system events, such as
387 * memory pressure events.
388 *
389 * Can be nil after `destroyContext` is called.
390 *
391 * @see [System
392 * Channel](https://api.flutter.dev/flutter/services/SystemChannels/system-constant.html)
393 */
394 @property(nonatomic, readonly) FlutterBasicMessageChannel* systemChannel;
395
396 /**
397 * The `FlutterBasicMessageChannel` used for communicating user settings such as
398 * clock format and text scale.
399 *
400 * Can be nil after `destroyContext` is called.
401 */
402 @property(nonatomic, readonly) FlutterBasicMessageChannel* settingsChannel;
403
404 /**
405 * The `FlutterBasicMessageChannel` used for communicating key events
406 * from physical keyboards
407 *
408 * Can be nil after `destroyContext` is called.
409 */
410 @property(nonatomic, readonly) FlutterBasicMessageChannel* keyEventChannel;
411
412 /**
413 * The depcreated `NSURL` of the Dart VM Service for the service isolate.
414 *
415 * This is only set in debug and profile runtime modes, and only after the
416 * Dart VM Service is ready. In release mode or before the Dart VM Service has
417 * started, it returns `nil`.
418 */
419 @property(nonatomic, readonly, nullable)
420 NSURL* observatoryUrl FLUTTER_DEPRECATED("Use vmServiceUrl instead");
421
422 /**
423 * The `NSURL` of the Dart VM Service for the service isolate.
424 *
425 * This is only set in debug and profile runtime modes, and only after the
426 * Dart VM Service is ready. In release mode or before the Dart VM Service has
427 * started, it returns `nil`.
428 */
429 @property(nonatomic, readonly, nullable) NSURL* vmServiceUrl;
430
431 /**
432 * The `FlutterBinaryMessenger` associated with this FlutterEngine (used for communicating with
433 * channels).
434 */
435 @property(nonatomic, readonly) NSObject<FlutterBinaryMessenger>* binaryMessenger;
436
437 /**
438 * The `FlutterTextureRegistry` associated with this FlutterEngine (used to register textures).
439 */
440 @property(nonatomic, readonly) NSObject<FlutterTextureRegistry>* textureRegistry;
441
442 /**
443 * The UI Isolate ID of the engine.
444 *
445 * This property will be nil if the engine is not running.
446 */
447 @property(nonatomic, readonly, copy, nullable) NSString* isolateId;
448
449 /**
450 * Whether or not GPU calls are allowed.
451 *
452 * Typically this is set when the app is backgrounded and foregrounded.
453 */
454 @property(nonatomic, assign) BOOL isGpuDisabled;
455
456 @end
457
458 NS_ASSUME_NONNULL_END
459
460 #endif // FLUTTER_FLUTTERENGINE_H_
FlutterEngine::systemChannel
FlutterBasicMessageChannel * systemChannel
Definition: FlutterEngine.h:394
FlutterEngine::isGpuDisabled
BOOL isGpuDisabled
Definition: FlutterEngine.h:454
FlutterEngine
Definition: FlutterEngine.h:59
FlutterBasicMessageChannel
Definition: FlutterChannels.h:39
FlutterEngine::textInputChannel
FlutterMethodChannel * textInputChannel
Definition: FlutterEngine.h:372
FlutterViewController
Definition: FlutterViewController.h:55
FlutterMethodChannel
Definition: FlutterChannels.h:222
FlutterEngine::binaryMessenger
NSObject< FlutterBinaryMessenger > * binaryMessenger
Definition: FlutterEngine.h:435
FlutterEngine::restorationChannel
FlutterMethodChannel * restorationChannel
Definition: FlutterEngine.h:353
FlutterEngine::isolateId
NSString * isolateId
Definition: FlutterEngine.h:447
NS_ASSUME_NONNULL_END
#define NS_ASSUME_NONNULL_END
Definition: FlutterMacros.h:20
-[FlutterEngine ensureSemanticsEnabled]
void ensureSemanticsEnabled()
Definition: FlutterEngine.mm:420
FlutterEngine::platformChannel
FlutterMethodChannel * platformChannel
Definition: FlutterEngine.h:361
FlutterEngine::settingsChannel
FlutterBasicMessageChannel * settingsChannel
Definition: FlutterEngine.h:402
FlutterPluginRegistry-p
Definition: FlutterPlugin.h:400
-[FlutterEngine init]
instancetype init()
Definition: FlutterEngine.mm:159
FlutterTexture.h
NS_ASSUME_NONNULL_BEGIN
#define NS_ASSUME_NONNULL_BEGIN
Definition: FlutterMacros.h:19
FlutterMacros.h
FlutterEngine::lifecycleChannel
FlutterBasicMessageChannel * lifecycleChannel
Definition: FlutterEngine.h:383
FlutterEngine::keyEventChannel
FlutterBasicMessageChannel * keyEventChannel
Definition: FlutterEngine.h:410
FlutterPlugin.h
FlutterEngine::vmServiceUrl
NSURL * vmServiceUrl
Definition: FlutterEngine.h:429
viewController
FlutterViewController * viewController
Definition: FlutterTextInputPluginTest.mm:92
FLUTTER_DEPRECATED
#define FLUTTER_DEPRECATED(msg)
Definition: FlutterMacros.h:30
FlutterEngine::localizationChannel
FlutterMethodChannel * localizationChannel
Definition: FlutterEngine.h:333
FlutterDefaultInitialRoute
NSString *const FlutterDefaultInitialRoute
Definition: FlutterEngine.mm:80
FlutterEngine::textureRegistry
NSObject< FlutterTextureRegistry > * textureRegistry
Definition: FlutterEngine.h:440
FlutterBinaryMessenger.h
FlutterDartProject.h
FlutterDefaultDartEntrypoint
NS_ASSUME_NONNULL_BEGIN NSString *const FlutterDefaultDartEntrypoint
Definition: FlutterEngine.mm:79
-[FlutterEngine destroyContext]
void destroyContext()
Definition: FlutterEngine.mm:480
FLUTTER_DARWIN_EXPORT
#define FLUTTER_DARWIN_EXPORT
Definition: FlutterMacros.h:14
FlutterDartProject
Definition: FlutterDartProject.mm:262
-[FlutterEngine run]
BOOL run()
Definition: FlutterEngine.mm:938
FlutterEngine::navigationChannel
FlutterMethodChannel * navigationChannel
Definition: FlutterEngine.h:343