| 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_FLUTTERPLUGIN_H_
6 #define FLUTTER_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 /**
254 * Flutter blocks all the UIGestureRecognizers on the platform view as soon as it
255 * decides they should be blocked.
256 *
257 * With this policy, only the `touchesBegan` method for all the UIGestureRecognizers is guaranteed
258 * to be called.
259 */
260 FlutterPlatformViewGestureRecognizersBlockingPolicyEager,
261 /**
262 * Flutter blocks the platform view's UIGestureRecognizers from recognizing only after
263 * touchesEnded was invoked.
264 *
265 * This results in the platform view's UIGestureRecognizers seeing the entire touch sequence,
266 * but never recognizing the gesture (and never invoking actions).
267 */
268 FlutterPlatformViewGestureRecognizersBlockingPolicyWaitUntilTouchesEnded,
269 } FlutterPlatformViewGestureRecognizersBlockingPolicy;
270
271 #pragma mark -
272 /**
273 * Registration context for a single `FlutterPlugin`, providing a one stop shop
274 * for the plugin to access contextual information and register callbacks for
275 * various application events.
276 *
277 * Registrars are obtained from a `FlutterPluginRegistry` which keeps track of
278 * the identity of registered plugins and provides basic support for cross-plugin
279 * coordination.
280 */
281 @protocol FlutterPluginRegistrar <NSObject>
282 /**
283 * Returns a `FlutterBinaryMessenger` for creating Dart/iOS communication
284 * channels to be used by the plugin.
285 *
286 * @return The messenger.
287 */
288 - (NSObject<FlutterBinaryMessenger>*)messenger;
289
290 /**
291 * Returns a `FlutterTextureRegistry` for registering textures
292 * provided by the plugin.
293 *
294 * @return The texture registry.
295 */
296 - (NSObject<FlutterTextureRegistry>*)textures;
297
298 /**
299 * Registers a `FlutterPlatformViewFactory` for creation of platform views.
300 *
301 * Plugins expose `UIView` for embedding in Flutter apps by registering a view factory.
302 *
303 * @param factory The view factory that will be registered.
304 * @param factoryId A unique identifier for the factory, the Dart code of the Flutter app can use
305 * this identifier to request creation of a `UIView` by the registered factory.
306 */
307 - (void)registerViewFactory:(NSObject<FlutterPlatformViewFactory>*)factory
308 withId:(NSString*)factoryId;
309
310 /**
311 * Registers a `FlutterPlatformViewFactory` for creation of platform views.
312 *
313 * Plugins can expose a `UIView` for embedding in Flutter apps by registering a view factory.
314 *
315 * @param factory The view factory that will be registered.
316 * @param factoryId A unique identifier for the factory, the Dart code of the Flutter app can use
317 * this identifier to request creation of a `UIView` by the registered factory.
318 * @param gestureRecognizersBlockingPolicy How UIGestureRecognizers on the platform views are
319 * blocked.
320 *
321 */
322 - (void)registerViewFactory:(NSObject<FlutterPlatformViewFactory>*)factory
323 withId:(NSString*)factoryId
324 gestureRecognizersBlockingPolicy:
325 (FlutterPlatformViewGestureRecognizersBlockingPolicy)gestureRecognizersBlockingPolicy;
326
327 /**
328 * Publishes a value for external use of the plugin.
329 *
330 * Plugins may publish a single value, such as an instance of the
331 * plugin's main class, for situations where external control or
332 * interaction is needed.
333 *
334 * The published value will be available from the `FlutterPluginRegistry`.
335 * Repeated calls overwrite any previous publication.
336 *
337 * @param value The value to be published.
338 */
339 - (void)publish:(NSObject*)value;
340
341 /**
342 * Registers the plugin as a receiver of incoming method calls from the Dart side
343 * on the specified `FlutterMethodChannel`.
344 *
345 * @param delegate The receiving object, such as the plugin's main class.
346 * @param channel The channel
347 */
348 - (void)addMethodCallDelegate:(NSObject<FlutterPlugin>*)delegate
349 channel:(FlutterMethodChannel*)channel;
350
351 /**
352 * Registers the plugin as a receiver of `UIApplicationDelegate` calls.
353 *
354 * @param delegate The receiving object, such as the plugin's main class.
355 */
356 - (void)addApplicationDelegate:(NSObject<FlutterPlugin>*)delegate
357 NS_EXTENSION_UNAVAILABLE_IOS("Disallowed in plugins used in app extensions");
358
359 /**
360 * Returns the file name for the given asset.
361 * The returned file name can be used to access the asset in the application's main bundle.
362 *
363 * @param asset The name of the asset. The name can be hierarchical.
364 * @return the file name to be used for lookup in the main bundle.
365 */
366 - (NSString*)lookupKeyForAsset:(NSString*)asset;
367
368 /**
369 * Returns the file name for the given asset which originates from the specified package.
370 * The returned file name can be used to access the asset in the application's main bundle.
371 *
372 *
373 * @param asset The name of the asset. The name can be hierarchical.
374 * @param package The name of the package from which the asset originates.
375 * @return the file name to be used for lookup in the main bundle.
376 */
377 - (NSString*)lookupKeyForAsset:(NSString*)asset fromPackage:(NSString*)package;
378 @end
379
380 #pragma mark -
381 /**
382 * A registry of Flutter iOS plugins.
383 *
384 * Plugins are identified by unique string keys, typically the name of the
385 * plugin's main class. The registry tracks plugins by this key, mapping it to
386 * a value published by the plugin during registration, if any. This provides a
387 * very basic means of cross-plugin coordination with loose coupling between
388 * unrelated plugins.
389 *
390 * Plugins typically need contextual information and the ability to register
391 * callbacks for various application events. To keep the API of the registry
392 * focused, these facilities are not provided directly by the registry, but by
393 * a `FlutterPluginRegistrar`, created by the registry in exchange for the unique
394 * key of the plugin.
395 *
396 * There is no implied connection between the registry and the registrar.
397 * Specifically, callbacks registered by the plugin via the registrar may be
398 * relayed directly to the underlying iOS application objects.
399 */
400 @protocol FlutterPluginRegistry <NSObject>
401 /**
402 * Returns a registrar for registering a plugin.
403 *
404 * @param pluginKey The unique key identifying the plugin.
405 */
406 - (nullable NSObject<FlutterPluginRegistrar>*)registrarForPlugin:(NSString*)pluginKey;
407 /**
408 * Returns whether the specified plugin has been registered.
409 *
410 * @param pluginKey The unique key identifying the plugin.
411 * @return `YES` if `registrarForPlugin` has been called with `pluginKey`.
412 */
413 - (BOOL)hasPlugin:(NSString*)pluginKey;
414
415 /**
416 * Returns a value published by the specified plugin.
417 *
418 * @param pluginKey The unique key identifying the plugin.
419 * @return An object published by the plugin, if any. Will be `NSNull` if
420 * nothing has been published. Will be `nil` if the plugin has not been
421 * registered.
422 */
423 - (nullable NSObject*)valuePublishedByPlugin:(NSString*)pluginKey;
424 @end
425
426 #pragma mark -
427 /**
428 * Implement this in the `UIAppDelegate` of your app to enable Flutter plugins to register
429 * themselves to the application life cycle events.
430 *
431 * For plugins to receive events from `UNUserNotificationCenter`, register this as the
432 * `UNUserNotificationCenterDelegate`.
433 */
434 @protocol FlutterAppLifeCycleProvider <UNUserNotificationCenterDelegate>
435
436 /**
437 * Called when registering a new `FlutterApplicaitonLifeCycleDelegate`.
438 *
439 * See also: `-[FlutterAppDelegate addApplicationLifeCycleDelegate:]`
440 */
441 - (void)addApplicationLifeCycleDelegate:(NSObject<FlutterApplicationLifeCycleDelegate>*)delegate;
442 @end
443
444 NS_ASSUME_NONNULL_END
445
446 #endif // FLUTTER_FLUTTERPLUGIN_H_
FlutterPlatformViews.h
FlutterPlugin-p
Definition: FlutterPlugin.h:189
FlutterPlatformViewGestureRecognizersBlockingPolicyWaitUntilTouchesEnded
@ FlutterPlatformViewGestureRecognizersBlockingPolicyWaitUntilTouchesEnded
Definition: FlutterPlugin.h:268
FlutterMethodChannel
Definition: FlutterChannels.h:222
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:281
FlutterMethodCall
Definition: FlutterCodecs.h:220
FlutterApplicationLifeCycleDelegate-p
Definition: FlutterPlugin.h:25
FlutterPlatformViewGestureRecognizersBlockingPolicyEager
@ FlutterPlatformViewGestureRecognizersBlockingPolicyEager
Definition: FlutterPlugin.h:260
FlutterBinaryMessenger.h
FlutterResult
void(^ FlutterResult)(id _Nullable result)
Definition: FlutterChannels.h:196
FlutterCodecs.h
FlutterPlatformViewGestureRecognizersBlockingPolicy
FlutterPlatformViewGestureRecognizersBlockingPolicy
Definition: FlutterPlugin.h:252
FlutterAppLifeCycleProvider-p
Definition: FlutterPlugin.h:434
FlutterPlatformViewFactory-p
Definition: FlutterPlatformViews.h:26
-[FlutterPluginRegistrar-p messenger]
NSObject< FlutterBinaryMessenger > * messenger()
-[FlutterPluginRegistrar-p textures]
NSObject< FlutterTextureRegistry > * textures()
FlutterBinaryMessenger-p
Definition: FlutterBinaryMessenger.h:48