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