Merge "Added notes about Android 16 behavior of virtual device owners." into main

3 files changed, 80 insertions, 30 deletions

diff --git a/core/java/android/app/Activity.java b/core/java/android/app/Activity.java
index 220fbb5c16a6..252d23f69400 100644
--- a/core/java/android/app/Activity.java
+++ b/core/java/android/app/Activity.java
@@ -7680,16 +7680,23 @@ public class Activity extends ContextThemeWrapper
     }
 
     /**
-     * Change the desired orientation of this activity.  If the activity
-     * is currently in the foreground or otherwise impacting the screen
-     * orientation, the screen will immediately be changed (possibly causing
-     * the activity to be restarted). Otherwise, this will be used the next
-     * time the activity is visible.
-     *
-     * <aside class="note"><b>Note:</b> Device manufacturers can configure devices to override
-     *    (ignore) calls to this method to improve the layout of orientation-restricted apps. See
-     *    <a href="{@docRoot}guide/practices/device-compatibility-mode">
-     *      Device compatibility mode</a>.
+     * Change the desired orientation of this activity. If the activity is currently in the
+     * foreground or otherwise impacting the screen orientation, the screen is immediately changed
+     * (possibly causing the activity to be restarted). Otherwise, the requested orientation is used
+     * the next time the activity is visible.
+     *
+     * <aside class="note"><b>Note:</b>
+     *     <ul>
+     *         <li>Device manufacturers can configure devices to override (ignore) calls to this
+     *             method to improve the layout of orientation-restricted apps.</li>
+     *         <li>On devices with Android 16 (API level 36) or higher installed, virtual device
+     *             owners (limited to select trusted and privileged apps) can optimize app layout on
+     *             displays they manage by ignoring calls to this method. See also
+     *             <a href="https://source.android.com/docs/core/permissions/app-streaming">
+     *               Companion app streaming</a>.</li>
+     *     </ul>
+     *     <p>See <a href="{@docRoot}guide/practices/device-compatibility-mode">Device
+     *     compatibility mode</a>.</p>
      * </aside>
      *
      * @param requestedOrientation An orientation constant as used in
@@ -7708,11 +7715,24 @@ public class Activity extends ContextThemeWrapper
     }
 
     /**
-     * Return the current requested orientation of the activity.  This will
-     * either be the orientation requested in its component's manifest, or
-     * the last requested orientation given to
+     * Return the current requested orientation of the activity. This is either the orientation
+     * requested in the app manifest, or the last requested orientation given to
      * {@link #setRequestedOrientation(int)}.
      *
+     * <aside class="note"><b>Note:</b>
+     *     <ul>
+     *         <li>Device manufacturers can configure devices to ignore calls to this method to
+     *             improve the layout of orientation-restricted apps.</li>
+     *         <li>On devices with Android 16 (API level 36) or higher installed, virtual device
+     *             owners (limited to select trusted and privileged apps) can optimize app layout on
+     *             displays they manage by ignoring calls to this method. See also
+     *             <a href="https://source.android.com/docs/core/permissions/app-streaming">
+     *               Companion app streaming</a>.</li>
+     *     </ul>
+     *     <p>See <a href="{@docRoot}guide/practices/device-compatibility-mode">Device
+     *     compatibility mode</a>.</p>
+     * </aside>
+     *
      * @return Returns an orientation constant as used in
      * {@link ActivityInfo#screenOrientation ActivityInfo.screenOrientation}.
      */
diff --git a/core/java/android/hardware/display/VirtualDisplayConfig.java b/core/java/android/hardware/display/VirtualDisplayConfig.java
index 2a9ee7f07934..322e139d9686 100644
--- a/core/java/android/hardware/display/VirtualDisplayConfig.java
+++ b/core/java/android/hardware/display/VirtualDisplayConfig.java
@@ -243,9 +243,11 @@ public final class VirtualDisplayConfig implements Parcelable {
     }
 
     /**
-     * Whether this virtual display ignores fixed orientation, aspect ratio and resizability
+     * Whether this virtual display ignores fixed orientation, aspect ratio, and resizability
      * of apps.
      *
+     * @return Whether orientation, aspect ratio, and resizability restrictions are ignored.
+     *
      * @see Builder#setIgnoreActivitySizeRestrictions(boolean)
      * @hide
      */
diff --git a/core/res/res/values/attrs_manifest.xml b/core/res/res/values/attrs_manifest.xml
index aaf84201821f..15230c299973 100644
--- a/core/res/res/values/attrs_manifest.xml
+++ b/core/res/res/values/attrs_manifest.xml
@@ -846,16 +846,23 @@
             This enum value is introduced in API level 31. -->
         <enum name="singleInstancePerTask" value="4" />
     </attr>
