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 
12 #import "FlutterChannels.h"
13 #import "FlutterCodecs.h"
14 #import "FlutterPlatformViews.h"
15 #import "FlutterTexture.h"
16 
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  */
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  */
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  */
270  // NOLINTEND(readability-identifier-naming)
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 
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:45
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