| Flutter iOS Embedder |

FlutterViewController.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_FLUTTERVIEWCONTROLLER_H_
6 #define FLUTTER_FLUTTERVIEWCONTROLLER_H_
7
8 #import <UIKit/UIKit.h>
9 #include <sys/cdefs.h>
10
11 #import "FlutterBinaryMessenger.h"
12 #import "FlutterDartProject.h"
13 #import "FlutterEngine.h"
14 #import "FlutterMacros.h"
15 #import "FlutterPlugin.h"
16 #import "FlutterTexture.h"
17
18 NS_ASSUME_NONNULL_BEGIN
19
20 @class FlutterEngine;
21
22 /**
23 * The name used for semantic update notifications via `NSNotificationCenter`.
24 *
25 * The object passed as the sender is the `FlutterViewController` associated
26 * with the update.
27 */
28 FLUTTER_DARWIN_EXPORT
29 extern NSNotificationName const FlutterSemanticsUpdateNotification;
30
31 /**
32 * A `UIViewController` implementation for Flutter views.
33 *
34 * Dart execution, channel communication, texture registration, and plugin registration are all
35 * handled by `FlutterEngine`. Calls on this class to those members all proxy through to the
36 * `FlutterEngine` attached FlutterViewController.
37 *
38 * A FlutterViewController can be initialized either with an already-running `FlutterEngine` via the
39 * `initWithEngine:` initializer, or it can be initialized with a `FlutterDartProject` that will be
40 * used to implicitly spin up a new `FlutterEngine`. Creating a `FlutterEngine` before showing a
41 * FlutterViewController can be used to pre-initialize the Dart VM and to prepare the isolate in
42 * order to reduce the latency to the first rendered frame. See
43 * https://flutter.dev/docs/development/add-to-app/performance for more details on loading
44 * latency.
45 *
46 * Holding a `FlutterEngine` independently of FlutterViewControllers can also be used to not to lose
47 * Dart-related state and asynchronous tasks when navigating back and forth between a
48 * FlutterViewController and other `UIViewController`s.
49 */
50 FLUTTER_DARWIN_EXPORT
51 #ifdef __IPHONE_13_4
52 @interface FlutterViewController
53 : UIViewController <FlutterTextureRegistry, FlutterPluginRegistry, UIGestureRecognizerDelegate>
54 #else
55 @interface FlutterViewController : UIViewController <FlutterTextureRegistry, FlutterPluginRegistry>
56 #endif
57
58 /**
59 * Initializes this FlutterViewController with the specified `FlutterEngine`.
60 *
61 * The initialized viewcontroller will attach itself to the engine as part of this process.
62 *
63 * @param engine The `FlutterEngine` instance to attach to. Cannot be nil.
64 * @param nibName The NIB name to initialize this UIViewController with.
65 * @param nibBundle The NIB bundle.
66 */
67 - (instancetype)initWithEngine:(FlutterEngine*)engine
68 nibName:(nullable NSString*)nibName
69 bundle:(nullable NSBundle*)nibBundle NS_DESIGNATED_INITIALIZER;
70
71 /**
72 * Initializes a new FlutterViewController and `FlutterEngine` with the specified
73 * `FlutterDartProject`.
74 *
75 * This will implicitly create a new `FlutterEngine` which is retrievable via the `engine` property
76 * after initialization.
77 *
78 * @param project The `FlutterDartProject` to initialize the `FlutterEngine` with.
79 * @param nibName The NIB name to initialize this UIViewController with.
80 * @param nibBundle The NIB bundle.
81 */
82 - (instancetype)initWithProject:(nullable FlutterDartProject*)project
83 nibName:(nullable NSString*)nibName
84 bundle:(nullable NSBundle*)nibBundle NS_DESIGNATED_INITIALIZER;
85
86 /**
87 * Initializes a new FlutterViewController and `FlutterEngine` with the specified
88 * `FlutterDartProject` and `initialRoute`.
89 *
90 * This will implicitly create a new `FlutterEngine` which is retrievable via the `engine` property
91 * after initialization.
92 *
93 * @param project The `FlutterDartProject` to initialize the `FlutterEngine` with.
94 * @param initialRoute The initial `Navigator` route to load.
95 * @param nibName The NIB name to initialize this UIViewController with.
96 * @param nibBundle The NIB bundle.
97 */
98 - (instancetype)initWithProject:(nullable FlutterDartProject*)project
99 initialRoute:(nullable NSString*)initialRoute
100 nibName:(nullable NSString*)nibName
101 bundle:(nullable NSBundle*)nibBundle NS_DESIGNATED_INITIALIZER;
102
103 /**
104 * Initializer that is called from loading a FlutterViewController from a XIB.
105 *
106 * See also:
107 * https://developer.apple.com/documentation/foundation/nscoding/1416145-initwithcoder?language=objc
108 */
109 - (instancetype)initWithCoder:(NSCoder*)aDecoder NS_DESIGNATED_INITIALIZER;
110
111 /**
112 * Registers a callback that will be invoked when the Flutter view has been rendered.
113 * The callback will be fired only once.
114 *
115 * Replaces an existing callback. Use a `nil` callback to unregister the existing one.
116 */
117 - (void)setFlutterViewDidRenderCallback:(void (^)(void))callback;
118
119 /**
120 * Returns the file name for the given asset.
121 * The returned file name can be used to access the asset in the application's
122 * main bundle.
123 *
124 * @param asset The name of the asset. The name can be hierarchical.
125 * @return The file name to be used for lookup in the main bundle.
126 */
127 - (NSString*)lookupKeyForAsset:(NSString*)asset;
128
129 /**
130 * Returns the file name for the given asset which originates from the specified
131 * package.
132 * The returned file name can be used to access the asset in the application's
133 * main bundle.
134 *
135 * @param asset The name of the asset. The name can be hierarchical.
136 * @param package The name of the package from which the asset originates.
137 * @return The file name to be used for lookup in the main bundle.
138 */
139 - (NSString*)lookupKeyForAsset:(NSString*)asset fromPackage:(NSString*)package;
140
141 /**
142 * Deprecated API to set initial route.
143 *
144 * Attempts to set the first route that the Flutter app shows if the Flutter
145 * runtime hasn't yet started. The default is "/".
146 *
147 * This method must be called immediately after `initWithProject` and has no
148 * effect when using `initWithEngine` if the `FlutterEngine` has already been
149 * run.
150 *
151 * Setting this after the Flutter started running has no effect. See `pushRoute`
152 * and `popRoute` to change the route after Flutter started running.
153 *
154 * This is deprecated because it needs to be called at the time of initialization
155 * and thus should just be in the `initWithProject` initializer. If using
156 * `initWithEngine`, the initial route should be set on the engine's
157 * initializer.
158 *
159 * @param route The name of the first route to show.
160 */
161 - (void)setInitialRoute:(NSString*)route
162 FLUTTER_DEPRECATED("Use FlutterViewController initializer to specify initial route");
163
164 /**
165 * Instructs the Flutter Navigator (if any) to go back.
166 */
167 - (void)popRoute;
168
169 /**
170 * Instructs the Flutter Navigator (if any) to push a route on to the navigation
171 * stack.
172 *
173 * @param route The name of the route to push to the navigation stack.
174 */
175 - (void)pushRoute:(NSString*)route;
176
177 /**
178 * The `FlutterPluginRegistry` used by this FlutterViewController.
179 */
180 - (id<FlutterPluginRegistry>)pluginRegistry;
181
182 /**
183 * A wrapper around UIAccessibilityIsVoiceOverRunning().
184 *
185 * As a C function, UIAccessibilityIsVoiceOverRunning() cannot be mocked in testing. Mock
186 * this class method to testing features depends on UIAccessibilityIsVoiceOverRunning().
187 */
188 + (BOOL)isUIAccessibilityIsVoiceOverRunning;
189
190 /**
191 * True if at least one frame has rendered and the ViewController has appeared.
192 *
193 * This property is reset to false when the ViewController disappears. It is
194 * guaranteed to only alternate between true and false for observers.
195 */
196 @property(nonatomic, readonly, getter=isDisplayingFlutterUI) BOOL displayingFlutterUI;
197
198 /**
199 * Specifies the view to use as a splash screen. Flutter's rendering is asynchronous, so the first
200 * frame rendered by the Flutter application might not immediately appear when the Flutter view is
201 * initially placed in the view hierarchy. The splash screen view will be used as
202 * a replacement until the first frame is rendered.
203 *
204 * The view used should be appropriate for multiple sizes; an autoresizing mask to
205 * have a flexible width and height will be applied automatically.
206 *
207 * Set to nil to remove the splash screen view.
208 */
209 @property(strong, nonatomic, nullable) UIView* splashScreenView;
210
211 /**
212 * Attempts to set the `splashScreenView` property from the `UILaunchStoryboardName` from the
213 * main bundle's `Info.plist` file. This method will not change the value of `splashScreenView`
214 * if it cannot find a default one from a storyboard or nib.
215 *
216 * @return `YES` if successful, `NO` otherwise.
217 */
218 - (BOOL)loadDefaultSplashScreenView;
219
220 /**
221 * Controls whether the created view will be opaque or not.
222 *
223 * Default is `YES`. Note that setting this to `NO` may negatively impact performance
224 * when using hardware acceleration, and toggling this will trigger a re-layout of the
225 * view.
226 */
227 @property(nonatomic, getter=isViewOpaque) BOOL viewOpaque;
228
229 /**
230 * The `FlutterEngine` instance for this view controller. This could be the engine this
231 * `FlutterViewController` is initialized with or a new `FlutterEngine` implicitly created if
232 * no engine was supplied during initialization.
233 */
234 @property(weak, nonatomic, readonly) FlutterEngine* engine;
235
236 /**
237 * The `FlutterBinaryMessenger` associated with this FlutterViewController (used for communicating
238 * with channels).
239 *
240 * This is just a convenient way to get the |FlutterEngine|'s binary messenger.
241 */
242 @property(nonatomic, readonly) NSObject<FlutterBinaryMessenger>* binaryMessenger;
243
244 /**
245 * If the `FlutterViewController` creates a `FlutterEngine`, this property
246 * determines if that `FlutterEngine` has `allowHeadlessExecution` set.
247 *
248 * The intention is that this is used with the XIB. Otherwise, a
249 * `FlutterEngine` can just be sent to the init methods.
250 *
251 * See also: `-[FlutterEngine initWithName:project:allowHeadlessExecution:]`
252 */
253 @property(nonatomic, readonly) BOOL engineAllowHeadlessExecution;
254
255 @end
256
257 NS_ASSUME_NONNULL_END
258
259 #endif // FLUTTER_FLUTTERVIEWCONTROLLER_H_
FlutterViewController::engineAllowHeadlessExecution
BOOL engineAllowHeadlessExecution
Definition: FlutterViewController.h:253
FlutterEngine
Definition: FlutterEngine.h:59
+[FlutterViewController isUIAccessibilityIsVoiceOverRunning]
BOOL isUIAccessibilityIsVoiceOverRunning()
Definition: FlutterViewController.mm:2336
FlutterViewController
Definition: FlutterViewController.h:55
FlutterViewController::splashScreenView
UIView * splashScreenView
Definition: FlutterViewController.h:209
FlutterEngine.h
NS_ASSUME_NONNULL_END
#define NS_ASSUME_NONNULL_END
Definition: FlutterMacros.h:20
FlutterSemanticsUpdateNotification
FLUTTER_DARWIN_EXPORT const NSNotificationName FlutterSemanticsUpdateNotification
Definition: FlutterViewController.mm:41
FlutterTextureRegistry-p
Definition: FlutterTexture.h:38
FlutterPluginRegistry-p
Definition: FlutterPlugin.h:400
-[FlutterViewController popRoute]
void popRoute()
Definition: FlutterViewController.mm:446
FlutterTexture.h
FlutterViewController::viewOpaque
BOOL viewOpaque
Definition: FlutterViewController.h:227
NS_ASSUME_NONNULL_BEGIN
#define NS_ASSUME_NONNULL_BEGIN
Definition: FlutterMacros.h:19
FlutterMacros.h
FlutterPlugin.h
-[FlutterViewController loadDefaultSplashScreenView]
BOOL loadDefaultSplashScreenView()
Definition: FlutterViewController.mm:660
FlutterViewController::displayingFlutterUI
BOOL displayingFlutterUI
Definition: FlutterViewController.h:196
FlutterBinaryMessenger.h
initWithCoder
instancetype initWithCoder
Definition: FlutterTextInputPlugin.h:163
FlutterDartProject.h
engine
id engine
Definition: FlutterTextInputPluginTest.mm:89
-[FlutterViewController pluginRegistry]
id< FlutterPluginRegistry > pluginRegistry()
Definition: FlutterViewController.mm:2332
FLUTTER_DARWIN_EXPORT
#define FLUTTER_DARWIN_EXPORT
Definition: FlutterMacros.h:14
FlutterViewController::binaryMessenger
NSObject< FlutterBinaryMessenger > * binaryMessenger
Definition: FlutterViewController.h:242
FlutterDartProject
Definition: FlutterDartProject.mm:262
id
int32_t id
Definition: SemanticsObjectTestMocks.h:20