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