Introduce IOnBackInvokedCallback and OnBackInvokedDispatcher

Test: mp core, m -j update-api
Bug:195946584

Change-Id: I7997c69fca69cc8875410d8240caf48feef34378

core/api/current.txt

@@ -49317,6 +49317,22 @@ package android.view {
     field public int toolType;
   }
 
+  public interface OnBackInvokedCallback {
+    method public default void onBackInvoked();
+  }
+
+  public abstract class OnBackInvokedDispatcher {
+    ctor public OnBackInvokedDispatcher();
+    method public abstract void registerOnBackInvokedCallback(@NonNull android.view.OnBackInvokedCallback, int);
+    method public abstract void unregisterOnBackInvokedCallback(@NonNull android.view.OnBackInvokedCallback);
+    field public static final int PRIORITY_DEFAULT = 0; // 0x0
+    field public static final int PRIORITY_OVERLAY = 1000000; // 0xf4240
+  }
+
+  public interface OnBackInvokedDispatcherOwner {
+    method @Nullable public android.view.OnBackInvokedDispatcher getOnBackInvokedDispatcher();
+  }
+
   public interface OnReceiveContentListener {
     method @Nullable public android.view.ContentInfo onReceiveContent(@NonNull android.view.View, @NonNull android.view.ContentInfo);
   }

core/java/android/view/OnBackInvokedCallback.java

@@ -0,0 +1,70 @@
+/*
+ * Copyright (C) 2022 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.view;
+
+import android.app.Activity;
+import android.app.Dialog;
+
+/**
+ * Interface for applications to register back invocation callbacks. This allows the client
+ * to customize various back behaviors by overriding the corresponding callback methods.
+ *
+ * Callback instances can be added to and removed from {@link OnBackInvokedDispatcher}, held
+ * by classes that implement {@link OnBackInvokedDispatcherOwner} (such as {@link Activity},
+ * {@link Dialog} and {@link View}).
+ *
+ * Under the hood callbacks are registered at window level. When back is triggered,
+ * callbacks on the in-focus window are invoked in reverse order in which they are added
+ * within the same priority. Between different pirorities, callbacks with higher priority
+ * are invoked first.
+ *
+ * See {@link OnBackInvokedDispatcher#registerOnBackInvokedCallback(OnBackInvokedCallback, int)}
+ * for specifying callback priority.
+ */
+public interface OnBackInvokedCallback {
+   /**
+    * Called when a back gesture has been started, or back button has been pressed down.
+    *
+    * @hide
+    */
+    default void onBackStarted() { };
+
+    /**
+     * Called on back gesture progress.
+     *
+     * @param touchX Absolute X location of the touch point.
+     * @param touchY Absolute Y location of the touch point.
+     * @param progress Value between 0 and 1 on how far along the back gesture is.
+     *
+     * @hide
+     */
+    // TODO(b/210539672): combine back progress params into BackEvent.
+    default void onBackProgressed(int touchX, int touchY, float progress) { };
+
+    /**
+     * Called when a back gesture or back button press has been cancelled.
+     *
+     * @hide
+     */
+    default void onBackCancelled() { };
+
+    /**
+     * Called when a back gesture has been completed and committed, or back button pressed
+     * has been released and committed.
+     */
+    default void onBackInvoked() { };
+}

core/java/android/view/OnBackInvokedDispatcher.java

@@ -0,0 +1,76 @@
+/*
+ * Copyright (C) 2022 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.view;
+
+import android.annotation.IntDef;
+import android.annotation.NonNull;
+import android.annotation.SuppressLint;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * Dispatcher to register {@link OnBackInvokedCallback} instances for handling
+ * back invocations.
+ *
+ * It also provides interfaces to update the attributes of {@link OnBackInvokedCallback}.
+ * Attribute updates are proactively pushed to the window manager if they change the dispatch
+ * target (a.k.a. the callback to be invoked next), or its behavior.
+ */
+public abstract class OnBackInvokedDispatcher {
+    /** @hide */
+    @IntDef({
+            PRIORITY_DEFAULT,
+            PRIORITY_OVERLAY,
+    })
+    @Retention(RetentionPolicy.SOURCE)
+    public @interface Priority{}
+
+    /**
+     * Priority level of {@link OnBackInvokedCallback}s for overlays such as menus and
+     * navigation drawers that should receive back dispatch before non-overlays.
+     */
+    public static final int PRIORITY_OVERLAY = 1000000;
+
+    /**
+     * Default priority level of {@link OnBackInvokedCallback}s.
+     */
+    public static final int PRIORITY_DEFAULT = 0;
+
+    /**
+     * Registers a {@link OnBackInvokedCallback}.
+     *
+     * Within the same priority level, callbacks are invoked in the reverse order in which
+     * they are registered. Higher priority callbacks are invoked before lower priority ones.
+     *
+     * @param callback The callback to be registered. If the callback instance has been already
+     *                 registered, the existing instance (no matter its priority) will be
+     *                 unregistered and registered again.
+     * @param priority The priority of the callback.
+     */
+    @SuppressLint("SamShouldBeLast")
+    public abstract void registerOnBackInvokedCallback(
+            @NonNull OnBackInvokedCallback callback, @Priority int priority);
+
+    /**
+     * Unregisters a {@link OnBackInvokedCallback}.
+     *
+     * @param callback The callback to be unregistered. Does nothing if the callback has not been
+     *                 registered.
+     */
+    public abstract void unregisterOnBackInvokedCallback(@NonNull OnBackInvokedCallback callback);
+}

core/java/android/view/OnBackInvokedDispatcherOwner.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright (C) 2022 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.view;
+
+import android.annotation.Nullable;
+
+/**
+ * A class that provides an {@link OnBackInvokedDispatcher} that allows you to register
+ * an {@link OnBackInvokedCallback} for handling the system back invocation behavior.
+ */
+public interface OnBackInvokedDispatcherOwner {
+    /**
+     * Returns the {@link OnBackInvokedDispatcher} that should dispatch the back invocation
+     * to its registered {@link OnBackInvokedCallback}s.
+     * Returns null when the root view is not attached to a window or a view tree with a decor.
+     */
+    @Nullable
+    OnBackInvokedDispatcher getOnBackInvokedDispatcher();
+}