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