Report top resumed activity state change

Some system resources can only be accessed exclusively by a single
client at a time. Previously there was only one resumed activity in
the system at any point, so apps were usually trying to obtain such
access in onResume. With multi-resume this is no longer a good place
to do so, because:
- onResume may be called for activity that is not on top;
- top resumed status may be switched between different resumed
  activities in multi-window mode by tapping on them.

This adds a separate callback to inform apps about top resumed state
gain and loss events. The following rules apply:
- both callbacks can only be delivered between onResume and onPause;
- top resumed state loss always follows top resumed state gain;
- the callbacks are optional, activity can go from onResume to
  onPause without obtaining top position.

Bug: 117135575
Test: atest CtsActivityManagerDeviceTestCases:ActivityLifecyclePositionTests
Change-Id: I45797afe47b166b22cfb75b64132b22d3fb4ecc7

1 files changed, 10 insertions, 0 deletions

diff --git a/core/java/android/app/ClientTransactionHandler.java b/core/java/android/app/ClientTransactionHandler.java
index 07dbb6bee9fd..70badfae4a20 100644
--- a/core/java/android/app/ClientTransactionHandler.java
+++ b/core/java/android/app/ClientTransactionHandler.java
@@ -105,6 +105,16 @@ public abstract class ClientTransactionHandler {
             boolean isForward, String reason);
 
     /**
+     * Notify the activity about top resumed state change.
+     * @param token Target activity token.
+     * @param isTopResumedActivity Current state of the activity, {@code true} if it's the
+     *                             topmost resumed activity in the system, {@code false} otherwise.
+     * @param reason Reason for performing this operation.
+     */
+    public abstract void handleTopResumedActivityChanged(IBinder token,
+            boolean isTopResumedActivity, String reason);
+
+    /**
      * Stop the activity.
      * @param token Target activity token.
      * @param show Flag indicating whether activity is still shown.