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 
12 #import "FlutterDartProject.h"
13 #import "FlutterEngine.h"
14 #import "FlutterMacros.h"
15 #import "FlutterPlugin.h"
16 #import "FlutterTexture.h"
17 
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  */
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://docs.flutter.cn/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  */
52 #ifdef __IPHONE_13_4
53 @interface FlutterViewController
54  : UIViewController <FlutterTextureRegistry, FlutterPluginRegistry, UIGestureRecognizerDelegate>
55 #else
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  */
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  */
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 
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:2397
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:45
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:171
FlutterDartProject.h
engine
id engine
Definition: FlutterTextInputPluginTest.mm:89
-[FlutterViewController pluginRegistry]
id< FlutterPluginRegistry > pluginRegistry()
Definition: FlutterViewController.mm:2393
FLUTTER_DARWIN_EXPORT
#define FLUTTER_DARWIN_EXPORT
Definition: FlutterMacros.h:14
FlutterViewController::binaryMessenger
NSObject< FlutterBinaryMessenger > * binaryMessenger
Definition: FlutterViewController.h:243
FlutterDartProject
Definition: FlutterDartProject.mm:262