Flutter macOS Embedder
FlutterPluginRegistrarMacOS.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_MACOS_FRAMEWORK_HEADERS_FLUTTERPLUGINREGISTRARMACOS_H_
6 #define FLUTTER_SHELL_PLATFORM_DARWIN_MACOS_FRAMEWORK_HEADERS_FLUTTERPLUGINREGISTRARMACOS_H_
7 
8 #import <Cocoa/Cocoa.h>
9 
11 #import "FlutterChannels.h"
12 #import "FlutterMacros.h"
13 #import "FlutterPlatformViews.h"
14 #import "FlutterPluginMacOS.h"
15 #import "FlutterTexture.h"
16 
17 // TODO(stuartmorgan): Merge this file and FlutterPluginMacOS.h with the iOS FlutterPlugin.h,
18 // sharing all but the platform-specific methods.
19 
20 /**
21  * The protocol for an object managing registration for a plugin. It provides access to application
22  * context, as allowing registering for callbacks for handling various conditions.
23  *
24  * Currently the macOS PluginRegistrar has very limited functionality, but is expected to expand
25  * over time to more closely match the functionality of FlutterPluginRegistrar.
26  */
28 @protocol FlutterPluginRegistrar <NSObject>
29 
30 /**
31  * The unique identifier for the `FlutterEngine` associated with this registrar.
32  *
33  * This corresponds to `PlatformDispatcher.instance.engineId` in Dart.
34  */
35 @property(nonatomic, readonly) int64_t engineIdentifier;
36 
37 /**
38  * The binary messenger used for creating channels to communicate with the Flutter engine.
39  */
40 @property(nonnull, readonly) id<FlutterBinaryMessenger> messenger;
41 
42 /**
43  * Returns a `FlutterTextureRegistry` for registering textures
44  * provided by the plugin.
45  */
46 @property(nonnull, readonly) id<FlutterTextureRegistry> textures;
47 
48 /**
49  * The view displaying Flutter content.
50  *
51  * This property is provided for backwards compatibility for apps
52  * that assume a single view. This will eventually be replaced by
53  * a multi-view API variant.
54  *
55  * This method may return |nil|, for instance in a headless environment.
56  */
57 @property(nullable, readonly) NSView* view;
58 
59 /**
60  * The `NSViewController` that hosts |view|.
61  *
62  * The plugin typically should not store a strong reference to this view
63  * controller.
64  *
65  * This property is provided for backwards compatibility for apps that assume
66  * a single view, and will eventually be replaced by the multi-view API variant.
67  *
68  * This property is |nil| when |view| is |nil|.
69  */
70 @property(nullable, readonly) NSViewController* viewController;
71 
72 /**
73  * Registers |delegate| to receive handleMethodCall:result: callbacks for the given |channel|.
74  */
75 - (void)addMethodCallDelegate:(nonnull id<FlutterPlugin>)delegate
76  channel:(nonnull FlutterMethodChannel*)channel;
77 
78 /**
79  * Registers the plugin as a receiver of `NSApplicationDelegate` calls.
80  *
81  * @param delegate The receiving object, such as the plugin's main class.
82  */
83 - (void)addApplicationDelegate:(nonnull NSObject<FlutterAppLifecycleDelegate>*)delegate;
84 
85 /**
86  * Registers a `FlutterPlatformViewFactory` for creation of platform views.
87  *
88  * Plugins expose `NSView` for embedding in Flutter apps by registering a view factory.
89  *
90  * @param factory The view factory that will be registered.
91  * @param factoryId A unique identifier for the factory, the Dart code of the Flutter app can use
92  * this identifier to request creation of a `NSView` by the registered factory.
93  */
94 - (void)registerViewFactory:(nonnull NSObject<FlutterPlatformViewFactory>*)factory
95  withId:(nonnull NSString*)factoryId;
96 
97 /**
98  * Publishes a value for external use of the plugin.
99  *
100  * Plugins may publish a single value, such as an instance of the
101  * plugin's main class, for situations where external control or
102  * interaction is needed.
103  *
104  * The published value will be available from the `FlutterPluginRegistry`.
105  * Repeated calls overwrite any previous publication.
106  *
107  * @param value The value to be published.
108  */
109 - (void)publish:(nonnull NSObject*)value;
110 
111 /**
112  * Returns a value published by the specified plugin.
113  *
114  * @param pluginKey The unique key identifying the plugin.
115  * @return An object published by the plugin, if any. Will be `NSNull` if
116  * nothing has been published. Will be `nil` if the plugin has not been
117  * registered.
118  */
119 - (nullable NSObject*)valuePublishedByPlugin:(nonnull NSString*)pluginKey;
120 
121 /**
122  * Returns the file name for the given asset.
123  * The returned file name can be used to access the asset in the application's main bundle.
124  *
125  * @param asset The name of the asset. The name can be hierarchical.
126  * @return the file name to be used for lookup in the main bundle.
127  */
128 - (nonnull NSString*)lookupKeyForAsset:(nonnull NSString*)asset;
129 
130 /**
131  * Returns the file name for the given asset which originates from the specified package.
132  * The returned file name can be used to access the asset in the application's main bundle.
133  *
134  *
135  * @param asset The name of the asset. The name can be hierarchical.
136  * @param package The name of the package from which the asset originates.
137  * @return the file name to be used for lookup in the main bundle.
138  */
139 - (nonnull NSString*)lookupKeyForAsset:(nonnull NSString*)asset
140  fromPackage:(nonnull NSString*)package;
141 
142 @end
143 
144 /**
145  * A registry of Flutter macOS plugins.
146  *
147  * Plugins are identified by unique string keys, typically the name of the
148  * plugin's main class.
149  *
150  * Plugins typically need contextual information and the ability to register
151  * callbacks for various application events. To keep the API of the registry
152  * focused, these facilities are not provided directly by the registry, but by
153  * a `FlutterPluginRegistrar`, created by the registry in exchange for the unique
154  * key of the plugin.
155  *
156  * There is no implied connection between the registry and the registrar.
157  * Specifically, callbacks registered by the plugin via the registrar may be
158  * relayed directly to the underlying iOS application objects.
159  */
160 @protocol FlutterPluginRegistry <NSObject>
161 
162 /**
163  * Returns a registrar for registering a plugin.
164  *
165  * @param pluginKey The unique key identifying the plugin.
166  */
167 - (nonnull id<FlutterPluginRegistrar>)registrarForPlugin:(nonnull NSString*)pluginKey;
168 
169 /**
170  * Returns a value published by the specified plugin.
171  *
172  * @param pluginKey The unique key identifying the plugin.
173  * @return An object published by the plugin, if any. Will be `NSNull` if
174  * nothing has been published. Will be `nil` if the plugin has not been
175  * registered.
176  */
177 - (nullable NSObject*)valuePublishedByPlugin:(nonnull NSString*)pluginKey;
178 
179 @end
180 
181 #endif // FLUTTER_SHELL_PLATFORM_DARWIN_MACOS_FRAMEWORK_HEADERS_FLUTTERPLUGINREGISTRARMACOS_H_
#define FLUTTER_DARWIN_EXPORT
Definition: FlutterMacros.h:14
id< FlutterBinaryMessenger > messenger
id< FlutterTextureRegistry > textures