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 recreated after configuration changes, that `Activity` should invoke `#reattachToActivityAfterConfigChange(Activity)` so that all `ActivityAware` plugins can re-establish references to the `Activity`.
  4. 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()`.
  5. 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 Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `attachToActivity(Activity activity, androidx.lifecycle.Lifecycle lifecycle)` Deprecated. Prefer using the `attachToActivity(ExclusiveAppComponent, Lifecycle)` API to avoid situations where multiple activities are driving the FlutterEngine simultaneously. See https://github.com/flutter/flutter/issues/66192.
    `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

          @Deprecated
          void attachToActivity(@NonNull
                                            Activity activity,
                                            @NonNull
                                            androidx.lifecycle.Lifecycle lifecycle)

      Deprecated. Prefer using the `attachToActivity(ExclusiveAppComponent, Lifecycle)` API to avoid situations where multiple activities are driving the FlutterEngine simultaneously. See https://github.com/flutter/flutter/issues/66192.
      Call this method from the `Activity` that is displaying the visual content of the `FlutterEngine` that is associated with this `ActivityControlSurface`.

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

    - #### 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`.

      This method differs from `attachToActivity(Activity, Lifecycle)` in that it calls back the existing `ExclusiveAppComponent` to give it a chance to cleanly detach before a new `ExclusiveAppComponent` is attached.

    - #### 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`.