From 93f0637c0461391375b2ac56cf48163b05722bea Mon Sep 17 00:00:00 2001
From: Yunfan Chen <yunfanc@google.com>
Date: Thu, 15 Dec 2022 12:01:09 +0900
Subject: [PATCH] Improve API of requestFullscreenMode

This patch improves the documentation and annotation of the API.
1. Added explanation of the type of Throwable: IllegalStateException
for all cases and will contain a detailed message to explain the
reason.
2. Explained that the activity need to be the focused display
top-most one.
3. Removed non-necessary @NonNull annotation
4. Documented the const of the request types.

Bug: 262491455
Test: atest CtsWindowManagerDeviceTestCases:FreeformWindowingModeTests
Change-Id: I950ef0aca9e7aa73e97cc3dd35f7f101ea59f863
---
 core/api/current.txt                |  2 +-
 core/java/android/app/Activity.java | 18 +++++++++++++-----
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/core/api/current.txt b/core/api/current.txt
index a7bca5a9e09cb..9399a6f8acc0d 100644
--- a/core/api/current.txt
+++ b/core/api/current.txt
@@ -4294,7 +4294,7 @@ package android.app {
     method @Deprecated public final void removeDialog(int);
     method public void reportFullyDrawn();
     method public android.view.DragAndDropPermissions requestDragAndDropPermissions(android.view.DragEvent);
-    method public void requestFullscreenMode(@NonNull int, @Nullable android.os.OutcomeReceiver<java.lang.Void,java.lang.Throwable>);
+    method public void requestFullscreenMode(int, @Nullable android.os.OutcomeReceiver<java.lang.Void,java.lang.Throwable>);
     method public final void requestPermissions(@NonNull String[], int);
     method public final void requestShowKeyboardShortcuts();
     method @Deprecated public boolean requestVisibleBehind(boolean);
diff --git a/core/java/android/app/Activity.java b/core/java/android/app/Activity.java
index b9eb443169563..d1772e3788922 100644
--- a/core/java/android/app/Activity.java
+++ b/core/java/android/app/Activity.java
@@ -995,8 +995,13 @@ public class Activity extends ContextThemeWrapper
     })
     public @interface FullscreenModeRequest {}
 
+    /** Request type of {@link #requestFullscreenMode(int, OutcomeReceiver)}, to request exiting the
+     *  requested fullscreen mode and restore to the previous multi-window mode.
+     */
     public static final int FULLSCREEN_MODE_REQUEST_EXIT = 0;
-
+    /** Request type of {@link #requestFullscreenMode(int, OutcomeReceiver)}, to request enter
+     *  fullscreen mode from multi-window mode.
+     */
     public static final int FULLSCREEN_MODE_REQUEST_ENTER = 1;
 
     private boolean mShouldDockBigOverlays;
@@ -3015,8 +3020,9 @@ public class Activity extends ContextThemeWrapper
     /**
      * Request to put the a freeform activity into fullscreen. This will only be allowed if the
      * activity is on a freeform display, such as a desktop device. The requester has to be the
-     * top-most activity and the request should be a response to a user input. When getting
-     * fullscreen and receiving corresponding {@link #onConfigurationChanged(Configuration)} and
+     * top-most activity of the focused display, and the request should be a response to a user
+     * input. When getting fullscreen and receiving corresponding
+     * {@link #onConfigurationChanged(Configuration)} and
      * {@link #onMultiWindowModeChanged(boolean, Configuration)}, the activity should relayout
      * itself and the system bars' visibilities can be controlled as usual fullscreen apps.
      *
@@ -3034,9 +3040,11 @@ public class Activity extends ContextThemeWrapper
      * @param approvalCallback Optional callback, use {@code null} when not necessary. When the
      *                         request is approved or rejected, the callback will be triggered. This
      *                         will happen before any configuration change. The callback will be
-     *                         dispatched on the main thread.
+     *                         dispatched on the main thread. If the request is rejected, the
+     *                         Throwable provided will be an {@link IllegalStateException} with a
+     *                         detailed message can be retrieved by {@link Throwable#getMessage()}.
      */
-    public void requestFullscreenMode(@NonNull @FullscreenModeRequest int request,
+    public void requestFullscreenMode(@FullscreenModeRequest int request,
             @Nullable OutcomeReceiver<Void, Throwable> approvalCallback) {
         FullscreenRequestHandler.requestFullscreenMode(
                 request, approvalCallback, mCurrentConfig, getActivityToken());