Package io.flutter.embedding.engine.plugins.activity

## Interface ActivityControlSurface

-     public interface ActivityControlSurface

  Control surface through which an `Activity` attaches to a `FlutterEngine`.

  An `Activity` that contains a `FlutterView` and associated `FlutterEngine` should coordinate itself with the `FlutterEngine`'s `ActivityControlSurface`.

  1. Once an `Activity` is created, and its associated `FlutterEngine` is executing Dart code, the `Activity` should invoke `attachToActivity( ExclusiveAppComponent, Lifecycle)`. At this point the `FlutterEngine` is considered "attached" to the `Activity` and all `ActivityAware` plugins are given access to the `Activity`.
  2. Just before an attached `Activity` is destroyed for configuration change purposes, that `Activity` should invoke `detachFromActivityForConfigChanges()`, giving each `ActivityAware` plugin an opportunity to clean up its references before the `is destroyed`.
  3. When an `Activity` is destroyed for non-configuration-change purposes, or when the `Activity` is no longer interested in displaying a `FlutterEngine`'s content, the `Activity` should invoke `detachFromActivity()`.
  4. When a `Activity` is being attached while an existing `ExclusiveAppComponent` is already attached, the existing `ExclusiveAppComponent` is given a chance to detach first via `ExclusiveAppComponent.detachFromFlutterEngine()` before the new activity attaches.
  The attached `Activity` should also forward all `Activity` calls that this `ActivityControlSurface` supports, e.g., `onRequestPermissionsResult(int, String[], int[])`. These forwarded calls are made available to all `ActivityAware` plugins that are added to the attached `FlutterEngine`.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `attachToActivity​(ExclusiveAppComponent<Activity> exclusiveActivity, androidx.lifecycle.Lifecycle lifecycle)` | Call this method from the `ExclusiveAppComponent` that is displaying the visual content of the `FlutterEngine` that is associated with this `ActivityControlSurface`.
    `void` | `detachFromActivity()` | Call this method from the `Activity` that is attached to this `ActivityControlSurfaces`'s `FlutterEngine` when the `Activity` is about to be destroyed for non-configuration-change reasons.
    `void` | `detachFromActivityForConfigChanges()` | Call this method from the `Activity` that is attached to this `ActivityControlSurfaces`'s `FlutterEngine` when the `Activity` is about to be destroyed due to configuration changes.
    `boolean` | `onActivityResult​(int requestCode, int resultCode, Intent data)` | Call this method from the `Activity` that is attached to this `ActivityControlSurface`'s `FlutterEngine` and the associated method in the `Activity` is invoked.
    `void` | `onNewIntent​(Intent intent)` | Call this method from the `Activity` that is attached to this `ActivityControlSurface`'s `FlutterEngine` and the associated method in the `Activity` is invoked.
    `boolean` | `onRequestPermissionsResult​(int requestCode, String[] permissions, int[] grantResult)` | Call this method from the `Activity` that is attached to this `ActivityControlSurface`'s `FlutterEngine` and the associated method in the `Activity` is invoked.
    `void` | `onRestoreInstanceState​(Bundle bundle)` | Call this method from the `Activity` or `Fragment` that is attached to this `ActivityControlSurface`'s `FlutterEngine` when `Activity.onCreate(Bundle)` or `Fragment#onCreate(Bundle)` is invoked in the `Activity` or `Fragment`.
    `void` | `onSaveInstanceState​(Bundle bundle)` | Call this method from the `Activity` or `Fragment` that is attached to this `ActivityControlSurface`'s `FlutterEngine` when the associated method is invoked in the `Activity` or `Fragment`.
    `void` | `onUserLeaveHint()` | Call this method from the `Activity` that is attached to this `ActivityControlSurface`'s `FlutterEngine` and the associated method in the `Activity` is invoked.

- - ### Method Detail

    - #### attachToActivity

          void attachToActivity​(@NonNull
                                ExclusiveAppComponent<Activity> exclusiveActivity,
                                @NonNull
                                androidx.lifecycle.Lifecycle lifecycle)

      Call this method from the `ExclusiveAppComponent` that is displaying the visual content of the `FlutterEngine` that is associated with this `ActivityControlSurface`.

      Once an `ExclusiveAppComponent` is created, and its associated `FlutterEngine` is executing Dart code, the `ExclusiveAppComponent` should invoke this method. At that point the `FlutterEngine` is considered "attached" to the `ExclusiveAppComponent` and all `ActivityAware` plugins are given access to the `ExclusiveAppComponent`'s `Activity`.

    - #### detachFromActivityForConfigChanges

          void detachFromActivityForConfigChanges()

      Call this method from the `Activity` that is attached to this `ActivityControlSurfaces`'s `FlutterEngine` when the `Activity` is about to be destroyed due to configuration changes.

      This method gives each `ActivityAware` plugin an opportunity to clean up its references before the `is destroyed`.

    - #### detachFromActivity

          void detachFromActivity()

      Call this method from the `Activity` that is attached to this `ActivityControlSurfaces`'s `FlutterEngine` when the `Activity` is about to be destroyed for non-configuration-change reasons.

      This method gives each `ActivityAware` plugin an opportunity to clean up its references before the `is destroyed`.

    - #### onRequestPermissionsResult

          boolean onRequestPermissionsResult​(int requestCode,
                                             @NonNull
                                             String[] permissions,
                                             @NonNull
                                             int[] grantResult)

      Call this method from the `Activity` that is attached to this `ActivityControlSurface`'s `FlutterEngine` and the associated method in the `Activity` is invoked.

      Returns true if one or more plugins utilized this permission result.

    - #### onActivityResult

          boolean onActivityResult​(int requestCode,
                                   int resultCode,
                                   @Nullable
                                   Intent data)

      Call this method from the `Activity` that is attached to this `ActivityControlSurface`'s `FlutterEngine` and the associated method in the `Activity` is invoked.

      Returns true if one or more plugins utilized this `Activity` result.

    - #### onNewIntent

          void onNewIntent​(@NonNull
                           Intent intent)

      Call this method from the `Activity` that is attached to this `ActivityControlSurface`'s `FlutterEngine` and the associated method in the `Activity` is invoked.

    - #### onUserLeaveHint

          void onUserLeaveHint()

      Call this method from the `Activity` that is attached to this `ActivityControlSurface`'s `FlutterEngine` and the associated method in the `Activity` is invoked.

    - #### onSaveInstanceState

          void onSaveInstanceState​(@NonNull
                                   Bundle bundle)

      Call this method from the `Activity` or `Fragment` that is attached to this `ActivityControlSurface`'s `FlutterEngine` when the associated method is invoked in the `Activity` or `Fragment`.

    - #### onRestoreInstanceState

          void onRestoreInstanceState​(@Nullable
                                      Bundle bundle)

      Call this method from the `Activity` or `Fragment` that is attached to this `ActivityControlSurface`'s `FlutterEngine` when `Activity.onCreate(Bundle)` or `Fragment#onCreate(Bundle)` is invoked in the `Activity` or `Fragment`.