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.embedding.engine.plugins.activity; 6 7 import android.app.Activity; 8 import android.arch.lifecycle.Lifecycle; 9 import android.content.Intent; 10 import android.support.annotation.NonNull; 11 import android.support.annotation.Nullable; 12 13 import io.flutter.plugin.platform.PlatformViewsController; 14 15 /** 16 * Control surface through which an {@link Activity} attaches to a {@link FlutterEngine}. 17 * <p> 18 * An {@link Activity} that contains a {@link FlutterView} and associated {@link FlutterEngine} 19 * should coordinate itself with the {@link FlutterEngine}'s {@code ActivityControlSurface}. 20 * <ol> 21 * <li>Once an {@link Activity} is created, and its associated {@link FlutterEngine} is 22 * executing Dart code, the {@link Activity} should invoke 23 * {@link #attachToActivity(Activity, Lifecycle)}. At this point the {@link FlutterEngine} 24 * is considered "attached" to the {@link Activity} and all {@link ActivityAware} plugins 25 * are given access to the {@link Activity}.</li> 26 * <li>Just before an attached {@link Activity} is destroyed for configuration change purposes, 27 * that {@link Activity} should invoke {@link #detachFromActivityForConfigChanges()}, giving 28 * each {@link ActivityAware} plugin an opportunity to clean up its references before the 29 * {@link Activity is destroyed}.</li> 30 * <li>When an {@link Activity} is recreated after configuration changes, that {@link Activity} 31 * should invoke {@link #reattachToActivityAfterConfigChange(Activity)} so that all 32 * {@link ActivityAware} plugins can re-establish references to the {@link Activity}.</li> 33 * <li>When an {@link Activity} is destroyed for non-configuration-change purposes, or when 34 * the {@link Activity} is no longer interested in displaying a {@link FlutterEngine}'s content, 35 * the {@link Activity} should invoke {@link #detachFromActivity()}.</li> 36 * </ol> 37 * The attached {@link Activity} should also forward all {@link Activity} calls that this 38 * {@code ActivityControlSurface} supports, e.g., 39 * {@link #onRequestPermissionsResult(int, String[], int[])}. These forwarded calls are made 40 * available to all {@link ActivityAware} plugins that are added to the attached {@link FlutterEngine}. 41 */ 42 public interface ActivityControlSurface { 43 /** 44 * Call this method from the {@link Activity} that is displaying the visual content of the 45 * {@link FlutterEngine} that is associated with this {@code ActivityControlSurface}. 46 * <p> 47 * Once an {@link Activity} is created, and its associated {@link FlutterEngine} is 48 * executing Dart code, the {@link Activity} should invoke this method. At that point the 49 * {@link FlutterEngine} is considered "attached" to the {@link Activity} and all 50 * {@link ActivityAware} plugins are given access to the {@link Activity}. 51 */ attachToActivity(@onNull Activity activity, @NonNull Lifecycle lifecycle)52 void attachToActivity(@NonNull Activity activity, @NonNull Lifecycle lifecycle); 53 54 /** 55 * Call this method from the {@link Activity} that is attached to this {@code ActivityControlSurfaces}'s 56 * {@link FlutterEngine} when the {@link Activity} is about to be destroyed due to configuration 57 * changes. 58 * <p> 59 * This method gives each {@link ActivityAware} plugin an opportunity to clean up its references 60 * before the {@link Activity is destroyed}. 61 */ detachFromActivityForConfigChanges()62 void detachFromActivityForConfigChanges(); 63 64 /** 65 * Call this method from the {@link Activity} that is attached to this {@code ActivityControlSurfaces}'s 66 * {@link FlutterEngine} when the {@link Activity} is about to be destroyed for non-configuration-change 67 * reasons. 68 * <p> 69 * This method gives each {@link ActivityAware} plugin an opportunity to clean up its references 70 * before the {@link Activity is destroyed}. 71 */ detachFromActivity()72 void detachFromActivity(); 73 74 /** 75 * Call this method from the {@link Activity} that is attached to this {@code ActivityControlSurface}'s 76 * {@link FlutterEngine} and the associated method in the {@link Activity} is invoked. 77 * <p> 78 * Returns true if one or more plugins utilized this permission result. 79 */ onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResult)80 boolean onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResult); 81 82 /** 83 * Call this method from the {@link Activity} that is attached to this {@code ActivityControlSurface}'s 84 * {@link FlutterEngine} and the associated method in the {@link Activity} is invoked. 85 * <p> 86 * Returns true if one or more plugins utilized this {@link Activity} result. 87 */ onActivityResult(int requestCode, int resultCode, @Nullable Intent data)88 boolean onActivityResult(int requestCode, int resultCode, @Nullable Intent data); 89 90 /** 91 * Call this method from the {@link Activity} that is attached to this {@code ActivityControlSurface}'s 92 * {@link FlutterEngine} and the associated method in the {@link Activity} is invoked. 93 */ onNewIntent(@onNull Intent intent)94 void onNewIntent(@NonNull Intent intent); 95 96 /** 97 * Call this method from the {@link Activity} that is attached to this {@code ActivityControlSurface}'s 98 * {@link FlutterEngine} and the associated method in the {@link Activity} is invoked. 99 */ onUserLeaveHint()100 void onUserLeaveHint(); 101 } 102