Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 709904f8 authored by Winson Chung's avatar Winson Chung
Browse files

Updating PiP API and documentation. 



- Renaming PictureInPictureArgs to PictureInPictureParams, making it
  immutable and built with a builder class.  In addition, making the
  aspect ratio rational.
- Moving the check to get max number of actions to the activity to have
  more flexibility going forward
- Also ensures that enterPictureInPictureMode() returns true if the
  activity is already in PiP mode.
- Will follow up with CL to remove PictureInPictureArgs and related methods
  once this CL drops

Bug: 35765211
Bug: 37638323
Bug: 37637423
Bug: 37636674
Bug: 36342780
Test: android.server.cts.ActivityManagerPinnedStackTests
Test: android.app.cts.PictureInPictureParamsBuilderTest

Change-Id: I54a487d55a59c9ce8ac7bd6c80c61209c8b26224
Signed-off-by: default avatarWinson Chung <winsonc@google.com>
parent 62bb027d

api/current.txt

+27 −11
Original line number Diff line number Diff line
@@ -3584,8 +3584,9 @@ package android.app { 
    method public boolean dispatchTouchEvent(android.view.MotionEvent);

    method public boolean dispatchTrackballEvent(android.view.MotionEvent);

    method public void dump(java.lang.String, java.io.FileDescriptor, java.io.PrintWriter, java.lang.String[]);

    method public void enterPictureInPictureMode();

    method public boolean enterPictureInPictureMode(android.app.PictureInPictureArgs);

    method public deprecated void enterPictureInPictureMode();

    method public deprecated boolean enterPictureInPictureMode(android.app.PictureInPictureArgs);

    method public boolean enterPictureInPictureMode(android.app.PictureInPictureParams);

    method public <T extends android.view.View> T findViewById(int);

    method public void finish();

    method public void finishActivity(int);
@@ -3609,6 +3610,7 @@ package android.app { 
    method public android.view.LayoutInflater getLayoutInflater();

    method public android.app.LoaderManager getLoaderManager();

    method public java.lang.String getLocalClassName();

    method public int getMaxNumPictureInPictureActions();

    method public final android.media.session.MediaController getMediaController();

    method public android.view.MenuInflater getMenuInflater();

    method public final android.app.Activity getParent();
@@ -3760,6 +3762,7 @@ package android.app { 
    method public void setIntent(android.content.Intent);

    method public final void setMediaController(android.media.session.MediaController);

    method public void setPictureInPictureArgs(android.app.PictureInPictureArgs);

    method public void setPictureInPictureParams(android.app.PictureInPictureParams);

    method public final deprecated void setProgress(int);

    method public final deprecated void setProgressBarIndeterminate(boolean);

    method public final deprecated void setProgressBarIndeterminateVisibility(boolean);
@@ -3838,7 +3841,7 @@ package android.app { 
    method public int getLauncherLargeIconDensity();

    method public int getLauncherLargeIconSize();

    method public int getLockTaskModeState();

    method public static int getMaxNumPictureInPictureActions();

    method public static deprecated int getMaxNumPictureInPictureActions();

    method public int getMemoryClass();

    method public void getMemoryInfo(android.app.ActivityManager.MemoryInfo);

    method public static void getMyMemoryState(android.app.ActivityManager.RunningAppProcessInfo);
@@ -5695,16 +5698,29 @@ package android.app { 
    method public abstract void onSendFinished(android.app.PendingIntent, android.content.Intent, int, java.lang.String, android.os.Bundle);

  }













  public final class PictureInPictureArgs implements android.os.Parcelable {













    ctor public PictureInPictureArgs();













    ctor public PictureInPictureArgs(float, java.util.List<android.app.RemoteAction>);













    method public android.app.PictureInPictureArgs clone();













  public final deprecated class PictureInPictureArgs extends android.app.PictureInPictureParams {













    ctor public deprecated PictureInPictureArgs();













    ctor public deprecated PictureInPictureArgs(float, java.util.List<android.app.RemoteAction>);













    method public deprecated void setActions(java.util.List<android.app.RemoteAction>);













    method public deprecated void setAspectRatio(float);













    method public deprecated void setSourceRectHint(android.graphics.Rect);













  }

























  public class PictureInPictureParams implements android.os.Parcelable {















    method public int describeContents();













    method public void setActions(java.util.List<android.app.RemoteAction>);













    method public void setAspectRatio(float);













    method public void setSourceRectHint(android.graphics.Rect);















    method public void writeToParcel(android.os.Parcel, int);













    field public static final android.os.Parcelable.Creator<android.app.PictureInPictureArgs> CREATOR;













    field public static final android.os.Parcelable.Creator<android.app.PictureInPictureParams> CREATOR;













    field protected android.util.Rational mAspectRatio;













    field protected android.graphics.Rect mSourceRectHint;













    field protected java.util.List<android.app.RemoteAction> mUserActions;













  }

























  public static class PictureInPictureParams.Builder {













    ctor public PictureInPictureParams.Builder();













    method public android.app.PictureInPictureParams build();













    method public android.app.PictureInPictureParams.Builder setActions(java.util.List<android.app.RemoteAction>);













    method public android.app.PictureInPictureParams.Builder setAspectRatio(android.util.Rational);













    method public android.app.PictureInPictureParams.Builder setSourceRectHint(android.graphics.Rect);















  }





























  public class Presentation extends android.app.Dialog {

























api/system-current.txt



+27
−11




























Original line number
Diff line number
Diff line








@@ -3715,8 +3715,9 @@ package android.app {













    method public boolean dispatchTouchEvent(android.view.MotionEvent);















    method public boolean dispatchTrackballEvent(android.view.MotionEvent);















    method public void dump(java.lang.String, java.io.FileDescriptor, java.io.PrintWriter, java.lang.String[]);













    method public void enterPictureInPictureMode();













    method public boolean enterPictureInPictureMode(android.app.PictureInPictureArgs);













    method public deprecated void enterPictureInPictureMode();













    method public deprecated boolean enterPictureInPictureMode(android.app.PictureInPictureArgs);













    method public boolean enterPictureInPictureMode(android.app.PictureInPictureParams);















    method public <T extends android.view.View> T findViewById(int);















    method public void finish();















    method public void finishActivity(int);









@@ -3740,6 +3741,7 @@ package android.app {













    method public android.view.LayoutInflater getLayoutInflater();















    method public android.app.LoaderManager getLoaderManager();















    method public java.lang.String getLocalClassName();













    method public int getMaxNumPictureInPictureActions();















    method public final android.media.session.MediaController getMediaController();















    method public android.view.MenuInflater getMenuInflater();















    method public final android.app.Activity getParent();










@@ -3894,6 +3896,7 @@ package android.app {













    method public void setIntent(android.content.Intent);















    method public final void setMediaController(android.media.session.MediaController);















    method public void setPictureInPictureArgs(android.app.PictureInPictureArgs);













    method public void setPictureInPictureParams(android.app.PictureInPictureParams);















    method public final deprecated void setProgress(int);















    method public final deprecated void setProgressBarIndeterminate(boolean);















    method public final deprecated void setProgressBarIndeterminateVisibility(boolean);










@@ -3979,7 +3982,7 @@ package android.app {













    method public int getLauncherLargeIconDensity();















    method public int getLauncherLargeIconSize();















    method public int getLockTaskModeState();













    method public static int getMaxNumPictureInPictureActions();













    method public static deprecated int getMaxNumPictureInPictureActions();















    method public int getMemoryClass();















    method public void getMemoryInfo(android.app.ActivityManager.MemoryInfo);















    method public static void getMyMemoryState(android.app.ActivityManager.RunningAppProcessInfo);










@@ -5898,16 +5901,29 @@ package android.app {













    method public abstract void onSendFinished(android.app.PendingIntent, android.content.Intent, int, java.lang.String, android.os.Bundle);















  }



























  public final class PictureInPictureArgs implements android.os.Parcelable {













    ctor public PictureInPictureArgs();













    ctor public PictureInPictureArgs(float, java.util.List<android.app.RemoteAction>);













    method public android.app.PictureInPictureArgs clone();













  public final deprecated class PictureInPictureArgs extends android.app.PictureInPictureParams {













    ctor public deprecated PictureInPictureArgs();













    ctor public deprecated PictureInPictureArgs(float, java.util.List<android.app.RemoteAction>);













    method public deprecated void setActions(java.util.List<android.app.RemoteAction>);













    method public deprecated void setAspectRatio(float);













    method public deprecated void setSourceRectHint(android.graphics.Rect);













  }

























  public class PictureInPictureParams implements android.os.Parcelable {















    method public int describeContents();













    method public void setActions(java.util.List<android.app.RemoteAction>);













    method public void setAspectRatio(float);













    method public void setSourceRectHint(android.graphics.Rect);















    method public void writeToParcel(android.os.Parcel, int);













    field public static final android.os.Parcelable.Creator<android.app.PictureInPictureArgs> CREATOR;













    field public static final android.os.Parcelable.Creator<android.app.PictureInPictureParams> CREATOR;













    field protected android.util.Rational mAspectRatio;













    field protected android.graphics.Rect mSourceRectHint;













    field protected java.util.List<android.app.RemoteAction> mUserActions;













  }

























  public static class PictureInPictureParams.Builder {













    ctor public PictureInPictureParams.Builder();













    method public android.app.PictureInPictureParams build();













    method public android.app.PictureInPictureParams.Builder setActions(java.util.List<android.app.RemoteAction>);













    method public android.app.PictureInPictureParams.Builder setAspectRatio(android.util.Rational);













    method public android.app.PictureInPictureParams.Builder setSourceRectHint(android.graphics.Rect);















  }





























  public class Presentation extends android.app.Dialog {

























api/test-current.txt



+27
−11




























Original line number
Diff line number
Diff line








@@ -3586,8 +3586,9 @@ package android.app {













    method public boolean dispatchTouchEvent(android.view.MotionEvent);















    method public boolean dispatchTrackballEvent(android.view.MotionEvent);















    method public void dump(java.lang.String, java.io.FileDescriptor, java.io.PrintWriter, java.lang.String[]);













    method public void enterPictureInPictureMode();













    method public boolean enterPictureInPictureMode(android.app.PictureInPictureArgs);













    method public deprecated void enterPictureInPictureMode();













    method public deprecated boolean enterPictureInPictureMode(android.app.PictureInPictureArgs);













    method public boolean enterPictureInPictureMode(android.app.PictureInPictureParams);















    method public <T extends android.view.View> T findViewById(int);















    method public void finish();















    method public void finishActivity(int);









@@ -3611,6 +3612,7 @@ package android.app {













    method public android.view.LayoutInflater getLayoutInflater();















    method public android.app.LoaderManager getLoaderManager();















    method public java.lang.String getLocalClassName();













    method public int getMaxNumPictureInPictureActions();















    method public final android.media.session.MediaController getMediaController();















    method public android.view.MenuInflater getMenuInflater();















    method public final android.app.Activity getParent();










@@ -3762,6 +3764,7 @@ package android.app {













    method public void setIntent(android.content.Intent);















    method public final void setMediaController(android.media.session.MediaController);















    method public void setPictureInPictureArgs(android.app.PictureInPictureArgs);













    method public void setPictureInPictureParams(android.app.PictureInPictureParams);















    method public final deprecated void setProgress(int);















    method public final deprecated void setProgressBarIndeterminate(boolean);















    method public final deprecated void setProgressBarIndeterminateVisibility(boolean);










@@ -3841,7 +3844,7 @@ package android.app {













    method public int getLauncherLargeIconDensity();















    method public int getLauncherLargeIconSize();















    method public int getLockTaskModeState();













    method public static int getMaxNumPictureInPictureActions();













    method public static deprecated int getMaxNumPictureInPictureActions();















    method public int getMemoryClass();















    method public void getMemoryInfo(android.app.ActivityManager.MemoryInfo);















    method public static void getMyMemoryState(android.app.ActivityManager.RunningAppProcessInfo);










@@ -5709,16 +5712,29 @@ package android.app {













    method public abstract void onSendFinished(android.app.PendingIntent, android.content.Intent, int, java.lang.String, android.os.Bundle);















  }



























  public final class PictureInPictureArgs implements android.os.Parcelable {













    ctor public PictureInPictureArgs();













    ctor public PictureInPictureArgs(float, java.util.List<android.app.RemoteAction>);













    method public android.app.PictureInPictureArgs clone();













  public final deprecated class PictureInPictureArgs extends android.app.PictureInPictureParams {













    ctor public deprecated PictureInPictureArgs();













    ctor public deprecated PictureInPictureArgs(float, java.util.List<android.app.RemoteAction>);













    method public deprecated void setActions(java.util.List<android.app.RemoteAction>);













    method public deprecated void setAspectRatio(float);













    method public deprecated void setSourceRectHint(android.graphics.Rect);













  }

























  public class PictureInPictureParams implements android.os.Parcelable {















    method public int describeContents();













    method public void setActions(java.util.List<android.app.RemoteAction>);













    method public void setAspectRatio(float);













    method public void setSourceRectHint(android.graphics.Rect);















    method public void writeToParcel(android.os.Parcel, int);













    field public static final android.os.Parcelable.Creator<android.app.PictureInPictureArgs> CREATOR;













    field public static final android.os.Parcelable.Creator<android.app.PictureInPictureParams> CREATOR;













    field protected android.util.Rational mAspectRatio;













    field protected android.graphics.Rect mSourceRectHint;













    field protected java.util.List<android.app.RemoteAction> mUserActions;













  }

























  public static class PictureInPictureParams.Builder {













    ctor public PictureInPictureParams.Builder();













    method public android.app.PictureInPictureParams build();













    method public android.app.PictureInPictureParams.Builder setActions(java.util.List<android.app.RemoteAction>);













    method public android.app.PictureInPictureParams.Builder setAspectRatio(android.util.Rational);













    method public android.app.PictureInPictureParams.Builder setSourceRectHint(android.graphics.Rect);















  }





























  public class Presentation extends android.app.Dialog {

























core/java/android/app/Activity.java



+68
−26




























Original line number
Diff line number
Diff line








@@ -2039,70 +2039,112 @@ public class Activity extends ContextThemeWrapper





























    /**















     * Puts the activity in picture-in-picture mode if possible in the current system state. Any













     * prior calls to {@link #setPictureInPictureArgs(PictureInPictureArgs)} will still apply when













     * entering picture-in-picture through this call.













     * prior calls to {@link #setPictureInPictureParams(PictureInPictureParams)} will still apply













     * when entering picture-in-picture through this call.















     *













     * @see #enterPictureInPictureMode(PictureInPictureArgs)













     * @see #enterPictureInPictureMode(PictureInPictureParams)















     * @see android.R.attr#supportsPictureInPicture















     */













    @Deprecated















    public void enterPictureInPictureMode() {













        enterPictureInPictureMode(new PictureInPictureArgs());













        enterPictureInPictureMode(new PictureInPictureParams.Builder().build());













    }



























    /**













     * TO BE REMOVED













     */













    @Deprecated













    public boolean enterPictureInPictureMode(@NonNull PictureInPictureArgs args) {













        try {













            if (args == null) {













                throw new IllegalArgumentException("Expected non-null picture-in-picture args");













            }













            updatePictureInPictureParamsForContentInsets(args);













            return ActivityManagerNative.getDefault().enterPictureInPictureMode(mToken, args);













        } catch (RemoteException e) {













            return false;













        }















    }































    /**













     * Puts the activity in picture-in-picture mode if possible in the current system state with













     * explicit given arguments. Only the set parameters in {@param args} will override prior calls













     * {@link #setPictureInPictureArgs(PictureInPictureArgs)}.













     * Puts the activity in picture-in-picture mode if possible in the current system state. The













     * set parameters in {@param params} will be combined with the parameters from prior calls to













     * {@link #setPictureInPictureParams(PictureInPictureParams)}.















     *















     * The system may disallow entering picture-in-picture in various cases, including when the













     * activity is not visible.













     * activity is not visible, if the screen is locked or if the user has an activity pinned.















     *















     * @see android.R.attr#supportsPictureInPicture













     * @see PictureInPictureParams













     *













     * @param params non-null parameters to be combined with previously set parameters when entering













     * picture-in-picture.















     *













     * @param args the explicit non-null arguments to use when entering picture-in-picture.













     * @return whether the system successfully entered picture-in-picture.













     * @return true if the system puts this activity into picture-in-picture mode or was already













     * in picture-in-picture mode (@see {@link #isInPictureInPictureMode())















     */













    public boolean enterPictureInPictureMode(@NonNull PictureInPictureArgs args) {













    public boolean enterPictureInPictureMode(@NonNull PictureInPictureParams params) {















        try {













            if (args == null) {













                throw new IllegalArgumentException("Expected non-null picture-in-picture args");













            if (params == null) {













                throw new IllegalArgumentException("Expected non-null picture-in-picture params");















            }













            updatePictureInPictureArgsForContentInsets(args);













            return ActivityManagerNative.getDefault().enterPictureInPictureMode(mToken, args);













            updatePictureInPictureParamsForContentInsets(params);













            return ActivityManagerNative.getDefault().enterPictureInPictureMode(mToken, params);















        } catch (RemoteException e) {















            return false;















        }















    }





























    /**













     * TO BE REMOVED













     */













    public void setPictureInPictureArgs(@NonNull PictureInPictureArgs args) {













        setPictureInPictureParams(args);













    }





























    /**















     * Updates the properties of the picture-in-picture activity, or sets it to be used later when















     * {@link #enterPictureInPictureMode()} is called.















     *













     * @param args the new properties of the picture-in-picture.













     * @param params the new parameters for the picture-in-picture.















     */













    public void setPictureInPictureArgs(@NonNull PictureInPictureArgs args) {













    public void setPictureInPictureParams(@NonNull PictureInPictureParams params) {















        try {













            if (args == null) {













                throw new IllegalArgumentException("Expected non-null picture-in-picture args");













            if (params == null) {













                throw new IllegalArgumentException("Expected non-null picture-in-picture params");













            }













            updatePictureInPictureParamsForContentInsets(params);













            ActivityManagerNative.getDefault().setPictureInPictureParams(mToken, params);













        } catch (RemoteException e) {













        }















    }













            updatePictureInPictureArgsForContentInsets(args);













            ActivityManagerNative.getDefault().setPictureInPictureArgs(mToken, args);



























    /**













     * Return the number of actions that will be displayed in the picture-in-picture UI when the













     * user interacts with the activity currently in picture-in-picture mode. This number may change













     * if the global configuration changes (ie. if the device is plugged into an external display),













     * but will always be larger than three.













     */













    public int getMaxNumPictureInPictureActions() {













        try {













            return ActivityManagerNative.getDefault().getMaxNumPictureInPictureActions(mToken);















        } catch (RemoteException e) {













            return 0;















        }















    }































    /**













     * Updates the provided {@param args} with the last known content insets for this activity, to













     * Updates the provided {@param params} with the last known content insets for this activity, to















     * be used with the source hint rect for the transition into PiP.















     */













    private void updatePictureInPictureArgsForContentInsets(PictureInPictureArgs args) {













        if (args != null && args.hasSourceBoundsHint() && getWindow() != null &&













    private void updatePictureInPictureParamsForContentInsets(PictureInPictureParams params) {













        if (params != null && params.hasSourceBoundsHint() && getWindow() != null &&















                getWindow().peekDecorView() != null &&















                getWindow().peekDecorView().getViewRootImpl() != null) {













            args.setSourceRectHintInsets(













            params.setSourceRectHintInsets(















                    getWindow().peekDecorView().getViewRootImpl().getLastContentInsets());















        } else {













            args.setSourceRectHintInsets(null);













            params.setSourceRectHintInsets(null);















        }















    }

















































core/java/android/app/ActivityManager.java



+7
−5




























Original line number
Diff line number
Diff line








@@ -122,8 +122,6 @@ public class ActivityManager {





























    private static int gMaxRecentTasks = -1;





























    private static final int NUM_ALLOWED_PIP_ACTIONS = 3;





























    private final Context mContext;































    private static volatile boolean sSystemReady = false;










@@ -1127,11 +1125,15 @@ public class ActivityManager {













    }































    /**













     * Return the maximum number of actions that will be displayed in the picture-in-picture UI when













     * the user interacts with the activity currently in picture-in-picture mode.













     * Return the number of actions that will be displayed in the picture-in-picture UI when the













     * user interacts with the activity currently in picture-in-picture mode. This number may change













     * if the global configuration changes (ie. if the device is plugged into an external display).













     *













     * TO BE REMOVED















     */













    @Deprecated















    public static int getMaxNumPictureInPictureActions() {













        return NUM_ALLOWED_PIP_ACTIONS;













        return 3;















    }































    /**