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 #include "FlutterMacros.h" 12 #include "FlutterPlugin.h" 13 #include "FlutterTexture.h" 14 15 @class FlutterViewController; 16 17 /** 18 * The FlutterEngine class coordinates a single instance of execution for a 19 * `FlutterDartProject`. It may have zero or one `FlutterViewController` at a 20 * time, which can be specified via `-setViewController:`. 21 * `FlutterViewController`'s `initWithEngine` initializer will automatically call 22 * `-setViewController:` for itself. 23 * 24 * A FlutterEngine can be created independently of a `FlutterViewController` for 25 * headless execution. It can also persist across the lifespan of multiple 26 * `FlutterViewController` instances to maintain state and/or asynchronous tasks 27 * (such as downloading a large file). 28 * 29 * Alternatively, you can simply create a new `FlutterViewController` with only a 30 * `FlutterDartProject`. That `FlutterViewController` will internally manage its 31 * own instance of a FlutterEngine, but will not guarantee survival of the engine 32 * beyond the life of the ViewController. 33 * 34 * A newly initialized FlutterEngine will not actually run a Dart Isolate until 35 * either `-runWithEntrypoint:` or `-runWithEntrypoint:libraryURI` is invoked. 36 * One of these methods must be invoked before calling `-setViewController:`. 37 */ 38 FLUTTER_EXPORT 39 @interface FlutterEngine : NSObject <FlutterTextureRegistry, FlutterPluginRegistry> 40 /** 41 * Initialize this FlutterEngine with a `FlutterDartProject`. 42 * 43 * If the FlutterDartProject is not specified, the FlutterEngine will attempt to locate 44 * the project in a default location (the flutter_assets folder in the iOS application 45 * bundle). 46 * 47 * A newly initialized engine will not run the `FlutterDartProject` until either 48 * `-runWithEntrypoint:` or `-runWithEntrypoint:libraryURI:` is called. 49 * 50 * FlutterEngine created with this method will have allowHeadlessExecution set to `YES`. 51 * This means that the engine will continue to run regardless of whether a `FlutterViewController` 52 * is attached to it or not, until `-destroyContext:` is called or the process finishes. 53 * 54 * @param labelPrefix The label prefix used to identify threads for this instance. Should 55 * be unique across FlutterEngine instances, and is used in instrumentation to label 56 * the threads used by this FlutterEngine. 57 * @param projectOrNil The `FlutterDartProject` to run. 58 */ 59 - (instancetype)initWithName:(NSString*)labelPrefix; 60 61 /** 62 * Initialize this FlutterEngine with a `FlutterDartProject`. 63 * 64 * If the FlutterDartProject is not specified, the FlutterEngine will attempt to locate 65 * the project in a default location (the flutter_assets folder in the iOS application 66 * bundle). 67 * 68 * A newly initialized engine will not run the `FlutterDartProject` until either 69 * `-runWithEntrypoint:` or `-runWithEntrypoint:libraryURI:` is called. 70 * 71 * @param labelPrefix The label prefix used to identify threads for this instance. Should 72 * be unique across FlutterEngine instances, and is used in instrumentation to label 73 * the threads used by this FlutterEngine. 74 * @param projectOrNil The `FlutterDartProject` to run. 75 * @param allowHeadlessExecution Whether or not to allow this instance to continue 76 * running after passing a nil `FlutterViewController` to `-setViewController:`. 77 */ 78 - (instancetype)initWithName:(NSString*)labelPrefix 79 allowHeadlessExecution:(BOOL)allowHeadlessExecution NS_DESIGNATED_INITIALIZER; 80 81 /** 82 * The default initializer is not available for this object. 83 * Callers must use `-[FlutterEngine initWithName:project:]`. 84 */ 85 - (instancetype)init NS_UNAVAILABLE; 86 87 + (instancetype)new NS_UNAVAILABLE; 88 89 /** 90 * Runs a Dart program on an Isolate from the main Dart library (i.e. the library that 91 * contains `main()`). 92 * 93 * The first call to this method will create a new Isolate. Subsequent calls will return 94 * immediately. 95 * 96 * @param entrypoint The name of a top-level function from the same Dart 97 * library that contains the app's main() function. If this is nil, it will 98 * default to `main()`. If it is not the app's main() function, that function 99 * must be decorated with `@pragma(vm:entry-point)` to ensure the method is not 100 * tree-shaken by the Dart compiler. 101 * @return YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise. 102 */ 103 - (BOOL)runWithEntrypoint:(NSString*)entrypoint; 104 105 /** 106 * Runs a Dart program on an Isolate using the specified entrypoint and Dart library, 107 * which may not be the same as the library containing the Dart program's `main()` function. 108 * 109 * The first call to this method will create a new Isolate. Subsequent calls will return 110 * immediately. 111 * 112 * @param entrypoint The name of a top-level function from a Dart library. If nil, this will 113 * default to `main()`. If it is not the app's main() function, that function 114 * must be decorated with `@pragma(vm:entry-point)` to ensure the method is not 115 * tree-shaken by the Dart compiler. 116 * @param uri The URI of the Dart library which contains the entrypoint method. IF nil, 117 * this will default to the same library as the `main()` function in the Dart program. 118 * @return YES if the call succeeds in creating and running a Flutter Engine instance; NO otherwise. 119 */ 120 - (BOOL)runWithEntrypoint:(NSString*)entrypoint libraryURI:(NSString*)uri; 121 122 /** 123 * Destroy running context for an engine. 124 * 125 * This method can be used to force the FlutterEngine object to release all resources. 126 * After sending this message, the object will be in an unusable state until it is deallocated. 127 * Accessing properties or sending messages to it will result in undefined behavior or runtime 128 * errors. 129 */ 130 - (void)destroyContext; 131 132 /** 133 * Ensures that Flutter will generate a semantics tree. 134 * 135 * This is enabled by default if certain accessibility services are turned on by 136 * the user, or when using a Simulator. This method allows a user to turn 137 * semantics on when they would not ordinarily be generated and the performance 138 * overhead is not a concern, e.g. for UI testing. Note that semantics should 139 * never be programmatically turned off, as it would potentially disable 140 * accessibility services an end user has requested. 141 * 142 * This method must only be called after launching the engine via 143 * `-runWithEntrypoint:` or `-runWithEntryPoint:libraryURI`. 144 * 145 * Although this method returns synchronously, it does not guarantee that a 146 * semantics tree is actually available when the method returns. It 147 * synchronously ensures that the next frame the Flutter framework creates will 148 * have a semantics tree. 149 * 150 * You can subscribe to semantics updates via `NSNotificationCenter` by adding 151 * an observer for the name `FlutterSemanticsUpdateNotification`. The `object` 152 * parameter will be the `FlutterViewController` associated with the semantics 153 * update. This will asynchronously fire after a semantics tree has actually 154 * built (which may be some time after the frame has been rendered). 155 */ 156 157 158 /** 159 * Sets the `FlutterViewController` for this instance. The FlutterEngine must be 160 * running (e.g. a successful call to `-runWithEntrypoint:` or `-runWithEntrypoint:libraryURI`) 161 * before calling this method. Callers may pass nil to remove the viewController 162 * and have the engine run headless in the current process. 163 * 164 * A FlutterEngine can only have one `FlutterViewController` at a time. If there is 165 * already a `FlutterViewController` associated with this instance, this method will replace 166 * the engine's current viewController with the newly specified one. 167 * 168 * Setting the viewController will signal the engine to start animations and drawing, and unsetting 169 * it will signal the engine to stop animations and drawing. However, neither will impact the state 170 * of the Dart program's execution. 171 */ 172 @property(nonatomic, weak) FlutterViewController* viewController; 173 174 /** 175 * The `FlutterMethodChannel` used for localization related platform messages, such as 176 * setting the locale. 177 */ 178 @property(nonatomic, readonly) FlutterMethodChannel* localizationChannel; 179 /** 180 * The `FlutterMethodChannel` used for navigation related platform messages. 181 * 182 * @see [Navigation 183 * Channel](https://docs.flutter.io/flutter/services/SystemChannels/navigation-constant.html) 184 * @see [Navigator Widget](https://docs.flutter.io/flutter/widgets/Navigator-class.html) 185 */ 186 @property(nonatomic, readonly) FlutterMethodChannel* navigationChannel; 187 188 /** 189 * The `FlutterMethodChannel` used for core platform messages, such as 190 * information about the screen orientation. 191 */ 192 @property(nonatomic, readonly) FlutterMethodChannel* platformChannel; 193 194 /** 195 * The `FlutterMethodChannel` used to communicate text input events to the 196 * Dart Isolate. 197 * 198 * @see [Text Input 199 * Channel](https://docs.flutter.io/flutter/services/SystemChannels/textInput-constant.html) 200 */ 201 @property(nonatomic, readonly) FlutterMethodChannel* textInputChannel; 202 203 /** 204 * The `FlutterBasicMessageChannel` used to communicate app lifecycle events 205 * to the Dart Isolate. 206 * 207 * @see [Lifecycle 208 * Channel](https://docs.flutter.io/flutter/services/SystemChannels/lifecycle-constant.html) 209 */ 210 @property(nonatomic, readonly) FlutterBasicMessageChannel* lifecycleChannel; 211 212 /** 213 * The `FlutterBasicMessageChannel` used for communicating system events, such as 214 * memory pressure events. 215 * 216 * @see [System 217 * Channel](https://docs.flutter.io/flutter/services/SystemChannels/system-constant.html) 218 */ 219 @property(nonatomic, readonly) FlutterBasicMessageChannel* systemChannel; 220 221 /** 222 * The `FlutterBasicMessageChannel` used for communicating user settings such as 223 * clock format and text scale. 224 */ 225 @property(nonatomic, readonly) FlutterBasicMessageChannel* settingsChannel; 226 227 /** 228 * The `NSURL` of the observatory for the service isolate. 229 * 230 * This is only set in debug and profile runtime modes, and only after the 231 * observatory service is ready. In release mode or before the observatory has 232 * started, it returns `nil`. 233 */ 234 @property(nonatomic, readonly) NSURL* observatoryUrl; 235 236 /** 237 * The `FlutterBinaryMessenger` associated with this FlutterEngine (used for communicating with 238 * channels). 239 */ 240 @property(nonatomic, readonly) NSObject<FlutterBinaryMessenger>* binaryMessenger; 241 242 /** 243 * The UI Isolate ID of of the engine. 244 * 245 * This property will be nil if the engine is not running. 246 */ 247 @property(nonatomic, readonly, copy) NSString* isolateId; 248 249 @end 250 251 #endif // FLUTTER_FLUTTERENGINE_H_ 252