Determine lifecycle by looking at window focus also (#41094)

## Description

This incorporates additional signal from `Activity.onWindowFocusChanged` to help decide if the application is `resumed` or `inactive`.

When the user pulls down the notification shade or opens the app switcher in iOS, then iOS sends a notification to the application that it no longer has input focus (is no longer "active" in Apple terminology). 

However, Android (at least on a Pixel) doesn't send `onPause` and `onResume` events for these things, as one might expect. Instead, this PR changes things so that we listen to `Activity.onWindowFocusChanged` and see if any of the windows still have focus.

If it doesn't have focus, then the lifecycle switches to `inactive` (even if `onPause` hasn't been called), and if it does have focus (and `onResume` hasn't been called) then we should go to `resumed`.

State changes are determined and deduped in the `LifecycleChannel` class.

Here's the old state table:

| Android State | Flutter state |
| ------------- | ------------- |
| Resumed  | resumed |
| Paused  | inactive |
| Stopped | paused |
| Detached | detached |

Here's the new state table:

| Android State | Window focused | Flutter state |
| ------------- | ------------- | ------------- |
| Resumed  | true  | resumed |
| Resumed  | false  | _inactive_ * |
| Paused  | true  | inactive |
| Paused  | false  | inactive |
| Stopped  | true  | paused |
| Stopped | false  | paused |
| Detached | true  | detached |
| Detached | false  | detached |

* = This is the relevant change in this PR.

("Window focused" means one or more windows managed by Flutter are focused)

The `inactive` state is for when the application is running and visible, but doesn't have the input focus.  An example where this currently happens are when a phone call is in progress on top of the app, or on some OEMs when going into the app switcher (I've tested on Realme and it does that, at least).  With the PR, it will also go into `inactive` when the app has lost input focus, but is still in the Android `onResume` state. This means that on phones that don't pause the app when they go into the app switcher or the notification window shade (Pixel, others), the app will go into `inactive` when it didn't before. If developers weren't doing anything special in the `inactive` state before, then this PR will have no change for them. If they were, they will go into that state more often (but more consistently across OEMs).

## Related Issues

  - Fixes  flutter/flutter#124591

## Tests

  - Added unit tests for handling `onWindowFocusChanged`.

Author: gspencergoog

lib/ui/platform_dispatcher.dart

