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 
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 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  */
51 #ifdef __IPHONE_13_4
52 @interface FlutterViewController
53  : UIViewController <FlutterTextureRegistry, FlutterPluginRegistry, UIGestureRecognizerDelegate>
54 #else
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  */
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  */
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 
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