| // Copyright 2013 The Flutter Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| package io.flutter.plugin.common; |
| |
| import android.app.Activity; |
| import android.content.Context; |
| import android.content.Intent; |
| import androidx.annotation.NonNull; |
| import androidx.annotation.Nullable; |
| import io.flutter.embedding.engine.plugins.FlutterPlugin; |
| import io.flutter.embedding.engine.plugins.activity.ActivityAware; |
| import io.flutter.embedding.engine.plugins.activity.ActivityPluginBinding; |
| import io.flutter.plugin.platform.PlatformViewRegistry; |
| import io.flutter.view.FlutterNativeView; |
| import io.flutter.view.FlutterView; |
| import io.flutter.view.TextureRegistry; |
| |
| /** |
| * Container class for Android API listeners used by {@link ActivityPluginBinding}. |
| * |
| * <p>This class also contains deprecated v1 embedding APIs used for plugin registration. |
| * |
| * <p>In v1 Android applications, an auto-generated and auto-updated plugin registrant class |
| * (GeneratedPluginRegistrant) makes use of a {@link PluginRegistry} to register contributions from |
| * each plugin mentioned in the application's pubspec file. The generated registrant class is, again |
| * by default, called from the application's main {@link android.app.Activity}, which defaults to an |
| * instance of {@link io.flutter.app.FlutterActivity}, itself a {@link PluginRegistry}. |
| */ |
| public interface PluginRegistry { |
| /** |
| * Returns a {@link Registrar} for receiving the registrations pertaining to the specified plugin. |
| * |
| * @param pluginKey a unique String identifying the plugin; typically the fully qualified name of |
| * the plugin's main class. |
| * @return A {@link Registrar} for receiving the registrations pertianing to the specified plugin. |
| * @deprecated See https://flutter.dev/go/android-project-migration for migration details. |
| */ |
| @Deprecated |
| @NonNull |
| Registrar registrarFor(@NonNull String pluginKey); |
| |
| /** |
| * Returns whether the specified plugin is known to this registry. |
| * |
| * @param pluginKey a unique String identifying the plugin; typically the fully qualified name of |
| * the plugin's main class. |
| * @return true if this registry has handed out a registrar for the specified plugin. |
| * @deprecated See https://flutter.dev/go/android-project-migration for migration details. |
| */ |
| @Deprecated |
| boolean hasPlugin(@NonNull String pluginKey); |
| |
| /** |
| * Returns the value published by the specified plugin, if any. |
| * |
| * <p>Plugins may publish a single value, such as an instance of the plugin's main class, for |
| * situations where external control or interaction is needed. Clients are expected to know the |
| * value's type. |
| * |
| * @param <T> The type of the value. |
| * @param pluginKey a unique String identifying the plugin; typically the fully qualified name of |
| * the plugin's main class. |
| * @return the published value, possibly null. |
| * @deprecated See https://flutter.dev/go/android-project-migration for migration details. |
| */ |
| @Deprecated |
| @Nullable |
| <T> T valuePublishedByPlugin(@NonNull String pluginKey); |
| |
| /** |
| * Receiver of registrations from a single plugin. |
| * |
| * @deprecated This registrar is for Flutter's v1 embedding. For instructions on migrating a |
| * plugin from Flutter's v1 Android embedding to v2, visit |
| * http://flutter.dev/go/android-plugin-migration |
| */ |
| @Deprecated |
| interface Registrar { |
| /** |
| * Returns the {@link android.app.Activity} that forms the plugin's operating context. |
| * |
| * <p>Plugin authors should not assume the type returned by this method is any specific subclass |
| * of {@code Activity} (such as {@link io.flutter.app.FlutterActivity} or {@link |
| * io.flutter.app.FlutterFragmentActivity}), as applications are free to use any activity |
| * subclass. |
| * |
| * <p>When there is no foreground activity in the application, this will return null. If a |
| * {@link Context} is needed, use context() to get the application's context. |
| * |
| * <p>This registrar is for Flutter's v1 embedding. To access an {@code Activity} from a plugin |
| * using the v2 embedding, see {@link ActivityPluginBinding#getActivity()}. To obtain an |
| * instance of an {@link ActivityPluginBinding} in a Flutter plugin, implement the {@link |
| * ActivityAware} interface. A binding is provided in {@link |
| * ActivityAware#onAttachedToActivity(ActivityPluginBinding)} and {@link |
| * ActivityAware#onReattachedToActivityForConfigChanges(ActivityPluginBinding)}. |
| * |
| * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit |
| * http://flutter.dev/go/android-plugin-migration |
| */ |
| @Nullable |
| Activity activity(); |
| |
| /** |
| * Returns the {@link android.app.Application}'s {@link Context}. |
| * |
| * <p>This registrar is for Flutter's v1 embedding. To access a {@code Context} from a plugin |
| * using the v2 embedding, see {@link |
| * FlutterPlugin.FlutterPluginBinding#getApplicationContext()} |
| * |
| * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit |
| * http://flutter.dev/go/android-plugin-migration |
| */ |
| @NonNull |
| Context context(); |
| |
| /** |
| * Returns the active {@link Context}. |
| * |
| * <p>This registrar is for Flutter's v1 embedding. In the v2 embedding, there is no concept of |
| * an "active context". Either use the application {@code Context} or an attached {@code |
| * Activity}. See {@link #context()} and {@link #activity()} for more details. |
| * |
| * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit |
| * http://flutter.dev/go/android-plugin-migration |
| * |
| * @return the current {@link #activity() Activity}, if not null, otherwise the {@link |
| * #context() Application}. |
| */ |
| @NonNull |
| Context activeContext(); |
| |
| /** |
| * Returns a {@link BinaryMessenger} which the plugin can use for creating channels for |
| * communicating with the Dart side. |
| * |
| * <p>This registrar is for Flutter's v1 embedding. To access a {@code BinaryMessenger} from a |
| * plugin using the v2 embedding, see {@link |
| * FlutterPlugin.FlutterPluginBinding#getBinaryMessenger()} |
| * |
| * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit |
| * http://flutter.dev/go/android-plugin-migration |
| */ |
| @NonNull |
| BinaryMessenger messenger(); |
| |
| /** |
| * Returns a {@link TextureRegistry} which the plugin can use for managing backend textures. |
| * |
| * <p>This registrar is for Flutter's v1 embedding. To access a {@code TextureRegistry} from a |
| * plugin using the v2 embedding, see {@link |
| * FlutterPlugin.FlutterPluginBinding#getTextureRegistry()} |
| * |
| * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit |
| * http://flutter.dev/go/android-plugin-migration |
| */ |
| @NonNull |
| TextureRegistry textures(); |
| |
| /** |
| * Returns the application's {@link PlatformViewRegistry}. |
| * |
| * <p>Plugins can use the platform registry to register their view factories. |
| * |
| * <p>This registrar is for Flutter's v1 embedding. To access a {@code PlatformViewRegistry} |
| * from a plugin using the v2 embedding, see {@link |
| * FlutterPlugin.FlutterPluginBinding#getPlatformViewRegistry()} |
| * |
| * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit |
| * http://flutter.dev/go/android-plugin-migration |
| */ |
| @NonNull |
| PlatformViewRegistry platformViewRegistry(); |
| |
| /** |
| * Returns the {@link FlutterView} that's instantiated by this plugin's {@link #activity() |
| * activity}. |
| * |
| * <p>This registrar is for Flutter's v1 embedding. The {@link FlutterView} referenced by this |
| * method does not exist in the v2 embedding. Additionally, no {@code View} is exposed to any |
| * plugins in the v2 embedding. Platform views can access their containing {@code View} using |
| * the platform views APIs. If you have a use-case that absolutely requires a plugin to access |
| * an Android {@code View}, please file a ticket on GitHub. |
| * |
| * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit |
| * http://flutter.dev/go/android-plugin-migration |
| */ |
| @NonNull |
| FlutterView view(); |
| |
| /** |
| * Returns the file name for the given asset. The returned file name can be used to access the |
| * asset in the APK through the {@link android.content.res.AssetManager} API. |
| * |
| * <p>TODO(mattcarroll): point this method towards new lookup method. |
| * |
| * @param asset the name of the asset. The name can be hierarchical |
| * @return the filename to be used with {@link android.content.res.AssetManager} |
| */ |
| @NonNull |
| String lookupKeyForAsset(@NonNull String asset); |
| |
| /** |
| * Returns the file name for the given asset which originates from the specified packageName. |
| * The returned file name can be used to access the asset in the APK through the {@link |
| * android.content.res.AssetManager} API. |
| * |
| * <p>TODO(mattcarroll): point this method towards new lookup method. |
| * |
| * @param asset the name of the asset. The name can be hierarchical |
| * @param packageName the name of the package from which the asset originates |
| * @return the file name to be used with {@link android.content.res.AssetManager} |
| */ |
| @NonNull |
| String lookupKeyForAsset(@NonNull String asset, @NonNull String packageName); |
| |
| /** |
| * Publishes a value associated with the plugin being registered. |
| * |
| * <p>The published value is available to interested clients via {@link |
| * PluginRegistry#valuePublishedByPlugin(String)}. |
| * |
| * <p>Publication should be done only when client code needs to interact with the plugin in a |
| * way that cannot be accomplished by the plugin registering callbacks with client APIs. |
| * |
| * <p>Overwrites any previously published value. |
| * |
| * <p>This registrar is for Flutter's v1 embedding. The concept of publishing values from |
| * plugins is not supported in the v2 embedding. |
| * |
| * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit |
| * http://flutter.dev/go/android-plugin-migration |
| * |
| * @param value the value, possibly null. |
| * @return this {@link Registrar}. |
| */ |
| @NonNull |
| Registrar publish(@Nullable Object value); |
| |
| /** |
| * Adds a callback allowing the plugin to take part in handling incoming calls to {@code |
| * Activity#onRequestPermissionsResult(int, String[], int[])} or {@code |
| * androidx.core.app.ActivityCompat.OnRequestPermissionsResultCallback#onRequestPermissionsResult(int, |
| * String[], int[])}. |
| * |
| * <p>This registrar is for Flutter's v1 embedding. To listen for permission results in the v2 |
| * embedding, use {@link |
| * ActivityPluginBinding#addRequestPermissionsResultListener(PluginRegistry.RequestPermissionsResultListener)}. |
| * |
| * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit |
| * http://flutter.dev/go/android-plugin-migration |
| * |
| * @param listener a {@link RequestPermissionsResultListener} callback. |
| * @return this {@link Registrar}. |
| */ |
| @NonNull |
| Registrar addRequestPermissionsResultListener( |
| @NonNull RequestPermissionsResultListener listener); |
| |
| /** |
| * Adds a callback allowing the plugin to take part in handling incoming calls to {@link |
| * Activity#onActivityResult(int, int, Intent)}. |
| * |
| * <p>This registrar is for Flutter's v1 embedding. To listen for {@code Activity} results in |
| * the v2 embedding, use {@link |
| * ActivityPluginBinding#addActivityResultListener(PluginRegistry.ActivityResultListener)}. |
| * |
| * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit |
| * http://flutter.dev/go/android-plugin-migration |
| * |
| * @param listener an {@link ActivityResultListener} callback. |
| * @return this {@link Registrar}. |
| */ |
| @NonNull |
| Registrar addActivityResultListener(@NonNull ActivityResultListener listener); |
| |
| /** |
| * Adds a callback allowing the plugin to take part in handling incoming calls to {@link |
| * Activity#onNewIntent(Intent)}. |
| * |
| * <p>This registrar is for Flutter's v1 embedding. To listen for new {@code Intent}s in the v2 |
| * embedding, use {@link |
| * ActivityPluginBinding#addOnNewIntentListener(PluginRegistry.NewIntentListener)}. |
| * |
| * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit |
| * http://flutter.dev/go/android-plugin-migration |
| * |
| * @param listener a {@link NewIntentListener} callback. |
| * @return this {@link Registrar}. |
| */ |
| @NonNull |
| Registrar addNewIntentListener(@NonNull NewIntentListener listener); |
| |
| /** |
| * Adds a callback allowing the plugin to take part in handling incoming calls to {@link |
| * Activity#onUserLeaveHint()}. |
| * |
| * <p>This registrar is for Flutter's v1 embedding. To listen for leave hints in the v2 |
| * embedding, use {@link |
| * ActivityPluginBinding#addOnUserLeaveHintListener(PluginRegistry.UserLeaveHintListener)}. |
| * |
| * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit |
| * http://flutter.dev/go/android-plugin-migration |
| * |
| * @param listener a {@link UserLeaveHintListener} callback. |
| * @return this {@link Registrar}. |
| */ |
| @NonNull |
| Registrar addUserLeaveHintListener(@NonNull UserLeaveHintListener listener); |
| |
| /** |
| * Adds a callback allowing the plugin to take part in handling incoming calls to {@link |
| * Activity#onDestroy()}. |
| * |
| * <p>This registrar is for Flutter's v1 embedding. The concept of {@code View} destruction does |
| * not exist in the v2 embedding. However, plugins in the v2 embedding can respond to {@link |
| * ActivityAware#onDetachedFromActivityForConfigChanges()} and {@link |
| * ActivityAware#onDetachedFromActivity()}, which indicate the loss of a visual context for the |
| * running Flutter experience. Developers should implement {@link ActivityAware} for their |
| * {@link FlutterPlugin} if such callbacks are needed. Also, plugins can respond to {@link |
| * FlutterPlugin#onDetachedFromEngine(FlutterPlugin.FlutterPluginBinding)}, which indicates that |
| * the given plugin has been completely disconnected from the associated Flutter experience and |
| * should clean up any resources. |
| * |
| * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2, visit |
| * http://flutter.dev/go/android-plugin-migration |
| * |
| * @param listener a {@link ViewDestroyListener} callback. |
| * @return this {@link Registrar}. |
| */ |
| // TODO(amirh): Add a line in the javadoc above that points to a Platform Views website guide |
| // when one is available (but not a website API doc) |
| @NonNull |
| Registrar addViewDestroyListener(@NonNull ViewDestroyListener listener); |
| } |
| |
| /** |
| * Delegate interface for handling result of permissions requests on behalf of the main {@link |
| * Activity}. |
| */ |
| interface RequestPermissionsResultListener { |
| /** |
| * @param requestCode The request code passed in {@code |
| * ActivityCompat.requestPermissions(android.app.Activity, String[], int)}. |
| * @param permissions The requested permissions. |
| * @param grantResults The grant results for the corresponding permissions which is either |
| * {@code PackageManager.PERMISSION_GRANTED} or {@code PackageManager.PERMISSION_DENIED}. |
| * @return true if the result has been handled. |
| */ |
| boolean onRequestPermissionsResult( |
| int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults); |
| } |
| |
| /** |
| * Delegate interface for handling activity results on behalf of the main {@link |
| * android.app.Activity}. |
| */ |
| interface ActivityResultListener { |
| /** |
| * @param requestCode The integer request code originally supplied to {@code |
| * startActivityForResult()}, allowing you to identify who this result came from. |
| * @param resultCode The integer result code returned by the child activity through its {@code |
| * setResult()}. |
| * @param data An Intent, which can return result data to the caller (various data can be |
| * attached to Intent "extras"). |
| * @return true if the result has been handled. |
| */ |
| boolean onActivityResult(int requestCode, int resultCode, @Nullable Intent data); |
| } |
| |
| /** |
| * Delegate interface for handling new intents on behalf of the main {@link android.app.Activity}. |
| */ |
| interface NewIntentListener { |
| /** |
| * @param intent The new intent that was started for the activity. |
| * @return true if the new intent has been handled. |
| */ |
| boolean onNewIntent(@NonNull Intent intent); |
| } |
| |
| /** |
| * Delegate interface for handling user leave hints on behalf of the main {@link |
| * android.app.Activity}. |
| */ |
| interface UserLeaveHintListener { |
| void onUserLeaveHint(); |
| } |
| |
| /** |
| * Delegate interface for handling an {@link android.app.Activity}'s onDestroy method being |
| * called. A plugin that implements this interface can adopt the {@link FlutterNativeView} by |
| * retaining a reference and returning true. |
| * |
| * @deprecated See https://flutter.dev/go/android-project-migration for migration details. |
| */ |
| @Deprecated |
| interface ViewDestroyListener { |
| boolean onViewDestroy(@NonNull FlutterNativeView view); |
| } |
| |
| /** |
| * Callback interface for registering plugins with a plugin registry. |
| * |
| * <p>For example, an Application may use this callback interface to provide a background service |
| * with a callback for calling its GeneratedPluginRegistrant.registerWith method. |
| * |
| * @deprecated See https://flutter.dev/go/android-project-migration for migration details. |
| */ |
| @Deprecated |
| interface PluginRegistrantCallback { |
| void registerWith(@NonNull PluginRegistry registry); |
| } |
| } |