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;
* 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)
}
/**
- * 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() {
}
/**
- * {@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() {
}
/**
- * {@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) {
/**
* 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() {
}
/**
- * 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 {
/**
* 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 {
}
/**
- * 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);
OSDN Git Service