-    <!-- Specify the orientation an activity should be run in.  If not
-         specified, it will run in the current preferred orientation
-         of the screen.
+    <!-- Specify the orientation an activity should run in. If the orientation is not specified, the
+         system determines the best orientation for the activity.
          <p>This attribute is supported by the <a
             href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a>
             element.
-         <aside class="note"><b>Note:</b> Device manufacturers can configure devices to override
-            (ignore) this attribute to improve the layout of apps. See
-            <a href="{@docRoot}guide/practices/device-compatibility-mode">
-            Device compatibility mode</a>.
+         <aside class="note"><b>Note:</b>
+            <ul>
+                <li>Device manufacturers can configure devices to override (ignore) this attribute
+                    to improve the layout of apps.</li>
+                <li>On devices with Android 16 (API level 36) or higher installed, virtual device
+                    owners (limited to select trusted and privileged apps) can configure devices
+                    they manage to override (ignore) this attribute to improve app layout. See also
+                    <a href="https://source.android.com/docs/core/permissions/app-streaming">
+                    Companion app streaming</a>.</li>
+             </ul>
+             <p>See <a href="{@docRoot}guide/practices/device-compatibility-mode">Device
+             compatibility mode</a>.</p>
          </aside> -->
     <attr name="screenOrientation">
         <!-- No preference specified: let the system decide the best
@@ -1474,12 +1481,19 @@
             <ul>
                 <li>On Android 11 (API level 30) and lower, the value of
                     {@link android.R.attr#screenOrientation} is ignored for resizeable activities
-                    in multi-window mode.
+                    in multi-window mode.</li>
                 <li>Device manufacturers can configure devices to override (ignore) this attribute
                     to force apps to resize. The override does not affect the app's support for
                     multi-window mode. See
-                    <a href="{@docRoot}guide/practices/device-compatibility-mode">
-                    Device compatibility mode</a>.
+                    <a href="{@docRoot}guide/practices/device-compatibility-mode">Device
+                    compatibility mode</a>.</li>
+                <li>On devices with Android 16 (API level 36) or higher installed, virtual device
+                    owners (limited to select trusted and privileged apps) can configure devices
+                    they manage to override (ignore) this attribute to force apps to resize. See
+                    <a href="{@docRoot}guide/practices/device-compatibility-mode">Device
+                    compatibility mode</a>. See also
+                    <a href="https://source.android.com/docs/core/permissions/app-streaming">
+                    Companion app streaming</a>.</li>
             </ul>
          </aside> -->
     <attr name="resizeableActivity" format="boolean" />
@@ -1504,11 +1518,18 @@
          <aside class="note"><b>Note:</b>
             <ul>
                 <li>This attribute is ignored if the activity has
-                    {@link android.R.attr#resizeableActivity} set to {@code true}.
+                    {@link android.R.attr#resizeableActivity} set to {@code true}.</li>
                 <li>Device manufacturers can configure devices to override (ignore) this attribute
                     to improve the layout of apps. See
-                    <a href="{@docRoot}guide/practices/device-compatibility-mode">
-                    Device compatibility mode</a>.
+                    <a href="{@docRoot}guide/practices/device-compatibility-mode#override_any_orientation_to_user">
+                    Device compatibility mode</a>.</li>
+                <li>On devices with Android 16 (API level 36) or higher installed, virtual device
+                    owners (limited to select trusted and privileged apps) can configure devices
+                    they manage to override (ignore) this attribute to improve app layout. See
+                    <a href="{@docRoot}guide/practices/device-compatibility-mode#override_any_orientation_to_user">
+                    Device compatibility mode</a>. See also
+                    <a href="https://source.android.com/docs/core/permissions/app-streaming">
+                    Companion app streaming</a>.</li>
             </ul>
          </aside> -->
     <attr name="maxAspectRatio" format="float" />
@@ -1522,11 +1543,18 @@
          <aside class="note"><b>Note:</b>
             <ul>
                 <li>This attribute is ignored if the activity has
-                    {@link android.R.attr#resizeableActivity} set to {@code true}.
+                    {@link android.R.attr#resizeableActivity} set to {@code true}.</li>
                 <li>Device manufacturers can configure devices to override (ignore) this attribute
                     to improve the layout of apps. See
-                    <a href="{@docRoot}guide/practices/device-compatibility-mode">
-                    Device compatibility mode</a>.
+                    <a href="{@docRoot}guide/practices/device-compatibility-mode">Device
+                    compatibility mode</a>.</li>
+                <li>On devices with Android 16 (API level 36) or higher installed, virtual device
+                    owners (limited to select trusted and privileged apps) can configure devices
+                    they manage to override (ignore) this attribute to improve app layout. See
+                    <a href="{@docRoot}guide/practices/device-compatibility-mode">Device
+                    compatibility mode</a>. See also
+                    <a href="https://source.android.com/docs/core/permissions/app-streaming">
+                    Companion app streaming</a>.</li>
             </ul>
          </aside> -->
     <attr name="minAspectRatio" format="float" />