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 package io.flutter.plugin.common; 6 7 import android.app.Activity; 8 import android.content.Context; 9 import android.content.Intent; 10 import io.flutter.plugin.platform.PlatformViewRegistry; 11 import io.flutter.view.FlutterNativeView; 12 import io.flutter.view.FlutterView; 13 import io.flutter.view.TextureRegistry; 14 15 /** 16 * Registry used by plugins to set up interaction with Android APIs. 17 * 18 * <p>Flutter applications by default include an auto-generated and auto-updated 19 * plugin registrant class (GeneratedPluginRegistrant) that makes use of a 20 * {@link PluginRegistry} to register contributions from each plugin mentioned 21 * in the application's pubspec file. The generated registrant class is, again 22 * by default, called from the application's main {@link Activity}, which 23 * defaults to an instance of {@link io.flutter.app.FlutterActivity}, itself a 24 * {@link PluginRegistry}.</p> 25 */ 26 public interface PluginRegistry { 27 /** 28 * Returns a {@link Registrar} for receiving the registrations pertaining 29 * to the specified plugin. 30 * 31 * @param pluginKey a unique String identifying the plugin; typically the 32 * fully qualified name of the plugin's main class. 33 */ registrarFor(String pluginKey)34 Registrar registrarFor(String pluginKey); 35 36 /** 37 * Returns whether the specified plugin is known to this registry. 38 * 39 * @param pluginKey a unique String identifying the plugin; typically the 40 * fully qualified name of the plugin's main class. 41 * @return true if this registry has handed out a registrar for the 42 * specified plugin. 43 */ hasPlugin(String pluginKey)44 boolean hasPlugin(String pluginKey); 45 46 /** 47 * Returns the value published by the specified plugin, if any. 48 * 49 * <p>Plugins may publish a single value, such as an instance of the 50 * plugin's main class, for situations where external control or 51 * interaction is needed. Clients are expected to know the value's 52 * type.</p> 53 * 54 * @param pluginKey a unique String identifying the plugin; typically the 55 * fully qualified name of the plugin's main class. 56 * @return the published value, possibly null. 57 */ valuePublishedByPlugin(String pluginKey)58 <T> T valuePublishedByPlugin(String pluginKey); 59 60 /** 61 * Receiver of registrations from a single plugin. 62 */ 63 interface Registrar { 64 /** 65 * Returns the {@link Activity} that forms the plugin's operating context. 66 * 67 * <p>Plugin authors should not assume the type returned by this method 68 * is any specific subclass of {@code Activity} (such as 69 * {@link io.flutter.app.FlutterActivity} or 70 * {@link io.flutter.app.FlutterFragmentActivity}), as applications 71 * are free to use any activity subclass.</p> 72 * 73 * <p>When there is no foreground activity in the application, this 74 * will return null. If a {@link Context} is needed, use context() to 75 * get the application's context.</p> 76 */ activity()77 Activity activity(); 78 79 /** 80 * Returns the {@link android.app.Application}'s {@link Context}. 81 */ context()82 Context context(); 83 84 /** 85 * Returns the active {@link Context}. 86 * 87 * @return the current {@link #activity() Activity}, if not null, otherwise the {@link #context() Application}. 88 */ activeContext()89 Context activeContext(); 90 91 /** 92 * Returns a {@link BinaryMessenger} which the plugin can use for 93 * creating channels for communicating with the Dart side. 94 */ messenger()95 BinaryMessenger messenger(); 96 97 /** 98 * Returns a {@link TextureRegistry} which the plugin can use for 99 * managing backend textures. 100 */ textures()101 TextureRegistry textures(); 102 103 /** 104 * Returns the application's {@link PlatformViewRegistry}. 105 * 106 * Plugins can use the platform registry to register their view factories. 107 */ platformViewRegistry()108 PlatformViewRegistry platformViewRegistry(); 109 110 /** 111 * Returns the {@link FlutterView} that's instantiated by this plugin's 112 * {@link #activity() activity}. 113 */ view()114 FlutterView view(); 115 116 117 /** 118 * Returns the file name for the given asset. 119 * The returned file name can be used to access the asset in the APK 120 * through the {@link android.content.res.AssetManager} API. 121 * 122 * @param asset the name of the asset. The name can be hierarchical 123 * @return the filename to be used with {@link android.content.res.AssetManager} 124 */ lookupKeyForAsset(String asset)125 String lookupKeyForAsset(String asset); 126 127 /** 128 * Returns the file name for the given asset which originates from the 129 * specified packageName. The returned file name can be used to access 130 * the asset in the APK through the {@link android.content.res.AssetManager} API. 131 * 132 * @param asset the name of the asset. The name can be hierarchical 133 * @param packageName the name of the package from which the asset originates 134 * @return the file name to be used with {@link android.content.res.AssetManager} 135 */ lookupKeyForAsset(String asset, String packageName)136 String lookupKeyForAsset(String asset, String packageName); 137 138 139 /** 140 * Publishes a value associated with the plugin being registered. 141 * 142 * <p>The published value is available to interested clients via 143 * {@link PluginRegistry#valuePublishedByPlugin(String)}.</p> 144 * 145 * <p>Publication should be done only when client code needs to interact 146 * with the plugin in a way that cannot be accomplished by the plugin 147 * registering callbacks with client APIs.</p> 148 * 149 * <p>Overwrites any previously published value.</p> 150 * 151 * @param value the value, possibly null. 152 * @return this {@link Registrar}. 153 */ publish(Object value)154 Registrar publish(Object value); 155 156 /** 157 * Adds a callback allowing the plugin to take part in handling incoming 158 * calls to {@code Activity#onRequestPermissionsResult(int, String[], int[])} 159 * or {@code android.support.v4.app.ActivityCompat.OnRequestPermissionsResultCallback#onRequestPermissionsResult(int, String[], int[])}. 160 * 161 * @param listener a {@link RequestPermissionsResultListener} callback. 162 * @return this {@link Registrar}. 163 */ addRequestPermissionsResultListener(RequestPermissionsResultListener listener)164 Registrar addRequestPermissionsResultListener(RequestPermissionsResultListener listener); 165 166 /** 167 * Adds a callback allowing the plugin to take part in handling incoming 168 * calls to {@link Activity#onActivityResult(int, int, Intent)}. 169 * 170 * @param listener an {@link ActivityResultListener} callback. 171 * @return this {@link Registrar}. 172 */ addActivityResultListener(ActivityResultListener listener)173 Registrar addActivityResultListener(ActivityResultListener listener); 174 175 /** 176 * Adds a callback allowing the plugin to take part in handling incoming 177 * calls to {@link Activity#onNewIntent(Intent)}. 178 * 179 * @param listener a {@link NewIntentListener} callback. 180 * @return this {@link Registrar}. 181 */ addNewIntentListener(NewIntentListener listener)182 Registrar addNewIntentListener(NewIntentListener listener); 183 184 /** 185 * Adds a callback allowing the plugin to take part in handling incoming 186 * calls to {@link Activity#onUserLeaveHint()}. 187 * 188 * @param listener a {@link UserLeaveHintListener} callback. 189 * @return this {@link Registrar}. 190 */ addUserLeaveHintListener(UserLeaveHintListener listener)191 Registrar addUserLeaveHintListener(UserLeaveHintListener listener); 192 193 /** 194 * Adds a callback allowing the plugin to take part in handling incoming 195 * calls to {@link Activity#onDestroy()}. 196 * 197 * @param listener a {@link ViewDestroyListener} callback. 198 * @return this {@link Registrar}. 199 */ addViewDestroyListener(ViewDestroyListener listener)200 Registrar addViewDestroyListener(ViewDestroyListener listener); 201 } 202 203 /** 204 * Delegate interface for handling result of permissions requests on 205 * behalf of the main {@link Activity}. 206 */ 207 interface RequestPermissionsResultListener { 208 /** 209 * @return true if the result has been handled. 210 */ onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults)211 boolean onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults); 212 } 213 214 /** 215 * Delegate interface for handling activity results on behalf of the main 216 * {@link Activity}. 217 */ 218 interface ActivityResultListener { 219 /** 220 * @return true if the result has been handled. 221 */ onActivityResult(int requestCode, int resultCode, Intent data)222 boolean onActivityResult(int requestCode, int resultCode, Intent data); 223 } 224 225 /** 226 * Delegate interface for handling new intents on behalf of the main 227 * {@link Activity}. 228 */ 229 interface NewIntentListener { 230 /** 231 * @return true if the new intent has been handled. 232 */ onNewIntent(Intent intent)233 boolean onNewIntent(Intent intent); 234 } 235 236 /** 237 * Delegate interface for handling user leave hints on behalf of the main 238 * {@link Activity}. 239 */ 240 interface UserLeaveHintListener { onUserLeaveHint()241 void onUserLeaveHint(); 242 } 243 244 /** 245 * Delegate interface for handling an {@link Activity}'s onDestroy 246 * method being called. A plugin that implements this interface can 247 * adopt the FlutterNativeView by retaining a reference and returning true. 248 */ 249 interface ViewDestroyListener { onViewDestroy(FlutterNativeView view)250 boolean onViewDestroy(FlutterNativeView view); 251 } 252 253 /** 254 * Callback interface for registering plugins with a plugin registry. 255 * 256 * <p>For example, an Application may use this callback interface to 257 * provide a background service with a callback for calling its 258 * GeneratedPluginRegistrant.registerWith method.</p> 259 */ 260 interface PluginRegistrantCallback { registerWith(PluginRegistry registry)261 void registerWith(PluginRegistry registry); 262 } 263 } 264