Chooser content toggling API.
Bug: 302691505
Flag: ACONFIG android.service.chooser.chooser_payload_toggling
DEVELOPMENT
Test: presubmits (this CL just defines constants)
Change-Id: I4d905a7db4fbc212c4456a1e1bcf76d266caafb2
diff --git a/core/api/current.txt b/core/api/current.txt
index acb4146..1395222 100644
--- a/core/api/current.txt
+++ b/core/api/current.txt
@@ -11279,8 +11279,10 @@
field public static final String EXTRA_CHANGED_COMPONENT_NAME_LIST = "android.intent.extra.changed_component_name_list";
field public static final String EXTRA_CHANGED_PACKAGE_LIST = "android.intent.extra.changed_package_list";
field public static final String EXTRA_CHANGED_UID_LIST = "android.intent.extra.changed_uid_list";
+ field @FlaggedApi("android.service.chooser.chooser_payload_toggling") public static final String EXTRA_CHOOSER_ADDITIONAL_CONTENT_URI = "android.intent.extra.CHOOSER_ADDITIONAL_CONTENT_URI";
field @FlaggedApi("android.service.chooser.chooser_album_text") public static final String EXTRA_CHOOSER_CONTENT_TYPE_HINT = "android.intent.extra.CHOOSER_CONTENT_TYPE_HINT";
field public static final String EXTRA_CHOOSER_CUSTOM_ACTIONS = "android.intent.extra.CHOOSER_CUSTOM_ACTIONS";
+ field @FlaggedApi("android.service.chooser.chooser_payload_toggling") public static final String EXTRA_CHOOSER_FOCUSED_ITEM_POSITION = "android.intent.extra.CHOOSER_FOCUSED_ITEM_POSITION";
field public static final String EXTRA_CHOOSER_MODIFY_SHARE_ACTION = "android.intent.extra.CHOOSER_MODIFY_SHARE_ACTION";
field public static final String EXTRA_CHOOSER_REFINEMENT_INTENT_SENDER = "android.intent.extra.CHOOSER_REFINEMENT_INTENT_SENDER";
field public static final String EXTRA_CHOOSER_TARGETS = "android.intent.extra.CHOOSER_TARGETS";
@@ -40096,6 +40098,21 @@
package android.service.chooser {
+ @FlaggedApi("android.service.chooser.chooser_payload_toggling") public interface AdditionalContentContract {
+ }
+
+ public static interface AdditionalContentContract.Columns {
+ field public static final String URI = "uri";
+ }
+
+ public static interface AdditionalContentContract.CursorExtraKeys {
+ field public static final String POSITION = "position";
+ }
+
+ public static interface AdditionalContentContract.MethodNames {
+ field public static final String ON_SELECTION_CHANGED = "onSelectionChanged";
+ }
+
public final class ChooserAction implements android.os.Parcelable {
method public int describeContents();
method @NonNull public android.app.PendingIntent getAction();
diff --git a/core/java/android/content/Intent.java b/core/java/android/content/Intent.java
index 08871d4..416cb59 100644
--- a/core/java/android/content/Intent.java
+++ b/core/java/android/content/Intent.java
@@ -55,6 +55,7 @@
import android.os.Build;
import android.os.Bundle;
import android.os.BundleMerger;
+import android.os.CancellationSignal;
import android.os.IBinder;
import android.os.IncidentManager;
import android.os.Parcel;
@@ -72,6 +73,7 @@
import android.provider.DocumentsProvider;
import android.provider.MediaStore;
import android.provider.OpenableColumns;
+import android.service.chooser.AdditionalContentContract;
import android.service.chooser.ChooserAction;
import android.telecom.PhoneAccount;
import android.telecom.TelecomManager;
@@ -6064,6 +6066,62 @@
public static final int CHOOSER_CONTENT_TYPE_ALBUM = 1;
/**
+ * Optional argument used to provide a {@link ContentProvider} {@link Uri} to an
+ * {@link #ACTION_CHOOSER} Intent which allows additional toggleable items to be included
+ * in the sharing UI.
+ * <p>
+ * For example, this could be used to show photos being shared in the context of the user's
+ * entire photo roll, with the option to change the set of photos being shared.
+ * <p>
+ * When this is provided in an {@link #ACTION_CHOOSER} Intent with an {@link #ACTION_SEND} or
+ * {@link #ACTION_SEND_MULTIPLE} target Intent, the sharesheet will query (see
+ * {@link ContentProvider#query(Uri, String[], Bundle, CancellationSignal)}) this URI to
+ * retrieve a set of additional items available for selection. The set of items returned by the
+ * content provider is expected to contain all the items from the {@link #EXTRA_STREAM}
+ * argument, in their relative order, which will be marked as selected. The URI's authority
+ * must be different from any shared items URI provided in {@link #EXTRA_STREAM} or returned by
+ * the provider.
+ *
+ * <p>The {@link Bundle} argument of the
+ * {@link ContentProvider#query(Uri, String[], Bundle, CancellationSignal)}
+ * method will contains the original intent Chooser has been launched with under the
+ * {@link #EXTRA_INTENT} key as a context for the current sharing session. The returned
+ * {@link android.database.Cursor} should contain
+ * {@link android.service.chooser.AdditionalContentContract.Columns#URI} column for the item URI
+ * and, optionally, {@link AdditionalContentContract.CursorExtraKeys#POSITION} extra that
+ * specifies the cursor starting position; the item at this position is expected to match the
+ * item specified by {@link #EXTRA_CHOOSER_FOCUSED_ITEM_POSITION}.</p>
+ *
+ * <p>When the user makes a selection change,
+ * {@link ContentProvider#call(String, String, Bundle)} method will be invoked with the "method"
+ * argument set to
+ * {@link android.service.chooser.AdditionalContentContract.MethodNames#ON_SELECTION_CHANGED},
+ * the "arg" argument set to this argument's value, and the "extras" {@link Bundle} argument
+ * containing {@link #EXTRA_INTENT} key containing the original intent Chooser has been launched
+ * with but with the modified target intent --Chooser will modify the target intent according to
+ * the selection changes made by the user.
+ * Applications may implement this method to change any of the following Chooser arguments by
+ * returning new values in the result bundle:
+ * {@link #EXTRA_CHOOSER_TARGETS}, {@link #EXTRA_ALTERNATE_INTENTS},
+ * {@link #EXTRA_CHOOSER_CUSTOM_ACTIONS},
+ * {@link #EXTRA_CHOOSER_MODIFY_SHARE_ACTION},
+ * {@link #EXTRA_CHOOSER_REFINEMENT_INTENT_SENDER}.</p>
+ */
+ @FlaggedApi(android.service.chooser.Flags.FLAG_CHOOSER_PAYLOAD_TOGGLING)
+ public static final String EXTRA_CHOOSER_ADDITIONAL_CONTENT_URI =
+ "android.intent.extra.CHOOSER_ADDITIONAL_CONTENT_URI";
+
+ /**
+ * Optional argument to be used with {@link #EXTRA_CHOOSER_ADDITIONAL_CONTENT_URI}, used in
+ * combination with {@link #EXTRA_CHOOSER_ADDITIONAL_CONTENT_URI}.
+ * An integer, zero-based index into {@link #EXTRA_STREAM} argument indicating the item that
+ * should be focused by the Chooser in preview.
+ */
+ @FlaggedApi(android.service.chooser.Flags.FLAG_CHOOSER_PAYLOAD_TOGGLING)
+ public static final String EXTRA_CHOOSER_FOCUSED_ITEM_POSITION =
+ "android.intent.extra.CHOOSER_FOCUSED_ITEM_POSITION";
+
+ /**
* An {@code ArrayList} of {@code String} annotations describing content for
* {@link #ACTION_CHOOSER}.
*
diff --git a/core/java/android/service/chooser/AdditionalContentContract.java b/core/java/android/service/chooser/AdditionalContentContract.java
new file mode 100644
index 0000000..f679e8a
--- /dev/null
+++ b/core/java/android/service/chooser/AdditionalContentContract.java
@@ -0,0 +1,60 @@
+/*
+ * Copyright 2024 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.service.chooser;
+
+import android.annotation.FlaggedApi;
+
+/**
+ * Specifies constants used by Chooser when interacting with the additional content provider,
+ * see {@link android.content.Intent#EXTRA_CHOOSER_ADDITIONAL_CONTENT_URI}.
+ */
+@FlaggedApi(android.service.chooser.Flags.FLAG_CHOOSER_PAYLOAD_TOGGLING)
+public interface AdditionalContentContract {
+
+ interface Columns {
+ /**
+ * Content URI for this item.
+ * <p>
+ * Note that this content URI must have a different authority from the content provided
+ * given in {@link android.content.Intent#EXTRA_CHOOSER_ADDITIONAL_CONTENT_URI}.
+ */
+ String URI = "uri";
+ }
+
+ /**
+ * Constants for {@link android.database.Cursor#getExtras} keys.
+ */
+ interface CursorExtraKeys {
+ /**
+ * An integer, zero-based cursor position that corresponds to the URI specified
+ * with the {@link android.content.Intent#EXTRA_CHOOSER_FOCUSED_ITEM_POSITION} index into
+ * the @link android.content.Intent#EXTRA_STREAM} array.
+ */
+ String POSITION = "position";
+ }
+
+ /**
+ * Constants for method names used with {@link android.content.ContentResolver#call} method.
+ */
+ interface MethodNames {
+ /**
+ * A method name Chooser is using to notify the sharing app about a shared items selection
+ * change.
+ */
+ String ON_SELECTION_CHANGED = "onSelectionChanged";
+ }
+}