From f998202963cd8330c8914ad5b144e65df37ad41b Mon Sep 17 00:00:00 2001 From: Galia Peycheva Date: Mon, 14 Feb 2022 15:01:31 +0100 Subject: [PATCH] Add API to add title and subtitle to the PIP. On TV information about the PIP is to be shown in the dashboard and via a card in the launcher. The app should be able to provide information for this in the form of a title and subtitle if they want to. Bug: 204173025 Test: atest PinnedStackTests#testTitleIsSet Test: atest PinnedStackTests#testSubtitleIsSet Change-Id: I805e010bad177215627f2a4876cd7bd7e0bd2314 --- core/api/current.txt | 2 + core/api/test-current.txt | 2 + .../android/app/PictureInPictureParams.java | 129 ++++++++++++++++-- 3 files changed, 125 insertions(+), 8 deletions(-) diff --git a/core/api/current.txt b/core/api/current.txt index ff0351a5a4fdc..386b7cfccb870 100644 --- a/core/api/current.txt +++ b/core/api/current.txt @@ -6639,6 +6639,8 @@ package android.app { method @NonNull public android.app.PictureInPictureParams.Builder setExpandedAspectRatio(@Nullable android.util.Rational); method @NonNull public android.app.PictureInPictureParams.Builder setSeamlessResizeEnabled(boolean); method public android.app.PictureInPictureParams.Builder setSourceRectHint(android.graphics.Rect); + method @NonNull public android.app.PictureInPictureParams.Builder setSubtitle(@Nullable CharSequence); + method @NonNull public android.app.PictureInPictureParams.Builder setTitle(@Nullable CharSequence); } public final class PictureInPictureUiState implements android.os.Parcelable { diff --git a/core/api/test-current.txt b/core/api/test-current.txt index 239bba560aa96..f95515a381fef 100644 --- a/core/api/test-current.txt +++ b/core/api/test-current.txt @@ -356,6 +356,8 @@ package android.app { method public float getAspectRatio(); method public float getExpandedAspectRatio(); method public android.graphics.Rect getSourceRectHint(); + method @Nullable public CharSequence getSubtitle(); + method @Nullable public CharSequence getTitle(); method public boolean isSeamlessResizeEnabled(); } diff --git a/core/java/android/app/PictureInPictureParams.java b/core/java/android/app/PictureInPictureParams.java index 18343fddf5d3b..0a74bba8fee3e 100644 --- a/core/java/android/app/PictureInPictureParams.java +++ b/core/java/android/app/PictureInPictureParams.java @@ -57,13 +57,16 @@ public final class PictureInPictureParams implements Parcelable { private Boolean mSeamlessResizeEnabled; + private CharSequence mTitle; + + private CharSequence mSubtitle; + /** * Sets the aspect ratio. This aspect ratio is defined as the desired width / height, and * does not change upon device rotation. * * @param aspectRatio the new aspect ratio for the activity in picture-in-picture, must be - * between 2.39:1 and 1:2.39 (inclusive). - * + * between 2.39:1 and 1:2.39 (inclusive). * @return this builder instance. */ public Builder setAspectRatio(Rational aspectRatio) { @@ -167,6 +170,36 @@ public final class PictureInPictureParams implements Parcelable { return this; } + /** + * Sets a title for the picture-in-picture window, which may be displayed by the system to + * give the user information about what this PIP is generally being used for. + * + * @param title General information about the PIP content + * @return this builder instance. + */ + @NonNull + public Builder setTitle(@Nullable CharSequence title) { + mTitle = title; + return this; + } + + /** + * Sets a subtitle for the picture-in-picture window, which may be displayed by the system + * to give the user more detailed information about what this PIP is displaying.
+ * + * Setting a title via {@link PictureInPictureParams.Builder#setTitle(CharSequence)} should + * be prioritized. + * + * @param subtitle Details about the PIP content. + * @return this builder instance + */ + @NonNull + public Builder setSubtitle(@Nullable CharSequence subtitle) { + mSubtitle = subtitle; + return this; + } + + /** * @return an immutable {@link PictureInPictureParams} to be used when entering or updating * the activity in picture-in-picture. @@ -177,7 +210,7 @@ public final class PictureInPictureParams implements Parcelable { public PictureInPictureParams build() { PictureInPictureParams params = new PictureInPictureParams(mAspectRatio, mExpandedAspectRatio, mUserActions, - mSourceRectHint, mAutoEnterEnabled, mSeamlessResizeEnabled); + mSourceRectHint, mAutoEnterEnabled, mSeamlessResizeEnabled, mTitle, mSubtitle); return params; } } @@ -221,6 +254,18 @@ public final class PictureInPictureParams implements Parcelable { */ private Boolean mSeamlessResizeEnabled; + /** + * Title of the picture-in-picture window to be displayed to the user. + */ + @Nullable + private CharSequence mTitle; + + /** + * Subtitle for the picture-in-picture window to be displayed to the user. + */ + @Nullable + private CharSequence mSubtitle; + /** {@hide} */ PictureInPictureParams() { } @@ -242,18 +287,26 @@ public final class PictureInPictureParams implements Parcelable { if (in.readInt() != 0) { mSeamlessResizeEnabled = in.readBoolean(); } + if (in.readInt() != 0) { + mTitle = in.readCharSequence(); + } + if (in.readInt() != 0) { + mSubtitle = in.readCharSequence(); + } } /** {@hide} */ PictureInPictureParams(Rational aspectRatio, Rational expandedAspectRatio, List actions, Rect sourceRectHint, Boolean autoEnterEnabled, - Boolean seamlessResizeEnabled) { + Boolean seamlessResizeEnabled, CharSequence title, CharSequence subtitle) { mAspectRatio = aspectRatio; mExpandedAspectRatio = expandedAspectRatio; mUserActions = actions; mSourceRectHint = sourceRectHint; mAutoEnterEnabled = autoEnterEnabled; mSeamlessResizeEnabled = seamlessResizeEnabled; + mTitle = title; + mSubtitle = subtitle; } /** @@ -263,7 +316,8 @@ public final class PictureInPictureParams implements Parcelable { public PictureInPictureParams(PictureInPictureParams other) { this(other.mAspectRatio, other.mExpandedAspectRatio, other.mUserActions, other.hasSourceBoundsHint() ? new Rect(other.getSourceRectHint()) : null, - other.mAutoEnterEnabled, other.mSeamlessResizeEnabled); + other.mAutoEnterEnabled, other.mSeamlessResizeEnabled, other.mTitle, + other.mSubtitle); } /** @@ -290,6 +344,12 @@ public final class PictureInPictureParams implements Parcelable { if (otherArgs.mSeamlessResizeEnabled != null) { mSeamlessResizeEnabled = otherArgs.mSeamlessResizeEnabled; } + if (otherArgs.hasSetTitle()) { + mTitle = otherArgs.mTitle; + } + if (otherArgs.hasSetSubtitle()) { + mSubtitle = otherArgs.mSubtitle; + } } /** @@ -398,6 +458,42 @@ public final class PictureInPictureParams implements Parcelable { return mSeamlessResizeEnabled == null ? true : mSeamlessResizeEnabled; } + /** + * @return whether a title was set. + * @hide + */ + public boolean hasSetTitle() { + return mTitle != null; + } + + /** + * @return title of the pip. + * @hide + */ + @TestApi + @Nullable + public CharSequence getTitle() { + return mTitle; + } + + /** + * @return whether a subtitle was set. + * @hide + */ + public boolean hasSetSubtitle() { + return mSubtitle != null; + } + + /** + * @return subtitle of the pip. + * @hide + */ + @TestApi + @Nullable + public CharSequence getSubtitle() { + return mSubtitle; + } + /** * @return True if no parameters are set * @hide @@ -405,7 +501,8 @@ public final class PictureInPictureParams implements Parcelable { public boolean empty() { return !hasSourceBoundsHint() && !hasSetActions() && !hasSetAspectRatio() && !hasSetExpandedAspectRatio() && mAutoEnterEnabled != null - && mSeamlessResizeEnabled != null; + && mSeamlessResizeEnabled != null && !hasSetTitle() + && !hasSetSubtitle(); } @Override @@ -418,13 +515,15 @@ public final class PictureInPictureParams implements Parcelable { && Objects.equals(mAspectRatio, that.mAspectRatio) && Objects.equals(mExpandedAspectRatio, that.mExpandedAspectRatio) && Objects.equals(mUserActions, that.mUserActions) - && Objects.equals(mSourceRectHint, that.mSourceRectHint); + && Objects.equals(mSourceRectHint, that.mSourceRectHint) + && Objects.equals(mTitle, that.mTitle) + && Objects.equals(mSubtitle, that.mSubtitle); } @Override public int hashCode() { return Objects.hash(mAspectRatio, mExpandedAspectRatio, mUserActions, mSourceRectHint, - mAutoEnterEnabled, mSeamlessResizeEnabled); + mAutoEnterEnabled, mSeamlessResizeEnabled, mTitle, mSubtitle); } @Override @@ -460,6 +559,18 @@ public final class PictureInPictureParams implements Parcelable { } else { out.writeInt(0); } + if (mTitle != null) { + out.writeInt(1); + out.writeCharSequence(mTitle); + } else { + out.writeInt(0); + } + if (mSubtitle != null) { + out.writeInt(1); + out.writeCharSequence(mSubtitle); + } else { + out.writeInt(0); + } } private void writeRationalToParcel(Rational rational, Parcel out) { @@ -488,6 +599,8 @@ public final class PictureInPictureParams implements Parcelable { + " hasSetActions=" + hasSetActions() + " isAutoPipEnabled=" + isAutoEnterEnabled() + " isSeamlessResizeEnabled=" + isSeamlessResizeEnabled() + + " title=" + getTitle() + + " subtitle=" + getSubtitle() + ")"; }