Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Enhance PinItemRequest javadoc" into oc-dev

Browse Source 
am: 5838563e93

Change-Id: Ie0233a300fe9dc046117602a891679e5f1b00a98
This commit is contained in:
Makoto Onuki
2017-04-17 21:03:32 +00:00
committed by android-build-merger
parent 88a9bd73bb 5838563e93
commit deda224f14
1 changed files with 63 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
core/java/android/content/pm/LauncherApps.java
View File

@@ -22,6 +22,8 @@ import android.annotation.Nullable;
import android.annotation.SdkConstant;
import android.annotation.SdkConstant.SdkConstantType;
import android.annotation.TestApi;
import android.app.PendingIntent;
import android.appwidget.AppWidgetManager;
import android.appwidget.AppWidgetProviderInfo;
import android.content.ActivityNotFoundException;
import android.content.ComponentName;
@@ -1279,15 +1281,34 @@ public class LauncherApps {
* an {@link #ACTION_CONFIRM_PIN_SHORTCUT} or {@link #ACTION_CONFIRM_PIN_APPWIDGET} intent
* respectively to the default launcher app.
*
* <p>Note the launcher may receive a request to pin a shortcut that is already pinned, because
* the user may actually want to have multiple icons of the same shortcut on the launcher.
* The launcher can tell this case by calling {@link ShortcutInfo#isPinned()} on the shortcut
* returned by {@link #getShortcutInfo()}. In this case, calling {@link #accept()} is optional;
* even if the launcher does not call it, the shortcut is already pinned. Also in this case,
* the {@code options} argument to {@link #accept(Bundle)} will be ignored.
* <h3>Request of the {@link #REQUEST_TYPE_SHORTCUT} type.
*
* <p>For AppWidget pin requests launcher should send back the appwidget id as an extra for
* {@link #accept(Bundle)} as {@link android.appwidget.AppWidgetManager#EXTRA_APPWIDGET_ID}.
* <p>A {@link #REQUEST_TYPE_SHORTCUT} request represents a request to pin a
* {@link ShortcutInfo}. If the launcher accepts a request, call {@link #accept()},
* or {@link #accept(Bundle)} with a null or empty Bundle. No options are defined for
* pin-shortcuts requests.
*
* <p>{@link #getShortcutInfo()} always returns a non-null {@link ShortcutInfo} for this type.
*
* <p>The launcher may receive a request with a {@link ShortcutInfo} that is already pinned, in
* which case {@link ShortcutInfo#isPinned()} returns true. This means the user wants to create
* another pinned shortcut for a shortcut that's already pinned. If the launcher accepts it,
* {@link #accept()} must still be called even though the shortcut is already pinned, and
* create a new pinned shortcut icon for it.
*
* <p>See also {@link ShortcutManager} for more details.
*
* <h3>Request of the {@link #REQUEST_TYPE_APPWIDGET} type.
*
* <p>A {@link #REQUEST_TYPE_SHORTCUT} request represents a request to pin a
* an AppWidget. If the launcher accepts a request, call {@link #accept(Bundle)} with
* the appwidget integer ID set to the
* {@link android.appwidget.AppWidgetManager#EXTRA_APPWIDGET_ID} extra.
*
* <p>{@link #getAppWidgetProviderInfo(Context)} always returns a non-null
* {@link AppWidgetProviderInfo} for this type.
*
* <p>See also {@link AppWidgetManager} for more details.
*
* @see #EXTRA_PIN_ITEM_REQUEST
* @see #getPinItemRequest(Intent)
@@ -1317,8 +1338,9 @@ public class LauncherApps {
}
/**
* Represents the type of a request. For now {@link #REQUEST_TYPE_SHORTCUT} is the only
* valid type.
* Represents the type of a request, which is one of the {@code REQUEST_TYPE_} constants.
*
* @return one of the {@code REQUEST_TYPE_} constants.
*/
@RequestType
public int getRequestType() {
@@ -1326,8 +1348,12 @@ public class LauncherApps {
}
/**
* {@link ShortcutInfo} sent by the requesting app. Always non-null for a
* {@link #REQUEST_TYPE_SHORTCUT} request.
* {@link ShortcutInfo} sent by the requesting app.
* Always non-null for a {@link #REQUEST_TYPE_SHORTCUT} request, and always null for a
* different request type.
*
* @return requested {@link ShortcutInfo} when a request is of the
* {@link #REQUEST_TYPE_SHORTCUT} type. Null otherwise.
*/
@Nullable
public ShortcutInfo getShortcutInfo() {
@@ -1339,8 +1365,12 @@ public class LauncherApps {
}
/**
* {@link AppWidgetProviderInfo} sent by the requesting app. Always non-null for a
* {@link #REQUEST_TYPE_APPWIDGET} request.
* {@link AppWidgetProviderInfo} sent by the requesting app.
* Always non-null for a {@link #REQUEST_TYPE_APPWIDGET} request, and always null for a
* different request type.
*
* @return requested {@link AppWidgetProviderInfo} when a request is of the
* {@link #REQUEST_TYPE_APPWIDGET} type. Null otherwise.
*/
@Nullable
public AppWidgetProviderInfo getAppWidgetProviderInfo(Context context) {
@@ -1358,6 +1388,11 @@ public class LauncherApps {
/**
* Any extras sent by the requesting app.
*
* @return For a shortcut request, this method always return null. For an AppWidget
* request, this method returns the extras passed to the
* {@link android.appwidget.AppWidgetManager#requestPinAppWidget(
* ComponentName, Bundle, PendingIntent)} API. See {@link AppWidgetManager} for details.
*/
@Nullable
public Bundle getExtras() {
@@ -1369,8 +1404,9 @@ public class LauncherApps {
}
/**
* Return {@code TRUE} if a request is valid -- i.e. {@link #accept(Bundle)} has not been
* called yet.
* Return whether a request is still valid.
*
* @return {@code TRUE} if a request is valid and {@link #accept(Bundle)} may be called.
*/
public boolean isValid() {
try {
@@ -1382,6 +1418,12 @@ public class LauncherApps {
/**
* Called by the receiving launcher app when the user accepts the request.
*
* @param options must be set for a {@link #REQUEST_TYPE_APPWIDGET} request.
*
* @return {@code TRUE} if the shortcut or the AppWidget has actually been pinned.
* {@code FALSE} if the item hasn't been pinned, for example, because the request had
* already been canceled, in which case the launcher must not pin the requested item.
*/
public boolean accept(@Nullable Bundle options) {
try {
@@ -1392,7 +1434,11 @@ public class LauncherApps {
}
/**
* Same as as {@link #accept(Bundle)} with no options.
* Called by the receiving launcher app when the user accepts the request, with no options.
*
* @return {@code TRUE} if the shortcut or the AppWidget has actually been pinned.
* {@code FALSE} if the item hasn't been pinned, for example, because the request had
* already been canceled, in which case the launcher must not pin the requested item.
*/
public boolean accept() {
return accept(/* options= */ null);