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