Flutter Engine
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 
12 #import "FlutterDartProject.h"
13 #import "FlutterMacros.h"
14 #import "FlutterPlugin.h"
15 #import "FlutterTexture.h"
16 
18 
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  */
59 @interface FlutterEngine : NSObject <FlutterTextureRegistry, 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. IF nil,
223  * this will default to the same library as the `main()` function in the Dart program.
224  * @return YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.
225  */
226 - (BOOL)runWithEntrypoint:(nullable NSString*)entrypoint libraryURI:(nullable NSString*)uri;
227 
228 /**
229  * Runs a Dart program on an Isolate using the specified entrypoint and Dart library,
230  * which may not be the same as the library containing the Dart program's `main()` function.
231  *
232  * The first call to this method will create a new Isolate. Subsequent calls will return
233  * immediately and have no effect.
234  *
235  * @param entrypoint The name of a top-level function from a Dart library. If this is
236  * FlutterDefaultDartEntrypoint (or nil); this will default to `main()`. If it is not the app's
237  * main() function, that function must be decorated with `@pragma(vm:entry-point)` to ensure the
238  * method is not tree-shaken by the Dart compiler.
239  * @param libraryURI The URI of the Dart library which contains the entrypoint method. IF nil,
240  * this will default to the same library as the `main()` function in the Dart program.
241  * @param initialRoute The name of the initial Flutter `Navigator` `Route` to load. If this is
242  * FlutterDefaultInitialRoute (or nil), it will default to the "/" route.
243  * @return YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise.
244  */
245 - (BOOL)runWithEntrypoint:(nullable NSString*)entrypoint
246  libraryURI:(nullable NSString*)libraryURI
247  initialRoute:(nullable NSString*)initialRoute;
248 
249 /**
250  * Destroy running context for an engine.
251  *
252  * This method can be used to force the FlutterEngine object to release all resources.
253  * After sending this message, the object will be in an unusable state until it is deallocated.
254  * Accessing properties or sending messages to it will result in undefined behavior or runtime
255  * errors.
256  */
257 - (void)destroyContext;
258 
259 /**
260  * Ensures that Flutter will generate a semantics tree.
261  *
262  * This is enabled by default if certain accessibility services are turned on by
263  * the user, or when using a Simulator. This method allows a user to turn
264  * semantics on when they would not ordinarily be generated and the performance
265  * overhead is not a concern, e.g. for UI testing. Note that semantics should
266  * never be programmatically turned off, as it would potentially disable
267  * accessibility services an end user has requested.
268  *
269  * This method must only be called after launching the engine via
270  * `-runWithEntrypoint:` or `-runWithEntryPoint:libraryURI`.
271  *
272  * Although this method returns synchronously, it does not guarantee that a
273  * semantics tree is actually available when the method returns. It
274  * synchronously ensures that the next frame the Flutter framework creates will
275  * have a semantics tree.
276  *
277  * You can subscribe to semantics updates via `NSNotificationCenter` by adding
278  * an observer for the name `FlutterSemanticsUpdateNotification`. The `object`
279  * parameter will be the `FlutterViewController` associated with the semantics
280  * update. This will asynchronously fire after a semantics tree has actually
281  * built (which may be some time after the frame has been rendered).
282  */
283 - (void)ensureSemanticsEnabled;
284 
285 /**
286  * Sets the `FlutterViewController` for this instance. The FlutterEngine must be
287  * running (e.g. a successful call to `-runWithEntrypoint:` or `-runWithEntrypoint:libraryURI`)
288  * before calling this method. Callers may pass nil to remove the viewController
289  * and have the engine run headless in the current process.
290  *
291  * A FlutterEngine can only have one `FlutterViewController` at a time. If there is
292  * already a `FlutterViewController` associated with this instance, this method will replace
293  * the engine's current viewController with the newly specified one.
294  *
295  * Setting the viewController will signal the engine to start animations and drawing, and unsetting
296  * it will signal the engine to stop animations and drawing. However, neither will impact the state
297  * of the Dart program's execution.
298  */
299 @property(nonatomic, weak) FlutterViewController* viewController;
300 
301 /**
302  * The `FlutterMethodChannel` used for localization related platform messages, such as
303  * setting the locale.
304  *
305  * Can be nil after `destroyContext` is called.
306  */
307 @property(nonatomic, readonly, nullable) FlutterMethodChannel* localizationChannel;
308 /**
309  * The `FlutterMethodChannel` used for navigation related platform messages.
310  *
311  * Can be nil after `destroyContext` is called.
312  *
313  * @see [Navigation
314  * Channel](https://api.flutter.dev/flutter/services/SystemChannels/navigation-constant.html)
315  * @see [Navigator Widget](https://api.flutter.dev/flutter/widgets/Navigator-class.html)
316  */
317 @property(nonatomic, readonly) FlutterMethodChannel* navigationChannel;
318 
319 /**
320  * The `FlutterMethodChannel` used for restoration related platform messages.
321  *
322  * Can be nil after `destroyContext` is called.
323  *
324  * @see [Restoration
325  * Channel](https://api.flutter.dev/flutter/services/SystemChannels/restoration-constant.html)
326  */
327 @property(nonatomic, readonly) FlutterMethodChannel* restorationChannel;
328 
329 /**
330  * The `FlutterMethodChannel` used for core platform messages, such as
331  * information about the screen orientation.
332  *
333  * Can be nil after `destroyContext` is called.
334  */
335 @property(nonatomic, readonly) FlutterMethodChannel* platformChannel;
336 
337 /**
338  * The `FlutterMethodChannel` used to communicate text input events to the
339  * Dart Isolate.
340  *
341  * Can be nil after `destroyContext` is called.
342  *
343  * @see [Text Input
344  * Channel](https://api.flutter.dev/flutter/services/SystemChannels/textInput-constant.html)
345  */
346 @property(nonatomic, readonly) FlutterMethodChannel* textInputChannel;
347 
348 /**
349  * The `FlutterBasicMessageChannel` used to communicate app lifecycle events
350  * to the Dart Isolate.
351  *
352  * Can be nil after `destroyContext` is called.
353  *
354  * @see [Lifecycle
355  * Channel](https://api.flutter.dev/flutter/services/SystemChannels/lifecycle-constant.html)
356  */
357 @property(nonatomic, readonly) FlutterBasicMessageChannel* lifecycleChannel;
358 
359 /**
360  * The `FlutterBasicMessageChannel` used for communicating system events, such as
361  * memory pressure events.
362  *
363  * Can be nil after `destroyContext` is called.
364  *
365  * @see [System
366  * Channel](https://api.flutter.dev/flutter/services/SystemChannels/system-constant.html)
367  */
368 @property(nonatomic, readonly) FlutterBasicMessageChannel* systemChannel;
369 
370 /**
371  * The `FlutterBasicMessageChannel` used for communicating user settings such as
372  * clock format and text scale.
373  *
374  * Can be nil after `destroyContext` is called.
375  */
376 @property(nonatomic, readonly) FlutterBasicMessageChannel* settingsChannel;
377 
378 /**
379  * The `FlutterBasicMessageChannel` used for communicating key events
380  * from physical keyboards
381  *
382  * Can be nil after `destroyContext` is called.
383  */
384 @property(nonatomic, readonly) FlutterBasicMessageChannel* keyEventChannel;
385 
386 /**
387  * The `NSURL` of the observatory for the service isolate.
388  *
389  * This is only set in debug and profile runtime modes, and only after the
390  * observatory service is ready. In release mode or before the observatory has
391  * started, it returns `nil`.
392  */
393 @property(nonatomic, readonly, nullable) NSURL* observatoryUrl;
394 
395 /**
396  * The `FlutterBinaryMessenger` associated with this FlutterEngine (used for communicating with
397  * channels).
398  */
399 @property(nonatomic, readonly) NSObject<FlutterBinaryMessenger>* binaryMessenger;
400 
401 /**
402  * The UI Isolate ID of the engine.
403  *
404  * This property will be nil if the engine is not running.
405  */
406 @property(nonatomic, readonly, copy, nullable) NSString* isolateId;
407 
408 /**
409  * Whether or not GPU calls are allowed.
410  *
411  * Typically this is set when the app is backgrounded and foregrounded.
412  */
413 @property(nonatomic, assign) BOOL isGpuDisabled;
414 
415 @end
416 
418 
419 #endif // FLUTTER_FLUTTERENGINE_H_
FlutterMethodChannel * localizationChannel
NSObject< FlutterBinaryMessenger > * binaryMessenger
FlutterViewController * viewController
FlutterMethodChannel * textInputChannel
#define NS_ASSUME_NONNULL_END
Definition: FlutterMacros.h:20
NSString * isolateId
#define FLUTTER_DARWIN_EXPORT
Definition: FlutterMacros.h:14
#define NS_ASSUME_NONNULL_BEGIN
Definition: FlutterMacros.h:19
FlutterMethodChannel * navigationChannel
FlutterBasicMessageChannel * systemChannel
NS_ASSUME_NONNULL_BEGIN NSString *const FlutterDefaultDartEntrypoint
NSString *const FlutterDefaultInitialRoute
NSURL * observatoryUrl
void ensureSemanticsEnabled()
FlutterMethodChannel * platformChannel
FlutterBasicMessageChannel * settingsChannel
int BOOL
Definition: windows_types.h:37
FlutterMethodChannel * restorationChannel
FlutterBasicMessageChannel * keyEventChannel
FlutterBasicMessageChannel * lifecycleChannel
instancetype init()