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

  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 Details

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