| Flutter iOS Embedder |

FlutterPlugin.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_FLUTTERPLUGIN_H_
6 #define FLUTTER_SHELL_PLATFORM_DARWIN_IOS_FRAMEWORK_HEADERS_FLUTTERPLUGIN_H_
7
8 #import <UIKit/UIKit.h>
9 #import <UserNotifications/UNUserNotificationCenter.h>
10
11 #import "FlutterBinaryMessenger.h"
12 #import "FlutterChannels.h"
13 #import "FlutterCodecs.h"
14 #import "FlutterPlatformViews.h"
15 #import "FlutterTexture.h"
16
17 NS_ASSUME_NONNULL_BEGIN
18 @protocol FlutterPluginRegistrar;
19 @protocol FlutterPluginRegistry;
20
21 #pragma mark -
22 /**
23 * Protocol for listener of events from the UIApplication, typically a FlutterPlugin.
24 */
25 @protocol FlutterApplicationLifeCycleDelegate <UNUserNotificationCenterDelegate>
26
27 @optional
28 /**
29 * Called if this has been registered for `UIApplicationDelegate` callbacks.
30 *
31 * @return `NO` if this vetos application launch.
32 */
33 - (BOOL)application:(UIApplication*)application
34 didFinishLaunchingWithOptions:(NSDictionary*)launchOptions;
35
36 /**
37 * Called if this has been registered for `UIApplicationDelegate` callbacks.
38 *
39 * @return `NO` if this vetos application launch.
40 */
41 - (BOOL)application:(UIApplication*)application
42 willFinishLaunchingWithOptions:(NSDictionary*)launchOptions;
43
44 /**
45 * Called if this has been registered for `UIApplicationDelegate` callbacks.
46 */
47 - (void)applicationDidBecomeActive:(UIApplication*)application;
48
49 /**
50 * Called if this has been registered for `UIApplicationDelegate` callbacks.
51 */
52 - (void)applicationWillResignActive:(UIApplication*)application;
53
54 /**
55 * Called if this has been registered for `UIApplicationDelegate` callbacks.
56 */
57 - (void)applicationDidEnterBackground:(UIApplication*)application;
58
59 /**
60 * Called if this has been registered for `UIApplicationDelegate` callbacks.
61 */
62 - (void)applicationWillEnterForeground:(UIApplication*)application;
63
64 /**
65 Called if this has been registered for `UIApplicationDelegate` callbacks.
66 */
67 - (void)applicationWillTerminate:(UIApplication*)application;
68
69 /**
70 * Called if this has been registered for `UIApplicationDelegate` callbacks.
71 */
72 - (void)application:(UIApplication*)application
73 didRegisterUserNotificationSettings:(UIUserNotificationSettings*)notificationSettings
74 API_DEPRECATED(
75 "See -[UIApplicationDelegate application:didRegisterUserNotificationSettings:] deprecation",
76 ios(8.0, 10.0));
77
78 /**
79 * Called if this has been registered for `UIApplicationDelegate` callbacks.
80 */
81 - (void)application:(UIApplication*)application
82 didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken;
83
84 /**
85 * Called if this has been registered for `UIApplicationDelegate` callbacks.
86 */
87 - (void)application:(UIApplication*)application
88 didFailToRegisterForRemoteNotificationsWithError:(NSError*)error;
89
90 /**
91 * Called if this has been registered for `UIApplicationDelegate` callbacks.
92 *
93 * @return `YES` if this handles the request.
94 */
95 - (BOOL)application:(UIApplication*)application
96 didReceiveRemoteNotification:(NSDictionary*)userInfo
97 fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler;
98
99 /**
100 * Calls all plugins registered for `UIApplicationDelegate` callbacks.
101 */
102 - (void)application:(UIApplication*)application
103 didReceiveLocalNotification:(UILocalNotification*)notification
104 API_DEPRECATED(
105 "See -[UIApplicationDelegate application:didReceiveLocalNotification:] deprecation",
106 ios(4.0, 10.0));
107
108 /**
109 * Called if this has been registered for `UIApplicationDelegate` callbacks.
110 *
111 * @return `YES` if this handles the request.
112 */
113 - (BOOL)application:(UIApplication*)application
114 openURL:(NSURL*)url
115 options:(NSDictionary<UIApplicationOpenURLOptionsKey, id>*)options;
116
117 /**
118 * Called if this has been registered for `UIApplicationDelegate` callbacks.
119 *
120 * @return `YES` if this handles the request.
121 */
122 - (BOOL)application:(UIApplication*)application handleOpenURL:(NSURL*)url;
123
124 /**
125 * Called if this has been registered for `UIApplicationDelegate` callbacks.
126 *
127 * @return `YES` if this handles the request.
128 */
129 - (BOOL)application:(UIApplication*)application
130 openURL:(NSURL*)url
131 sourceApplication:(NSString*)sourceApplication
132 annotation:(id)annotation;
133
134 /**
135 * Called if this has been registered for `UIApplicationDelegate` callbacks.
136 *
137 * @return `YES` if this handles the request.
138 */
139 - (BOOL)application:(UIApplication*)application
140 performActionForShortcutItem:(UIApplicationShortcutItem*)shortcutItem
141 completionHandler:(void (^)(BOOL succeeded))completionHandler
142 API_AVAILABLE(ios(9.0));
143
144 /**
145 * Called if this has been registered for `UIApplicationDelegate` callbacks.
146 *
147 * @return `YES` if this handles the request.
148 */
149 - (BOOL)application:(UIApplication*)application
150 handleEventsForBackgroundURLSession:(nonnull NSString*)identifier
151 completionHandler:(nonnull void (^)(void))completionHandler;
152
153 /**
154 * Called if this has been registered for `UIApplicationDelegate` callbacks.
155 *
156 * @return `YES` if this handles the request.
157 */
158 - (BOOL)application:(UIApplication*)application
159 performFetchWithCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler;
160
161 /**
162 * Called if this has been registered for `UIApplicationDelegate` callbacks.
163 *
164 * @return `YES` if this handles the request.
165 */
166 - (BOOL)application:(UIApplication*)application
167 continueUserActivity:(NSUserActivity*)userActivity
168 restorationHandler:(void (^)(NSArray*))restorationHandler;
169 @end
170
171 #pragma mark -
172 /**
173 * A plugin registration callback.
174 *
175 * Used for registering plugins with additional instances of
176 * `FlutterPluginRegistry`.
177 *
178 * @param registry The registry to register plugins with.
179 */
180 typedef void (*FlutterPluginRegistrantCallback)(NSObject<FlutterPluginRegistry>* registry);
181
182 #pragma mark -
183 /**
184 * Implemented by the iOS part of a Flutter plugin.
185 *
186 * Defines a set of optional callback methods and a method to set up the plugin
187 * and register it to be called by other application components.
188 */
189 @protocol FlutterPlugin <NSObject, FlutterApplicationLifeCycleDelegate>
190 @required
191 /**
192 * Registers this plugin using the context information and callback registration
193 * methods exposed by the given registrar.
194 *
195 * The registrar is obtained from a `FlutterPluginRegistry` which keeps track of
196 * the identity of registered plugins and provides basic support for cross-plugin
197 * coordination.
198 *
199 * The caller of this method, a plugin registrant, is usually autogenerated by
200 * Flutter tooling based on declared plugin dependencies. The generated registrant
201 * asks the registry for a registrar for each plugin, and calls this method to
202 * allow the plugin to initialize itself and register callbacks with application
203 * objects available through the registrar protocol.
204 *
205 * @param registrar A helper providing application context and methods for
206 * registering callbacks.
207 */
208 + (void)registerWithRegistrar:(NSObject<FlutterPluginRegistrar>*)registrar;
209 @optional
210 /**
211 * Set a callback for registering plugins to an additional `FlutterPluginRegistry`,
212 * including headless `FlutterEngine` instances.
213 *
214 * This method is typically called from within an application's `AppDelegate` at
215 * startup to allow for plugins which create additional `FlutterEngine` instances
216 * to register the application's plugins.
217 *
218 * @param callback A callback for registering some set of plugins with a
219 * `FlutterPluginRegistry`.
220 */
221 + (void)setPluginRegistrantCallback:(FlutterPluginRegistrantCallback)callback;
222 @optional
223 /**
224 * Called if this plugin has been registered to receive `FlutterMethodCall`s.
225 *
226 * @param call The method call command object.
227 * @param result A callback for submitting the result of the call.
228 */
229 - (void)handleMethodCall:(FlutterMethodCall*)call result:(FlutterResult)result;
230 @optional
231 /**
232 * Called when a plugin is being removed from a `FlutterEngine`, which is
233 * usually the result of the `FlutterEngine` being deallocated. This method
234 * provides the opportunity to do necessary cleanup.
235 *
236 * You will only receive this method if you registered your plugin instance with
237 * the `FlutterEngine` via `-[FlutterPluginRegistry publish:]`.
238 *
239 * @param registrar The registrar that was used to publish the plugin.
240 *
241 */
242 - (void)detachFromEngineForRegistrar:(NSObject<FlutterPluginRegistrar>*)registrar;
243 @end
244
245 #pragma mark -
246 /**
247 * How the UIGestureRecognizers of a platform view are blocked.
248 *
249 * UIGestureRecognizers of platform views can be blocked based on decisions made by the
250 * Flutter Framework (e.g. When an interact-able widget is covering the platform view).
251 */
252 typedef enum {
253 // NOLINTBEGIN(readability-identifier-naming)
254 /**
255 * Flutter blocks all the UIGestureRecognizers on the platform view as soon as it
256 * decides they should be blocked.
257 *
258 * With this policy, only the `touchesBegan` method for all the UIGestureRecognizers is guaranteed
259 * to be called.
260 */
261 FlutterPlatformViewGestureRecognizersBlockingPolicyEager,
262 /**
263 * Flutter blocks the platform view's UIGestureRecognizers from recognizing only after
264 * touchesEnded was invoked.
265 *
266 * This results in the platform view's UIGestureRecognizers seeing the entire touch sequence,
267 * but never recognizing the gesture (and never invoking actions).
268 */
269 FlutterPlatformViewGestureRecognizersBlockingPolicyWaitUntilTouchesEnded,
270 // NOLINTEND(readability-identifier-naming)
271 } FlutterPlatformViewGestureRecognizersBlockingPolicy;
272
273 #pragma mark -
274 /**
275 * Registration context for a single `FlutterPlugin`, providing a one stop shop
276 * for the plugin to access contextual information and register callbacks for
277 * various application events.
278 *
279 * Registrars are obtained from a `FlutterPluginRegistry` which keeps track of
280 * the identity of registered plugins and provides basic support for cross-plugin
281 * coordination.
282 */
283 @protocol FlutterPluginRegistrar <NSObject>
284 /**
285 * Returns a `FlutterBinaryMessenger` for creating Dart/iOS communication
286 * channels to be used by the plugin.
287 *
288 * @return The messenger.
289 */
290 - (NSObject<FlutterBinaryMessenger>*)messenger;
291
292 /**
293 * Returns a `FlutterTextureRegistry` for registering textures
294 * provided by the plugin.
295 *
296 * @return The texture registry.
297 */
298 - (NSObject<FlutterTextureRegistry>*)textures;
299
300 /**
301 * Registers a `FlutterPlatformViewFactory` for creation of platform views.
302 *
303 * Plugins expose `UIView` for embedding in Flutter apps by registering a view factory.
304 *
305 * @param factory The view factory that will be registered.
306 * @param factoryId A unique identifier for the factory, the Dart code of the Flutter app can use
307 * this identifier to request creation of a `UIView` by the registered factory.
308 */
309 - (void)registerViewFactory:(NSObject<FlutterPlatformViewFactory>*)factory
310 withId:(NSString*)factoryId;
311
312 /**
313 * Registers a `FlutterPlatformViewFactory` for creation of platform views.
314 *
315 * Plugins can expose a `UIView` for embedding in Flutter apps by registering a view factory.
316 *
317 * @param factory The view factory that will be registered.
318 * @param factoryId A unique identifier for the factory, the Dart code of the Flutter app can use
319 * this identifier to request creation of a `UIView` by the registered factory.
320 * @param gestureRecognizersBlockingPolicy How UIGestureRecognizers on the platform views are
321 * blocked.
322 *
323 */
324 - (void)registerViewFactory:(NSObject<FlutterPlatformViewFactory>*)factory
325 withId:(NSString*)factoryId
326 gestureRecognizersBlockingPolicy:
327 (FlutterPlatformViewGestureRecognizersBlockingPolicy)gestureRecognizersBlockingPolicy;
328
329 /**
330 * Publishes a value for external use of the plugin.
331 *
332 * Plugins may publish a single value, such as an instance of the
333 * plugin's main class, for situations where external control or
334 * interaction is needed.
335 *
336 * The published value will be available from the `FlutterPluginRegistry`.
337 * Repeated calls overwrite any previous publication.
338 *
339 * @param value The value to be published.
340 */
341 - (void)publish:(NSObject*)value;
342
343 /**
344 * Registers the plugin as a receiver of incoming method calls from the Dart side
345 * on the specified `FlutterMethodChannel`.
346 *
347 * @param delegate The receiving object, such as the plugin's main class.
348 * @param channel The channel
349 */
350 - (void)addMethodCallDelegate:(NSObject<FlutterPlugin>*)delegate
351 channel:(FlutterMethodChannel*)channel;
352
353 /**
354 * Registers the plugin as a receiver of `UIApplicationDelegate` calls.
355 *
356 * @param delegate The receiving object, such as the plugin's main class.
357 */
358 - (void)addApplicationDelegate:(NSObject<FlutterPlugin>*)delegate
359 NS_EXTENSION_UNAVAILABLE_IOS("Disallowed in plugins used in app extensions");
360
361 /**
362 * Returns the file name for the given asset.
363 * The returned file name can be used to access the asset in the application's main bundle.
364 *
365 * @param asset The name of the asset. The name can be hierarchical.
366 * @return the file name to be used for lookup in the main bundle.
367 */
368 - (NSString*)lookupKeyForAsset:(NSString*)asset;
369
370 /**
371 * Returns the file name for the given asset which originates from the specified package.
372 * The returned file name can be used to access the asset in the application's main bundle.
373 *
374 *
375 * @param asset The name of the asset. The name can be hierarchical.
376 * @param package The name of the package from which the asset originates.
377 * @return the file name to be used for lookup in the main bundle.
378 */
379 - (NSString*)lookupKeyForAsset:(NSString*)asset fromPackage:(NSString*)package;
380 @end
381
382 #pragma mark -
383 /**
384 * A registry of Flutter iOS plugins.
385 *
386 * Plugins are identified by unique string keys, typically the name of the
387 * plugin's main class. The registry tracks plugins by this key, mapping it to
388 * a value published by the plugin during registration, if any. This provides a
389 * very basic means of cross-plugin coordination with loose coupling between
390 * unrelated plugins.
391 *
392 * Plugins typically need contextual information and the ability to register
393 * callbacks for various application events. To keep the API of the registry
394 * focused, these facilities are not provided directly by the registry, but by
395 * a `FlutterPluginRegistrar`, created by the registry in exchange for the unique
396 * key of the plugin.
397 *
398 * There is no implied connection between the registry and the registrar.
399 * Specifically, callbacks registered by the plugin via the registrar may be
400 * relayed directly to the underlying iOS application objects.
401 */
402 @protocol FlutterPluginRegistry <NSObject>
403 /**
404 * Returns a registrar for registering a plugin.
405 *
406 * @param pluginKey The unique key identifying the plugin.
407 */
408 - (nullable NSObject<FlutterPluginRegistrar>*)registrarForPlugin:(NSString*)pluginKey;
409 /**
410 * Returns whether the specified plugin has been registered.
411 *
412 * @param pluginKey The unique key identifying the plugin.
413 * @return `YES` if `registrarForPlugin` has been called with `pluginKey`.
414 */
415 - (BOOL)hasPlugin:(NSString*)pluginKey;
416
417 /**
418 * Returns a value published by the specified plugin.
419 *
420 * @param pluginKey The unique key identifying the plugin.
421 * @return An object published by the plugin, if any. Will be `NSNull` if
422 * nothing has been published. Will be `nil` if the plugin has not been
423 * registered.
424 */
425 - (nullable NSObject*)valuePublishedByPlugin:(NSString*)pluginKey;
426 @end
427
428 #pragma mark -
429 /**
430 * Implement this in the `UIAppDelegate` of your app to enable Flutter plugins to register
431 * themselves to the application life cycle events.
432 *
433 * For plugins to receive events from `UNUserNotificationCenter`, register this as the
434 * `UNUserNotificationCenterDelegate`.
435 */
436 @protocol FlutterAppLifeCycleProvider <UNUserNotificationCenterDelegate>
437
438 /**
439 * Called when registering a new `FlutterApplicaitonLifeCycleDelegate`.
440 *
441 * See also: `-[FlutterAppDelegate addApplicationLifeCycleDelegate:]`
442 */
443 - (void)addApplicationLifeCycleDelegate:(NSObject<FlutterApplicationLifeCycleDelegate>*)delegate;
444 @end
445
446 NS_ASSUME_NONNULL_END
447
448 #endif // FLUTTER_SHELL_PLATFORM_DARWIN_IOS_FRAMEWORK_HEADERS_FLUTTERPLUGIN_H_
FlutterPlatformViews.h
FlutterPlugin-p
Definition: FlutterPlugin.h:189
FlutterPlatformViewGestureRecognizersBlockingPolicyWaitUntilTouchesEnded
@ FlutterPlatformViewGestureRecognizersBlockingPolicyWaitUntilTouchesEnded
Definition: FlutterPlugin.h:269
FlutterMethodChannel
Definition: FlutterChannels.h:220
NS_ASSUME_NONNULL_END
#define NS_ASSUME_NONNULL_END
Definition: FlutterMacros.h:20
FlutterTextureRegistry-p
Definition: FlutterTexture.h:38
FlutterTexture.h
FlutterChannels.h
NS_ASSUME_NONNULL_BEGIN
#define NS_ASSUME_NONNULL_BEGIN
Definition: FlutterMacros.h:19
FlutterPluginRegistrantCallback
void(* FlutterPluginRegistrantCallback)(NSObject< FlutterPluginRegistry > *registry)
Definition: FlutterPlugin.h:180
FlutterPluginRegistrar-p
Definition: FlutterPlugin.h:283
FlutterMethodCall
Definition: FlutterCodecs.h:220
FlutterApplicationLifeCycleDelegate-p
Definition: FlutterPlugin.h:25
FlutterPlatformViewGestureRecognizersBlockingPolicyEager
@ FlutterPlatformViewGestureRecognizersBlockingPolicyEager
Definition: FlutterPlugin.h:261
FlutterBinaryMessenger.h
FlutterResult
void(^ FlutterResult)(id _Nullable result)
Definition: FlutterChannels.h:194
FlutterCodecs.h
FlutterPlatformViewGestureRecognizersBlockingPolicy
FlutterPlatformViewGestureRecognizersBlockingPolicy
Definition: FlutterPlugin.h:252
FlutterAppLifeCycleProvider-p
Definition: FlutterPlugin.h:436
FlutterPlatformViewFactory-p
Definition: FlutterPlatformViews.h:26
-[FlutterPluginRegistrar-p messenger]
NSObject< FlutterBinaryMessenger > * messenger()
-[FlutterPluginRegistrar-p textures]
NSObject< FlutterTextureRegistry > * textures()
FlutterBinaryMessenger-p
Definition: FlutterBinaryMessenger.h:49