@@ -1642,31 +1642,61 @@ class FrameTiming {
 /// States that an application can be in.
 ///
 /// The values below describe notifications from the operating system.
-/// Applications should not expect to always receive all possible
-/// notifications. For example, if the users pulls out the battery from the
-/// device, no notification will be sent before the application is suddenly
-/// terminated, along with the rest of the operating system.
+/// Applications should not expect to always receive all possible notifications.
+/// For example, if the users pulls out the battery from the device, no
+/// notification will be sent before the application is suddenly terminated,
+/// along with the rest of the operating system.
+///
+/// For historical and name collision reasons, Flutter's application state names
+/// do not correspond one to one with the state names on all platforms. On
+/// Android, for instance, when the OS calls
+/// [`Activity.onPause`](https://developer.android.com/reference/android/app/Activity#onPause()),
+/// Flutter will enter the [inactive] state, but when Android calls
+/// [`Activity.onStop`](https://developer.android.com/reference/android/app/Activity#onStop()),
+/// Flutter enters the [paused] state. See the individual state's documentation
+/// for descriptions of what they mean on each platform.
 ///
 /// See also:
 ///
-///  * [WidgetsBindingObserver], for a mechanism to observe the lifecycle state
-///    from the widgets layer.
+/// * [WidgetsBindingObserver], for a mechanism to observe the lifecycle state
+///   from the widgets layer.
+/// * iOS's [IOKit activity lifecycle](https://developer.apple.com/documentation/uikit/app_and_environment/managing_your_app_s_life_cycle?language=objc) documentation.
+/// * Android's [activity lifecycle](https://developer.android.com/guide/components/activities/activity-lifecycle) documentation.
+/// * macOS's [AppKit activity lifecycle](https://developer.apple.com/documentation/appkit/nsapplicationdelegate?language=objc) documentation.
 enum AppLifecycleState {
-  /// The application is visible and responding to user input.
+  /// The application is visible and responsive to user input.
+  ///
+  /// On Android, this state corresponds to the Flutter host view having focus
+  /// ([`Activity.onWindowFocusChanged`](https://developer.android.com/reference/android/app/Activity#onWindowFocusChanged(boolean))
+  /// was called with true) while in Android's "resumed" state. It is possible
+  /// for the Flutter app to be in the [inactive] state while still being in
+  /// Android's
+  /// ["onResume"](https://developer.android.com/guide/components/activities/activity-lifecycle)
+  /// state if the app has lost focus
+  /// ([`Activity.onWindowFocusChanged`](https://developer.android.com/reference/android/app/Activity#onWindowFocusChanged(boolean))
+  /// was called with false), but hasn't had
+  /// [`Activity.onPause`](https://developer.android.com/reference/android/app/Activity#onPause())
+  /// called on it.
   resumed,
 
   /// The application is in an inactive state and is not receiving user input.
   ///
   /// On iOS, this state corresponds to an app or the Flutter host view running
-  /// in the foreground inactive state. Apps transition to this state when in
-  /// a phone call, responding to a TouchID request, when entering the app
+  /// in the foreground inactive state. Apps transition to this state when in a
+  /// phone call, responding to a TouchID request, when entering the app
   /// switcher or the control center, or when the UIViewController hosting the
   /// Flutter app is transitioning.
   ///
-  /// On Android, this corresponds to an app or the Flutter host view running
-  /// in the foreground inactive state.  Apps transition to this state when
-  /// another activity is focused, such as a split-screen app, a phone call,
-  /// a picture-in-picture app, a system dialog, or another view.
+  /// On Android, this corresponds to an app or the Flutter host view running in
+  /// Android's paused state (i.e.
+  /// [`Activity.onPause`](https://developer.android.com/reference/android/app/Activity#onPause())
+  /// has been called), or in Android's "resumed" state (i.e.
+  /// [`Activity.onResume`](https://developer.android.com/reference/android/app/Activity#onResume())
+  /// has been called) but it has lost window focus. Examples of when apps
+  /// transition to this state include when the app is partially obscured or
+  /// another activity is focused, such as: a split-screen app, a phone call, a
+  /// picture-in-picture app, a system dialog, another view, when the
+  /// notification window shade is down, or the application switcher is visible.
   ///
   /// Apps in this state should assume that they may be [paused] at any time.
   inactive,

shell/platform/android/io/flutter/app/FlutterActivity.java

@@ -157,6 +157,12 @@ public void onUserLeaveHint() {
     eventDelegate.onUserLeaveHint();
   }
 
+  @Override
+  public void onWindowFocusChanged(boolean hasFocus) {
+    super.onWindowFocusChanged(hasFocus);
+    eventDelegate.onWindowFocusChanged(hasFocus);
+  }
+
   @Override
   public void onTrimMemory(int level) {
     eventDelegate.onTrimMemory(level);

shell/platform/android/io/flutter/app/FlutterActivityDelegate.java

@@ -260,6 +260,11 @@ public void onUserLeaveHint() {
     flutterView.getPluginRegistry().onUserLeaveHint();
   }
 
+  @Override
+  public void onWindowFocusChanged(boolean hasFocus) {
+    flutterView.getPluginRegistry().onWindowFocusChanged(hasFocus);
+  }
+
   @Override
   public void onTrimMemory(int level) {
     // Use a trim level delivered while the application is running so the

shell/platform/android/io/flutter/app/FlutterActivityEvents.java

@@ -64,4 +64,10 @@ public interface FlutterActivityEvents
 
   /** @see android.app.Activity#onUserLeaveHint() */
   void onUserLeaveHint();
+
+  /**
+   * @param hasFocus True if the current activity window has focus.
+   * @see android.app.Activity#onWindowFocusChanged(boolean)
+   */
+  void onWindowFocusChanged(boolean hasFocus);
 }

shell/platform/android/io/flutter/app/FlutterFragmentActivity.java

@@ -155,6 +155,12 @@ public void onUserLeaveHint() {
     eventDelegate.onUserLeaveHint();
   }
 
+  @Override
+  public void onWindowFocusChanged(boolean hasFocus) {
+    super.onWindowFocusChanged(hasFocus);
+    eventDelegate.onWindowFocusChanged(hasFocus);
+  }
+
   @Override
   public void onTrimMemory(int level) {
     super.onTrimMemory(level);

shell/platform/android/io/flutter/app/FlutterPluginRegistry.java

@@ -28,6 +28,7 @@ public class FlutterPluginRegistry
         PluginRegistry.RequestPermissionsResultListener,
         PluginRegistry.ActivityResultListener,
         PluginRegistry.NewIntentListener,
+        PluginRegistry.WindowFocusChangedListener,
         PluginRegistry.UserLeaveHintListener,
         PluginRegistry.ViewDestroyListener {
   private static final String TAG = "FlutterPluginRegistry";
@@ -44,6 +45,7 @@ public class FlutterPluginRegistry
   private final List<ActivityResultListener> mActivityResultListeners = new ArrayList<>(0);
   private final List<NewIntentListener> mNewIntentListeners = new ArrayList<>(0);
   private final List<UserLeaveHintListener> mUserLeaveHintListeners = new ArrayList<>(0);
+  private final List<WindowFocusChangedListener> mWindowFocusChangedListeners = new ArrayList<>(0);
   private final List<ViewDestroyListener> mViewDestroyListeners = new ArrayList<>(0);
 
   public FlutterPluginRegistry(FlutterNativeView nativeView, Context context) {
@@ -182,6 +184,12 @@ public Registrar addUserLeaveHintListener(UserLeaveHintListener listener) {
       return this;
     }
 
+    @Override
+    public Registrar addWindowFocusChangedListener(WindowFocusChangedListener listener) {
+      mWindowFocusChangedListeners.add(listener);
+      return this;
+    }
+
     @Override
     public Registrar addViewDestroyListener(ViewDestroyListener listener) {
       mViewDestroyListeners.add(listener);
@@ -227,6 +235,13 @@ public void onUserLeaveHint() {
     }
   }
 
+  @Override
+  public void onWindowFocusChanged(boolean hasFocus) {
+    for (WindowFocusChangedListener listener : mWindowFocusChangedListeners) {
+      listener.onWindowFocusChanged(hasFocus);
+    }
+  }
+
   @Override
   public boolean onViewDestroy(FlutterNativeView view) {
     boolean handled = false;

shell/platform/android/io/flutter/embedding/android/FlutterActivity.java

@@ -949,6 +949,14 @@ public void onUserLeaveHint() {
     }
   }
 
+  @Override
+  public void onWindowFocusChanged(boolean hasFocus) {
+    super.onWindowFocusChanged(hasFocus);
+    if (stillAttachedForEvent("onWindowFocusChanged")) {
+      delegate.onWindowFocusChanged(hasFocus);
+    }
+  }
+
   @Override
   public void onTrimMemory(int level) {
     super.onTrimMemory(level);

shell/platform/android/io/flutter/embedding/android/FlutterActivityAndFragmentDelegate.java

@@ -581,7 +581,7 @@ public boolean onPreDraw() {
   void onResume() {
     Log.v(TAG, "onResume()");
     ensureAlive();
-    if (host.shouldDispatchAppLifecycleState()) {
+    if (host.shouldDispatchAppLifecycleState() && flutterEngine != null) {
       flutterEngine.getLifecycleChannel().appIsResumed();
     }
   }
@@ -629,7 +629,7 @@ void updateSystemUiOverlays() {
   void onPause() {
     Log.v(TAG, "onPause()");
     ensureAlive();
-    if (host.shouldDispatchAppLifecycleState()) {
+    if (host.shouldDispatchAppLifecycleState() && flutterEngine != null) {
       flutterEngine.getLifecycleChannel().appIsInactive();
     }
   }
@@ -652,7 +652,7 @@ void onStop() {
     Log.v(TAG, "onStop()");
     ensureAlive();
 
-    if (host.shouldDispatchAppLifecycleState()) {
+    if (host.shouldDispatchAppLifecycleState() && flutterEngine != null) {
       flutterEngine.getLifecycleChannel().appIsPaused();
     }
 
@@ -763,7 +763,7 @@ void onDetach() {
       platformPlugin = null;
     }
 
-    if (host.shouldDispatchAppLifecycleState()) {
+    if (host.shouldDispatchAppLifecycleState() && flutterEngine != null) {
       flutterEngine.getLifecycleChannel().appIsDetached();
     }
 
@@ -898,6 +898,27 @@ void onUserLeaveHint() {
     }
   }
 
+  /**
+   * Invoke this from {@code Activity#onWindowFocusChanged()}.
+   *
+   * <p>A {@code Fragment} host must have its containing {@code Activity} forward this call so that
+   * the {@code Fragment} can then invoke this method.
+   */
+  void onWindowFocusChanged(boolean hasFocus) {
+    ensureAlive();
+    Log.v(TAG, "Received onWindowFocusChanged: " + (hasFocus ? "true" : "false"));
+    if (host.shouldDispatchAppLifecycleState() && flutterEngine != null) {
+      // TODO(gspencergoog): Once we have support for multiple windows/views,
+      // this code will need to consult the list of windows/views to determine if
+      // any windows in the app are focused and call the appropriate function.
+      if (hasFocus) {
+        flutterEngine.getLifecycleChannel().aWindowIsFocused();
+      } else {
+        flutterEngine.getLifecycleChannel().noWindowsAreFocused();
+      }
+    }
+  }
+
   /**
    * Invoke this from {@link android.app.Activity#onTrimMemory(int)}.
    *

shell/platform/android/io/flutter/embedding/android/FlutterFragment.java

@@ -8,13 +8,16 @@
 import android.content.ComponentCallbacks2;
 import android.content.Context;
 import android.content.Intent;
+import android.os.Build;
 import android.os.Bundle;
 import android.view.LayoutInflater;
 import android.view.View;
 import android.view.ViewGroup;
+import android.view.ViewTreeObserver.OnWindowFocusChangeListener;
 import androidx.activity.OnBackPressedCallback;
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
+import androidx.annotation.RequiresApi;
 import androidx.annotation.VisibleForTesting;
 import androidx.fragment.app.Fragment;
 import androidx.fragment.app.FragmentActivity;
@@ -167,6 +170,19 @@ public class FlutterFragment extends Fragment
   protected static final String ARG_SHOULD_AUTOMATICALLY_HANDLE_ON_BACK_PRESSED =
       "should_automatically_handle_on_back_pressed";
 
+  @RequiresApi(18)
+  private final OnWindowFocusChangeListener onWindowFocusChangeListener =
+      Build.VERSION.SDK_INT >= 18
+          ? new OnWindowFocusChangeListener() {
+            @Override
+            public void onWindowFocusChanged(boolean hasFocus) {
+              if (stillAttachedForEvent("onWindowFocusChanged")) {
+                delegate.onWindowFocusChanged(hasFocus);
+              }
+            }
+          }
+          : null;
+
   /**
    * Creates a {@code FlutterFragment} with a default configuration.
    *
@@ -1109,9 +1125,23 @@ public void onStop() {
     }
   }
 
+  @Override
+  public void onViewCreated(View view, Bundle savedInstanceState) {
+    super.onViewCreated(view, savedInstanceState);
+    if (Build.VERSION.SDK_INT >= 18) {
+      view.getViewTreeObserver().addOnWindowFocusChangeListener(onWindowFocusChangeListener);
+    }
+  }
+
   @Override
   public void onDestroyView() {
     super.onDestroyView();
+    if (Build.VERSION.SDK_INT >= 18) {
+      // onWindowFocusChangeListener is API 18+ only.
+      requireView()
+          .getViewTreeObserver()
+          .removeOnWindowFocusChangeListener(onWindowFocusChangeListener);
+    }
     if (stillAttachedForEvent("onDestroyView")) {
       delegate.onDestroyView();
     }

shell/platform/android/io/flutter/embedding/engine/FlutterEngineConnectionRegistry.java

@@ -732,6 +732,10 @@ private static class FlutterEngineActivityPluginBinding implements ActivityPlugi
     private final Set<io.flutter.plugin.common.PluginRegistry.UserLeaveHintListener>
         onUserLeaveHintListeners = new HashSet<>();
 
+    @NonNull
+    private final Set<io.flutter.plugin.common.PluginRegistry.WindowFocusChangedListener>
+        onWindowFocusChangedListeners = new HashSet<>();
+
     @NonNull
     private final Set<OnSaveInstanceStateListener> onSaveInstanceStateListeners = new HashSet<>();
 
@@ -847,6 +851,25 @@ public void removeOnUserLeaveHintListener(
       onUserLeaveHintListeners.remove(listener);
     }
 
+    @Override
+    public void addOnWindowFocusChangedListener(
+        @NonNull io.flutter.plugin.common.PluginRegistry.WindowFocusChangedListener listener) {
+      onWindowFocusChangedListeners.add(listener);
+    }
+
+    @Override
+    public void removeOnWindowFocusChangedListener(
+        @NonNull io.flutter.plugin.common.PluginRegistry.WindowFocusChangedListener listener) {
+      onWindowFocusChangedListeners.remove(listener);
+    }
+
+    void onWindowFocusChanged(boolean hasFocus) {
+      for (io.flutter.plugin.common.PluginRegistry.WindowFocusChangedListener listener :
+          onWindowFocusChangedListeners) {
+        listener.onWindowFocusChanged(hasFocus);
+      }
+    }
+
     @Override
     public void addOnSaveStateListener(@NonNull OnSaveInstanceStateListener listener) {
       onSaveInstanceStateListeners.add(listener);