DEV/flutter_flutter
1
0
Fork 0
mirror of https://github.com/flutter/flutter.git synced 2026-02-20 02:29:02 +08:00
Code Issues Packages Projects Releases Wiki Activity

Point old plugin registry accessors to new embedding plugin accessors. (#44225) (flutter/engine#13739)

Browse Source
This commit is contained in:
Matt Carroll 2019-11-09 01:55:59 +00:00 committed by GitHub
parent 2572d5b375
commit 98d25e5bf3
3 changed files with 124 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
engine/src/flutter/shell/platform/android/io/flutter/embedding/engine/plugins/FlutterPlugin.java
View File

@ -50,7 +50,17 @@ import io.flutter.view.TextureRegistry;
* be retrieved through a {@link Context}. Developers can access the application context via
* {@link FlutterPluginBinding#getApplicationContext()}.
* <p>
* TODO(mattcarroll): explain ActivityAware when it's added to the new plugin API surface.
* Some plugins may require access to the {@code Activity} that is displaying a Flutter experience,
* or may need to react to {@code Activity} lifecycle events, e.g., {@code onCreate()},
* {@code onStart()}, {@code onResume()}, {@code onPause()}, {@code onStop()}, {@code onDestroy()}.
* Any such plugin should implement
* {@link io.flutter.embedding.engine.plugins.activity.ActivityAware} in addition to implementing
* {@code FlutterPlugin}. {@code ActivityAware} provides callback hooks that expose access to an
* associated {@code Activity} and its {@code Lifecycle}. All plugins must respect the possibility
* that a Flutter experience may never be associated with an {@code Activity}, e.g., when Flutter
* is used for background behavior. Additionally, all plugins must respect that a {@code Activity}s
* may come and go over time, thus requiring plugins to cleanup resources and recreate those
* resources as the {@code Activity} comes and goes.
*/
public interface FlutterPlugin {

4
engine/src/flutter/shell/platform/android/io/flutter/embedding/engine/plugins/activity/ActivityPluginBinding.java
View File

@ -14,6 +14,10 @@ import io.flutter.plugin.common.PluginRegistry;
/**
* Binding that gives {@link ActivityAware} plugins access to an associated {@link Activity} and
* the {@link Activity}'s lifecycle methods.
* <p>
* To obtain an instance of an {@code ActivityPluginBinding} in a Flutter plugin, implement the
* {@link ActivityAware} interface. A binding is provided in {@link ActivityAware#onAttachedToActivity(ActivityPluginBinding)}
* and {@link ActivityAware#onReattachedToActivityForConfigChanges(ActivityPluginBinding)}.
*/
public interface ActivityPluginBinding {

113
engine/src/flutter/shell/platform/android/io/flutter/plugin/common/PluginRegistry.java
View File

@ -7,6 +7,10 @@ package io.flutter.plugin.common;
import android.app.Activity;
import android.content.Context;
import android.content.Intent;
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;
@ -59,6 +63,9 @@ public interface PluginRegistry {
/**
* Receiver of registrations from a single plugin.
*
* <p>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
*/
interface Registrar {
/**
@ -73,30 +80,64 @@ public interface PluginRegistry {
* <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>
*
* <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
*/
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
*/
Context context();
/**
* Returns the active {@link Context}.
*
* @return the current {@link #activity() Activity}, if not null, otherwise the {@link #context() Application}.
*/
* 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}.
*/
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
*/
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
*/
TextureRegistry textures();
@ -104,12 +145,27 @@ public interface PluginRegistry {
* Returns the application's {@link PlatformViewRegistry}.
*
* 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
*/
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
*/
FlutterView view();
@ -119,6 +175,8 @@ public interface PluginRegistry {
* The returned file name can be used to access the asset in the APK
* through the {@link android.content.res.AssetManager} API.
*
* 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}
*/
@ -129,6 +187,8 @@ public interface PluginRegistry {
* specified packageName. The returned file name can be used to access
* the asset in the APK through the {@link android.content.res.AssetManager} API.
*
* 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}
@ -148,6 +208,12 @@ public interface PluginRegistry {
*
* <p>Overwrites any previously published value.</p>
*
* <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}.
*/
@ -158,6 +224,12 @@ public interface PluginRegistry {
* calls to {@code Activity#onRequestPermissionsResult(int, String[], int[])}
* or {@code android.support.v4.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(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}.
*/
@ -167,6 +239,12 @@ public interface PluginRegistry {
* 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(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}.
*/
@ -176,6 +254,12 @@ public interface PluginRegistry {
* 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(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}.
*/
@ -185,6 +269,12 @@ public interface PluginRegistry {
* 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(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}.
*/
@ -194,9 +284,24 @@ public interface PluginRegistry {
* 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)
Registrar addViewDestroyListener(ViewDestroyListener listener);
}