Merge "Changing app widget "extras" to "options" and another small API Review issue" into jb-dev

Author: Adam Cohen

api/current.txt

@@ -4317,15 +4317,15 @@ package android.appwidget {
     method protected void prepareView(android.view.View);
     method public void setAppWidget(int, android.appwidget.AppWidgetProviderInfo);
     method public void updateAppWidget(android.widget.RemoteViews);
-    method public void updateAppWidgetExtras(android.os.Bundle);
+    method public void updateAppWidgetOptions(android.os.Bundle);
     method public void updateAppWidgetSize(android.os.Bundle, int, int, int, int);
   }
 
   public class AppWidgetManager {
     method public boolean bindAppWidgetIdIfAllowed(int, android.content.ComponentName);
-    method public android.os.Bundle getAppWidgetExtras(int);
     method public int[] getAppWidgetIds(android.content.ComponentName);
     method public android.appwidget.AppWidgetProviderInfo getAppWidgetInfo(int);
+    method public android.os.Bundle getAppWidgetOptions(int);
     method public java.util.List<android.appwidget.AppWidgetProviderInfo> getInstalledProviders();
     method public static android.appwidget.AppWidgetManager getInstance(android.content.Context);
     method public void notifyAppWidgetViewDataChanged(int[], int);
@@ -4335,32 +4335,32 @@ package android.appwidget {
     method public void updateAppWidget(int[], android.widget.RemoteViews);
     method public void updateAppWidget(int, android.widget.RemoteViews);
     method public void updateAppWidget(android.content.ComponentName, android.widget.RemoteViews);
-    method public void updateAppWidgetExtras(int, android.os.Bundle);
+    method public void updateAppWidgetOptions(int, android.os.Bundle);
     field public static final java.lang.String ACTION_APPWIDGET_BIND = "android.appwidget.action.APPWIDGET_BIND";
     field public static final java.lang.String ACTION_APPWIDGET_CONFIGURE = "android.appwidget.action.APPWIDGET_CONFIGURE";
     field public static final java.lang.String ACTION_APPWIDGET_DELETED = "android.appwidget.action.APPWIDGET_DELETED";
     field public static final java.lang.String ACTION_APPWIDGET_DISABLED = "android.appwidget.action.APPWIDGET_DISABLED";
     field public static final java.lang.String ACTION_APPWIDGET_ENABLED = "android.appwidget.action.APPWIDGET_ENABLED";
-    field public static final java.lang.String ACTION_APPWIDGET_EXTRAS_CHANGED = "android.appwidget.action.APPWIDGET_UPDATE_EXTRAS";
+    field public static final java.lang.String ACTION_APPWIDGET_OPTIONS_CHANGED = "android.appwidget.action.APPWIDGET_UPDATE_OPTIONS";
     field public static final java.lang.String ACTION_APPWIDGET_PICK = "android.appwidget.action.APPWIDGET_PICK";
     field public static final java.lang.String ACTION_APPWIDGET_UPDATE = "android.appwidget.action.APPWIDGET_UPDATE";
-    field public static final java.lang.String EXTRA_APPWIDGET_EXTRAS = "appWidgetExtras";
     field public static final java.lang.String EXTRA_APPWIDGET_ID = "appWidgetId";
     field public static final java.lang.String EXTRA_APPWIDGET_IDS = "appWidgetIds";
-    field public static final java.lang.String EXTRA_APPWIDGET_MAX_HEIGHT = "appWidgetMaxHeight";
-    field public static final java.lang.String EXTRA_APPWIDGET_MAX_WIDTH = "appWidgetMaxWidth";
-    field public static final java.lang.String EXTRA_APPWIDGET_MIN_HEIGHT = "appWidgetMinHeight";
-    field public static final java.lang.String EXTRA_APPWIDGET_MIN_WIDTH = "appWidgetMinWidth";
+    field public static final java.lang.String EXTRA_APPWIDGET_OPTIONS = "appWidgetOptions";
     field public static final java.lang.String EXTRA_APPWIDGET_PROVIDER = "appWidgetProvider";
     field public static final java.lang.String EXTRA_CUSTOM_EXTRAS = "customExtras";
     field public static final java.lang.String EXTRA_CUSTOM_INFO = "customInfo";
     field public static final int INVALID_APPWIDGET_ID = 0; // 0x0
     field public static final java.lang.String META_DATA_APPWIDGET_PROVIDER = "android.appwidget.provider";
+    field public static final java.lang.String OPTION_APPWIDGET_MAX_HEIGHT = "appWidgetMaxHeight";
+    field public static final java.lang.String OPTION_APPWIDGET_MAX_WIDTH = "appWidgetMaxWidth";
+    field public static final java.lang.String OPTION_APPWIDGET_MIN_HEIGHT = "appWidgetMinHeight";
+    field public static final java.lang.String OPTION_APPWIDGET_MIN_WIDTH = "appWidgetMinWidth";
   }
 
   public class AppWidgetProvider extends android.content.BroadcastReceiver {
     ctor public AppWidgetProvider();
-    method public void onAppWidgetExtrasChanged(android.content.Context, android.appwidget.AppWidgetManager, int, android.os.Bundle);
+    method public void onAppWidgetOptionsChanged(android.content.Context, android.appwidget.AppWidgetManager, int, android.os.Bundle);
     method public void onDeleted(android.content.Context, int[]);
     method public void onDisabled(android.content.Context);
     method public void onEnabled(android.content.Context);

core/java/android/appwidget/AppWidgetHostView.java

@@ -210,36 +210,37 @@ protected void dispatchRestoreInstanceState(SparseArray<Parcelable> container) {
     /**
      * Provide guidance about the size of this widget to the AppWidgetManager. This information
      * gets embedded into the AppWidgetExtras and causes a callback to the AppWidgetProvider.
-     * @see AppWidgetProvider#onAppWidgetExtrasChanged(Context, AppWidgetManager, int, Bundle)
+     * @see AppWidgetProvider#onAppWidgetOptionsChanged(Context, AppWidgetManager, int, Bundle)
      *
-     * @param extras The bundle of extra information, in addition to the size information
+     * @param options The bundle of options, in addition to the size information,
      *          can be null.
      * @param minWidth The minimum width that the widget will be displayed at.
      * @param minHeight The maximum height that the widget will be displayed at.
-     * @param maxWidth The maximum height that the widget will be displayed at.
+     * @param maxWidth The maximum width that the widget will be displayed at.
+     * @param maxHeight The maximum height that the widget will be displayed at.
      *
      */
-    public void updateAppWidgetSize(Bundle extras, int minWidth, int minHeight, int maxWidth,
+    public void updateAppWidgetSize(Bundle options, int minWidth, int minHeight, int maxWidth,
             int maxHeight) {
-        if (extras == null) {
-            extras = new Bundle();
+        if (options == null) {
+            options = new Bundle();
         }
-        extras.putInt(AppWidgetManager.EXTRA_APPWIDGET_MIN_WIDTH, minWidth);
-        extras.putInt(AppWidgetManager.EXTRA_APPWIDGET_MIN_HEIGHT, minHeight);
-        extras.putInt(AppWidgetManager.EXTRA_APPWIDGET_MAX_WIDTH, maxWidth);
-        extras.putInt(AppWidgetManager.EXTRA_APPWIDGET_MAX_HEIGHT, maxHeight);
-        updateAppWidgetExtras(extras);
+        options.putInt(AppWidgetManager.OPTION_APPWIDGET_MIN_WIDTH, minWidth);
+        options.putInt(AppWidgetManager.OPTION_APPWIDGET_MIN_HEIGHT, minHeight);
+        options.putInt(AppWidgetManager.OPTION_APPWIDGET_MAX_WIDTH, maxWidth);
+        options.putInt(AppWidgetManager.OPTION_APPWIDGET_MAX_HEIGHT, maxHeight);
+        updateAppWidgetOptions(options);
     }
 
     /**
      * Specify some extra information for the widget provider. Causes a callback to the
      * AppWidgetProvider.
-     * @see AppWidgetProvider#onAppWidgetExtrasChanged(Context, AppWidgetManager, int, Bundle)
+     * @see AppWidgetProvider#onAppWidgetOptionsChanged(Context, AppWidgetManager, int, Bundle)
      *
-     * @param extras The bundle of extra information.
+     * @param options The bundle of options information.
      */
-    public void updateAppWidgetExtras(Bundle extras) {
-        AppWidgetManager.getInstance(mContext).updateAppWidgetExtras(mAppWidgetId, extras);
+    public void updateAppWidgetOptions(Bundle options) {
+        AppWidgetManager.getInstance(mContext).updateAppWidgetOptions(mAppWidgetId, options);
     }
 
     /** {@inheritDoc} */

core/java/android/appwidget/AppWidgetManager.java

@@ -152,28 +152,28 @@ public class AppWidgetManager {
     /**
      * An bundle extra that contains the lower bound on the current width, in dips, of a widget instance.
      */
-    public static final String EXTRA_APPWIDGET_MIN_WIDTH = "appWidgetMinWidth";
+    public static final String OPTION_APPWIDGET_MIN_WIDTH = "appWidgetMinWidth";
 
     /**
      * An bundle extra that contains the lower bound on the current height, in dips, of a widget instance.
      */
-    public static final String EXTRA_APPWIDGET_MIN_HEIGHT = "appWidgetMinHeight";
+    public static final String OPTION_APPWIDGET_MIN_HEIGHT = "appWidgetMinHeight";
 
     /**
      * An bundle extra that contains the upper bound on the current width, in dips, of a widget instance.
      */
-    public static final String EXTRA_APPWIDGET_MAX_WIDTH = "appWidgetMaxWidth";
+    public static final String OPTION_APPWIDGET_MAX_WIDTH = "appWidgetMaxWidth";
 
     /**
      * An bundle extra that contains the upper bound on the current width, in dips, of a widget instance.
      */
-    public static final String EXTRA_APPWIDGET_MAX_HEIGHT = "appWidgetMaxHeight";
+    public static final String OPTION_APPWIDGET_MAX_HEIGHT = "appWidgetMaxHeight";
 
     /**
      * An intent extra which points to a bundle of extra information for a particular widget id.
      * In particular this bundle can contain EXTRA_APPWIDGET_WIDTH and EXTRA_APPWIDGET_HEIGHT.
      */
-    public static final String EXTRA_APPWIDGET_EXTRAS = "appWidgetExtras";
+    public static final String EXTRA_APPWIDGET_OPTIONS = "appWidgetOptions";
 
     /**
      * An intent extra that contains multiple appWidgetIds.
@@ -240,7 +240,7 @@ public class AppWidgetManager {
      * @see AppWidgetProvider#onAppWidgetExtrasChanged AppWidgetProvider#onAppWidgetExtrasChanged(
      *      Context context, AppWidgetManager appWidgetManager, int appWidgetId, Bundle newExtras)
      */
-    public static final String ACTION_APPWIDGET_EXTRAS_CHANGED = "android.appwidget.action.APPWIDGET_UPDATE_EXTRAS";
+    public static final String ACTION_APPWIDGET_OPTIONS_CHANGED = "android.appwidget.action.APPWIDGET_UPDATE_OPTIONS";
 
     /**
      * Sent when an instance of an AppWidget is deleted from its host.
@@ -339,14 +339,14 @@ public void updateAppWidget(int[] appWidgetIds, RemoteViews views) {
      * The extras can be used to embed additional information about this widget to be accessed
      * by the associated widget's AppWidgetProvider.
      *
-     * @see #getAppWidgetExtras(int)
+     * @see #getAppWidgetOptions(int)
      *
      * @param appWidgetId    The AppWidget instances for which to set the RemoteViews.
-     * @param extras         The extras to associate with this widget
+     * @param options         The options to associate with this widget
      */
-    public void updateAppWidgetExtras(int appWidgetId, Bundle extras) {
+    public void updateAppWidgetOptions(int appWidgetId, Bundle options) {
         try {
-            sService.updateAppWidgetExtras(appWidgetId, extras);
+            sService.updateAppWidgetOptions(appWidgetId, options);
         }
         catch (RemoteException e) {
             throw new RuntimeException("system server dead?", e);
@@ -359,14 +359,14 @@ public void updateAppWidgetExtras(int appWidgetId, Bundle extras) {
      * The extras can be used to embed additional information about this widget to be accessed
      * by the associated widget's AppWidgetProvider.
      *
-     * @see #updateAppWidgetExtras(int, Bundle)
+     * @see #updateAppWidgetOptions(int, Bundle)
      *
      * @param appWidgetId     The AppWidget instances for which to set the RemoteViews.
-     * @return                The extras associated with the given widget instance.
+     * @return                The options associated with the given widget instance.
      */
-    public Bundle getAppWidgetExtras(int appWidgetId) {
+    public Bundle getAppWidgetOptions(int appWidgetId) {
         try {
-            return sService.getAppWidgetExtras(appWidgetId);
+            return sService.getAppWidgetOptions(appWidgetId);
         }
         catch (RemoteException e) {
             throw new RuntimeException("system server dead?", e);

core/java/android/appwidget/AppWidgetProvider.java

@@ -74,13 +74,13 @@ else if (AppWidgetManager.ACTION_APPWIDGET_DELETED.equals(action)) {
                 this.onDeleted(context, new int[] { appWidgetId });
             }
         }
-        else if (AppWidgetManager.ACTION_APPWIDGET_EXTRAS_CHANGED.equals(action)) {
+        else if (AppWidgetManager.ACTION_APPWIDGET_OPTIONS_CHANGED.equals(action)) {
             Bundle extras = intent.getExtras();
             if (extras != null && extras.containsKey(AppWidgetManager.EXTRA_APPWIDGET_ID)
-                    && extras.containsKey(AppWidgetManager.EXTRA_APPWIDGET_EXTRAS)) {
+                    && extras.containsKey(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS)) {
                 int appWidgetId = extras.getInt(AppWidgetManager.EXTRA_APPWIDGET_ID);
-                Bundle widgetExtras = extras.getBundle(AppWidgetManager.EXTRA_APPWIDGET_EXTRAS);
-                this.onAppWidgetExtrasChanged(context, AppWidgetManager.getInstance(context),
+                Bundle widgetExtras = extras.getBundle(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS);
+                this.onAppWidgetOptionsChanged(context, AppWidgetManager.getInstance(context),
                         appWidgetId, widgetExtras);
             }
         }
@@ -114,7 +114,7 @@ public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] a
     }
 
     /**
-     * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_EXTRAS_CHANGED}
+     * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_OPTIONS_CHANGED}
      * broadcast when this widget has been layed out at a new size.
      *
      * {@more}
@@ -124,12 +124,12 @@ public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] a
      * @param appWidgetManager A {@link AppWidgetManager} object you can call {@link
      *                  AppWidgetManager#updateAppWidget} on.
      * @param appWidgetId The appWidgetId of the widget who's size changed.
-     * @param newExtras The appWidgetId of the widget who's size changed.
+     * @param newOptions The appWidgetId of the widget who's size changed.
      *
-     * @see AppWidgetManager#ACTION_APPWIDGET_EXTRAS_CHANGED
+     * @see AppWidgetManager#ACTION_APPWIDGET_OPTIONS_CHANGED
      */
-    public void onAppWidgetExtrasChanged(Context context, AppWidgetManager appWidgetManager,
-            int appWidgetId, Bundle newExtras) {
+    public void onAppWidgetOptionsChanged(Context context, AppWidgetManager appWidgetManager,
+            int appWidgetId, Bundle newOptions) {
     }
 
     /**

core/java/com/android/internal/appwidget/IAppWidgetService.aidl

@@ -43,8 +43,8 @@ interface IAppWidgetService {
     // for AppWidgetManager
     //
     void updateAppWidgetIds(in int[] appWidgetIds, in RemoteViews views);
-    void updateAppWidgetExtras(int appWidgetId, in Bundle extras);
-    Bundle getAppWidgetExtras(int appWidgetId);
+    void updateAppWidgetOptions(int appWidgetId, in Bundle extras);
+    Bundle getAppWidgetOptions(int appWidgetId);
     void partiallyUpdateAppWidgetIds(in int[] appWidgetIds, in RemoteViews views);
     void updateAppWidgetProvider(in ComponentName provider, in RemoteViews views);
     void notifyAppWidgetViewDataChanged(in int[] appWidgetIds, int viewId);

services/java/com/android/server/AppWidgetService.java

@@ -279,13 +279,13 @@ public RemoteViews getAppWidgetViews(int appWidgetId) throws RemoteException {
     }
 
     @Override
-    public void updateAppWidgetExtras(int appWidgetId, Bundle extras) {
-        getImplForUser().updateAppWidgetExtras(appWidgetId, extras);
+    public void updateAppWidgetOptions(int appWidgetId, Bundle options) {
+        getImplForUser().updateAppWidgetOptions(appWidgetId, options);
     }
 
     @Override
-    public Bundle getAppWidgetExtras(int appWidgetId) {
-        return getImplForUser().getAppWidgetExtras(appWidgetId);
+    public Bundle getAppWidgetOptions(int appWidgetId) {
+        return getImplForUser().getAppWidgetOptions(appWidgetId);
     }
 
     static int[] getAppWidgetIds(Provider p) {

services/java/com/android/server/AppWidgetServiceImpl.java

@@ -112,7 +112,7 @@ static class AppWidgetId {
         int appWidgetId;
         Provider provider;
         RemoteViews views;
-        Bundle extras;
+        Bundle options;
         Host host;
     }
 
@@ -820,7 +820,7 @@ public void updateAppWidgetIds(int[] appWidgetIds, RemoteViews views) {
         }
     }
 
-    public void updateAppWidgetExtras(int appWidgetId, Bundle extras) {
+    public void updateAppWidgetOptions(int appWidgetId, Bundle options) {
         synchronized (mAppWidgetIds) {
             ensureStateLoadedLocked();
             AppWidgetId id = lookupAppWidgetIdLocked(appWidgetId);
@@ -829,23 +829,23 @@ public void updateAppWidgetExtras(int appWidgetId, Bundle extras) {
                 return;
             }
             Provider p = id.provider;
-            id.extras = extras;
+            id.options = options;
 
             // send the broacast saying that this appWidgetId has been deleted
-            Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_EXTRAS_CHANGED);
+            Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_OPTIONS_CHANGED);
             intent.setComponent(p.info.provider);
             intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, id.appWidgetId);
-            intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_EXTRAS, extras);
+            intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
             mContext.sendBroadcast(intent, mUserId);
         }
     }
 
-    public Bundle getAppWidgetExtras(int appWidgetId) {
+    public Bundle getAppWidgetOptions(int appWidgetId) {
         synchronized (mAppWidgetIds) {
             ensureStateLoadedLocked();
             AppWidgetId id = lookupAppWidgetIdLocked(appWidgetId);
-            if (id != null && id.extras != null) {
-                return id.extras;
+            if (id != null && id.options != null) {
+                return id.options;
             } else {
                 return Bundle.EMPTY;
             }