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