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