| Flutter iOS Embedder |

FlutterSceneLifeCycle.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_FLUTTERSCENELIFECYCLE_H_
6 #define FLUTTER_SHELL_PLATFORM_DARWIN_IOS_FRAMEWORK_HEADERS_FLUTTERSCENELIFECYCLE_H_
7
8 #import <UIKit/UIKit.h>
9 #import "FlutterMacros.h"
10
11 NS_ASSUME_NONNULL_BEGIN
12
13 @class FlutterEngine;
14
15 /**
16 * A protocol for delegates that handle `UISceneDelegate` and `UIWindowSceneDelegate` life-cycle
17 * events.
18 *
19 * This protocol provides a way for Flutter plugins to observe and react to scene-based life-cycle
20 * events. The methods in this protocol correspond to methods in `UISceneDelegate` and
21 * `UIWindowSceneDelegate`.
22 *
23 * See also:
24 *
25 * * `UISceneDelegate`, core methods you use to respond to life-cycle events occurring within a
26 * scene: https://developer.apple.com/documentation/uikit/uiscenedelegate
27 * * `UIWindowSceneDelegate`, additional methods that you use to manage app-specific tasks
28 * occurring in a scene: https://developer.apple.com/documentation/uikit/uiwindowscenedelegate
29 */
30 API_AVAILABLE(ios(13.0))
31 @protocol FlutterSceneLifeCycleDelegate <NSObject>
32
33 @optional
34
35 #pragma mark - Connecting and disconnecting the scene
36
37 /**
38 * Informs the delegate that a new scene is about to be connected and configured.
39 *
40 * This corresponds to `-[UISceneDelegate scene:willConnectToSession:options:]`. `connectionOptions`
41 * may be nil if another plugin has already handled the connection.
42 *
43 * @return `YES` if this handled the connection.
44 */
45 - (BOOL)scene:(UIScene*)scene
46 willConnectToSession:(UISceneSession*)session
47 options:(nullable UISceneConnectionOptions*)connectionOptions;
48
49 - (void)sceneDidDisconnect:(UIScene*)scene;
50
51 #pragma mark - Transitioning to the foreground
52
53 - (void)sceneWillEnterForeground:(UIScene*)scene;
54
55 - (void)sceneDidBecomeActive:(UIScene*)scene;
56
57 #pragma mark - Transitioning to the background
58
59 - (void)sceneWillResignActive:(UIScene*)scene;
60
61 - (void)sceneDidEnterBackground:(UIScene*)scene;
62
63 #pragma mark - Opening URLs
64
65 /**
66 * Asks the delegate to open one or more URLs.
67 *
68 * This corresponds to `-[UISceneDelegate scene:openURLContexts:]`.
69 *
70 * @return `YES` if this handled one or more of the URLs.
71 */
72 - (BOOL)scene:(UIScene*)scene openURLContexts:(NSSet<UIOpenURLContext*>*)URLContexts;
73
74 #pragma mark - Continuing user activities
75
76 /**
77 * Tells the delegate that the scene is continuing a user activity.
78 *
79 * This corresponds to `-[UISceneDelegate scene:continueUserActivity:]`.
80 *
81 * @return `YES` if this handled the activity.
82 */
83 - (BOOL)scene:(UIScene*)scene continueUserActivity:(NSUserActivity*)userActivity;
84
85 #pragma mark - Performing tasks
86
87 /**
88 * Tells the delegate that the user has selected a home screen quick action.
89 *
90 * This corresponds to `-[UIWindowSceneDelegate
91 * windowScene:performActionForShortcutItem:completionHandler:]`.
92 *
93 * @return `YES` if this handled the shortcut.
94 */
95 - (BOOL)windowScene:(UIWindowScene*)windowScene
96 performActionForShortcutItem:(UIApplicationShortcutItem*)shortcutItem
97 completionHandler:(void (^)(BOOL succeeded))completionHandler;
98
99 @end
100
101 /**
102 * A protocol for manually registering a `FlutterEngine` to receive scene life cycle events.
103 */
104 @protocol FlutterSceneLifeCycleEngineRegistration
105 /**
106 * Registers a `FlutterEngine` to receive scene life cycle events.
107 *
108 * This method is **only** necessary when the following conditions are true:
109 * 1. Multiple Scenes (UIApplicationSupportsMultipleScenes) is enabled.
110 * 2. The `UIWindowSceneDelegate` `window.rootViewController` is not a `FlutterViewController`
111 * initialized with the target `FlutterEngine`.
112 *
113 * When multiple scenes is enabled (UIApplicationSupportsMultipleScenes), Flutter cannot
114 * automatically associate a `FlutterEngine` with a scene during the scene connection phase. In
115 * order for plugins to receive launch connection information, the `FlutterEngine` must be manually
116 * registered with either the `FlutterSceneDelegate` or `FlutterPluginSceneLifeCycleDelegate` during
117 * `scene:willConnectToSession:options:`.
118 *
119 * In all other cases, or once the `FlutterViewController.view` associated with the `FlutterEngine`
120 * is added to the view hierarchy, Flutter will automatically handle registration for scene events.
121 *
122 * Manually registered engines must also be manually deregistered and re-registered if they
123 * switch scenes. Use `unregisterSceneLifeCycleWithFlutterEngine:`.
124 *
125 * @param engine The `FlutterEngine` to register for scene life cycle events.
126 * @return `NO` if already manually registered.
127 */
128 - (BOOL)registerSceneLifeCycleWithFlutterEngine:(FlutterEngine*)engine;
129
130 /**
131 * Use this method to unregister a `FlutterEngine` from the scene's life cycle events.
132 *
133 * @param engine The `FlutterEngine` to unregister for scene life cycle events.
134 * @return `NO` if the engine was not found among the manually registered engines and could not be
135 * unregistered.
136 */
137 - (BOOL)unregisterSceneLifeCycleWithFlutterEngine:(FlutterEngine*)engine;
138 @end
139
140 /**
141 * Forwards `UISceneDelegate` and `UIWindowSceneDelegate` callbacks to plugins that register for
142 * them.
143 *
144 * This class is responsible for receiving `UISceneDelegate` and `UIWindowSceneDelegate` callbacks
145 * and forwarding them to any plugins.
146 */
147 FLUTTER_DARWIN_EXPORT
148 API_AVAILABLE(ios(13.0))
149 @interface FlutterPluginSceneLifeCycleDelegate : NSObject <FlutterSceneLifeCycleEngineRegistration>
150
151 #pragma mark - Connecting and disconnecting the scene
152
153 /**
154 * Calls all plugins registered for `UIWindowScene` callbacks in order of registration until
155 * a plugin handles the request.
156 */
157 - (void)scene:(UIScene*)scene
158 willConnectToSession:(UISceneSession*)session
159 options:(UISceneConnectionOptions*)connectionOptions;
160
161 - (void)sceneDidDisconnect:(UIScene*)scene;
162
163 #pragma mark - Transitioning to the foreground
164
165 - (void)sceneWillEnterForeground:(UIScene*)scene;
166
167 - (void)sceneDidBecomeActive:(UIScene*)scene;
168
169 #pragma mark - Transitioning to the background
170
171 - (void)sceneWillResignActive:(UIScene*)scene;
172
173 - (void)sceneDidEnterBackground:(UIScene*)scene;
174
175 #pragma mark - Opening URLs
176
177 /**
178 * Calls all plugins registered for `UIWindowScene` callbacks in order of registration until
179 * a plugin handles the request.
180 */
181 - (void)scene:(UIScene*)scene openURLContexts:(NSSet<UIOpenURLContext*>*)URLContexts;
182
183 #pragma mark - Continuing user activities
184
185 /**
186 * Calls all plugins registered for `UIWindowScene` callbacks in order of registration until
187 * a plugin handles the request.
188 */
189 - (void)scene:(UIScene*)scene continueUserActivity:(NSUserActivity*)userActivity;
190
191 #pragma mark - Performing tasks
192
193 /**
194 * Calls all plugins registered for `UIWindowScene` callbacks in order of registration until
195 * a plugin handles the request.
196 */
197 - (void)windowScene:(UIWindowScene*)windowScene
198 performActionForShortcutItem:(UIApplicationShortcutItem*)shortcutItem
199 completionHandler:(void (^)(BOOL succeeded))completionHandler;
200
201 @end
202
203 /**
204 * A protocol for `UIWindowSceneDelegate` objects that vend a `FlutterPluginSceneLifeCycleDelegate`.
205 *
206 * By conforming to this protocol, a `UIWindowSceneDelegate` can vend a
207 * `FlutterPluginSceneLifeCycleDelegate` that can be used to forward scene life-cycle events to
208 * Flutter plugins.
209 *
210 * This is typically implemented by the app's `SceneDelegate`, as a `FlutterSceneLifeCycleProvider`
211 * is associated with one and only one `UIScene`.
212 */
213 API_AVAILABLE(ios(13.0))
214 @protocol FlutterSceneLifeCycleProvider
215
216 /**
217 * The `FlutterPluginSceneLifeCycleDelegate` instance for forwarding `UIScene` events
218 * to plugins associated with this `UIScene`.
219 *
220 * The implementer of this protocol is responsible for creating the
221 * `FlutterPluginSceneLifeCycleDelegate` object, as well as forwarding `UIScene` events
222 * to plugins by calling the corresponding methods defined on
223 * `FlutterPluginSceneLifeCycleDelegate`.
224 *
225 * The `FlutterPluginSceneLifeCycleDelegate` implementation is stateful. For this reason,
226 * this property getter should typically always return the same object.
227 */
228 @property(nonatomic, readonly) FlutterPluginSceneLifeCycleDelegate* sceneLifeCycleDelegate;
229 @end
230
231 NS_ASSUME_NONNULL_END
232
233 #endif // FLUTTER_SHELL_PLATFORM_DARWIN_IOS_FRAMEWORK_HEADERS_FLUTTERSCENELIFECYCLE_H_
FlutterMacros.h
NS_ASSUME_NONNULL_BEGIN
#define NS_ASSUME_NONNULL_BEGIN
Definition: FlutterMacros.h:19
NS_ASSUME_NONNULL_END
#define NS_ASSUME_NONNULL_END
Definition: FlutterMacros.h:20
FLUTTER_DARWIN_EXPORT
#define FLUTTER_DARWIN_EXPORT
Definition: FlutterMacros.h:14
API_AVAILABLE
UITextSmartQuotesType smartQuotesType API_AVAILABLE(ios(11.0))
FlutterEngine
Definition: FlutterEngine.h:61
FlutterPluginSceneLifeCycleDelegate
Definition: FlutterSceneLifeCycle.h:149
FlutterSceneLifeCycleDelegate-p
Definition: FlutterSceneLifeCycle.h:31
FlutterSceneLifeCycleEngineRegistration-p
Definition: FlutterSceneLifeCycle.h:104
FlutterSceneLifeCycleProvider-p
Definition: FlutterSceneLifeCycle.h:214
FlutterSceneLifeCycleProvider-p::sceneLifeCycleDelegate
FlutterPluginSceneLifeCycleDelegate * sceneLifeCycleDelegate
Definition: FlutterSceneLifeCycle.h:228