Merge "Start using the new activity options argument."

Author: Dianne Hackborn

api/current.txt

@@ -2864,6 +2864,12 @@ package android.app {
     field public android.content.ComponentName topActivity;
   }
 
+  public class ActivityOptions {
+    method public void join(android.app.ActivityOptions);
+    method public static android.app.ActivityOptions makeCustomAnimation(android.content.Context, int, int);
+    method public android.os.Bundle toBundle();
+  }
+
   public class AlarmManager {
     method public void cancel(android.app.PendingIntent);
     method public void set(int, long, android.app.PendingIntent);
@@ -3728,7 +3734,9 @@ package android.app {
     method public void cancel();
     method public int describeContents();
     method public static android.app.PendingIntent getActivities(android.content.Context, int, android.content.Intent[], int);
+    method public static android.app.PendingIntent getActivities(android.content.Context, int, android.content.Intent[], int, android.os.Bundle);
     method public static android.app.PendingIntent getActivity(android.content.Context, int, android.content.Intent, int);
+    method public static android.app.PendingIntent getActivity(android.content.Context, int, android.content.Intent, int, android.os.Bundle);
     method public static android.app.PendingIntent getBroadcast(android.content.Context, int, android.content.Intent, int);
     method public android.content.IntentSender getIntentSender();
     method public static android.app.PendingIntent getService(android.content.Context, int, android.content.Intent, int);

core/java/android/app/Activity.java

@@ -32,7 +32,6 @@
 import android.content.res.Configuration;
 import android.content.res.Resources;
 import android.content.res.TypedArray;
-import android.content.res.Resources.Theme;
 import android.database.Cursor;
 import android.graphics.Bitmap;
 import android.graphics.Canvas;
@@ -55,7 +54,6 @@
 import android.util.EventLog;
 import android.util.Log;
 import android.util.SparseArray;
-import android.util.TypedValue;
 import android.view.ActionMode;
 import android.view.ContextMenu;
 import android.view.ContextMenu.ContextMenuInfo;
@@ -3208,7 +3206,8 @@ public void startActivityForResult(Intent intent, int requestCode) {
      * @param requestCode If >= 0, this code will be returned in
      *                    onActivityResult() when the activity exits.
      * @param options Additional options for how the Activity should be started.
-     * May be null if there are no options.
+     * See {@link android.content.Context#startActivity(Intent, Bundle)
+     * Context.startActivity(Intent, Bundle)} for more details.
      *
      * @throws android.content.ActivityNotFoundException
      *
@@ -3288,7 +3287,10 @@ public void startIntentSenderForResult(IntentSender intent, int requestCode,
      * <var>flagsMask</var>
      * @param extraFlags Always set to 0.
      * @param options Additional options for how the Activity should be started.
-     * May be null if there are no options.
+     * See {@link android.content.Context#startActivity(Intent, Bundle)
+     * Context.startActivity(Intent, Bundle)} for more details.  If options
+     * have also been supplied by the IntentSender, options given here will
+     * override any that conflict with those given by the IntentSender.
      */
     public void startIntentSenderForResult(IntentSender intent, int requestCode,
             Intent fillInIntent, int flagsMask, int flagsValues, int extraFlags,
@@ -3369,7 +3371,8 @@ public void startActivity(Intent intent) {
      * 
      * @param intent The intent to start. 
      * @param options Additional options for how the Activity should be started.
-     * May be null if there are no options.
+     * See {@link android.content.Context#startActivity(Intent, Bundle)
+     * Context.startActivity(Intent, Bundle)} for more details.
      * 
      * @throws android.content.ActivityNotFoundException
      *
@@ -3417,7 +3420,8 @@ public void startActivities(Intent[] intents) {
      *
      * @param intents The intents to start.
      * @param options Additional options for how the Activity should be started.
-     * May be null if there are no options.
+     * See {@link android.content.Context#startActivity(Intent, Bundle)
+     * Context.startActivity(Intent, Bundle)} for more details.
      *
      * @throws android.content.ActivityNotFoundException
      *
@@ -3465,7 +3469,10 @@ public void startIntentSender(IntentSender intent,
      * <var>flagsMask</var>
      * @param extraFlags Always set to 0.
      * @param options Additional options for how the Activity should be started.
-     * May be null if there are no options.
+     * See {@link android.content.Context#startActivity(Intent, Bundle)
+     * Context.startActivity(Intent, Bundle)} for more details.  If options
+     * have also been supplied by the IntentSender, options given here will
+     * override any that conflict with those given by the IntentSender.
      */
     public void startIntentSender(IntentSender intent,
             Intent fillInIntent, int flagsMask, int flagsValues, int extraFlags,
@@ -3521,7 +3528,8 @@ public boolean startActivityIfNeeded(Intent intent, int requestCode) {
      *         onActivityResult() when the activity exits, as described in
      *         {@link #startActivityForResult}.
      * @param options Additional options for how the Activity should be started.
-     * May be null if there are no options.
+     * See {@link android.content.Context#startActivity(Intent, Bundle)
+     * Context.startActivity(Intent, Bundle)} for more details.
      * 
      * @return If a new activity was launched then true is returned; otherwise
      *         false is returned and you must handle the Intent yourself.
@@ -3592,7 +3600,8 @@ public boolean startNextMatchingActivity(Intent intent) {
      * your own activity; the only changes you can make are to the extras
      * inside of it.
      * @param options Additional options for how the Activity should be started.
-     * May be null if there are no options.
+     * See {@link android.content.Context#startActivity(Intent, Bundle)
+     * Context.startActivity(Intent, Bundle)} for more details.
      * 
      * @return Returns a boolean indicating whether there was another Activity
      * to start: true if there was a next activity to start, false if there
@@ -3644,7 +3653,8 @@ public void startActivityFromChild(Activity child, Intent intent,
      * @param intent The intent to start.
      * @param requestCode Reply request code.  < 0 if reply is not requested.
      * @param options Additional options for how the Activity should be started.
-     * May be null if there are no options.
+     * See {@link android.content.Context#startActivity(Intent, Bundle)
+     * Context.startActivity(Intent, Bundle)} for more details.
      * 
      * @throws android.content.ActivityNotFoundException
      * 
@@ -3694,7 +3704,8 @@ public void startActivityFromFragment(Fragment fragment, Intent intent,
      * @param intent The intent to start.
      * @param requestCode Reply request code.  < 0 if reply is not requested. 
      * @param options Additional options for how the Activity should be started.
-     * May be null if there are no options.
+     * See {@link android.content.Context#startActivity(Intent, Bundle)
+     * Context.startActivity(Intent, Bundle)} for more details.
      * 
      * @throws android.content.ActivityNotFoundException
      * 
@@ -3744,6 +3755,14 @@ public void startIntentSenderFromChild(Activity child, IntentSender intent,
      * Call immediately after one of the flavors of {@link #startActivity(Intent)}
      * or {@link #finish} to specify an explicit transition animation to
      * perform next.
+     *
+     * <p>As of {@link android.os.Build.VERSION_CODES#JELLY_BEAN} an alternative
+     * to using this with starting activities is to supply the desired animation
+     * information through a {@link ActivityOptions} bundle to
+     * {@link #startActivity(Intent, Bundle) or a related function.  This allows
+     * you to specify a custom animation even when starting an activity from
+     * outside the context of the current top activity.
+     *
      * @param enterAnim A resource ID of the animation resource to use for
      * the incoming activity.  Use 0 for no animation.
      * @param exitAnim A resource ID of the animation resource to use for
@@ -4065,7 +4084,7 @@ public PendingIntent createPendingResult(int requestCode, Intent data,
                 ActivityManagerNative.getDefault().getIntentSender(
                         ActivityManager.INTENT_SENDER_ACTIVITY_RESULT, packageName,
                         mParent == null ? mToken : mParent.mToken,
-                        mEmbeddedID, requestCode, new Intent[] { data }, null, flags);
+                        mEmbeddedID, requestCode, new Intent[] { data }, null, flags, null);
             return target != null ? new PendingIntent(target) : null;
         } catch (RemoteException e) {
             // Empty

core/java/android/app/ActivityManagerNative.java

@@ -835,9 +835,11 @@ public boolean onTransact(int code, Parcel data, Parcel reply, int flags)
                 requestResolvedTypes = null;
             }
             int fl = data.readInt();
+            Bundle options = data.readInt() != 0
+                    ? Bundle.CREATOR.createFromParcel(data) : null;
             IIntentSender res = getIntentSender(type, packageName, token,
                     resultWho, requestCode, requestIntents,
-                    requestResolvedTypes, fl);
+                    requestResolvedTypes, fl, options);
             reply.writeNoException();
             reply.writeStrongBinder(res != null ? res.asBinder() : null);
             return true;
@@ -2607,8 +2609,8 @@ public String getPackageForToken(IBinder token) throws RemoteException
     }
     public IIntentSender getIntentSender(int type,
             String packageName, IBinder token, String resultWho,
-            int requestCode, Intent[] intents, String[] resolvedTypes, int flags)
-            throws RemoteException {
+            int requestCode, Intent[] intents, String[] resolvedTypes, int flags,
+            Bundle options) throws RemoteException {
         Parcel data = Parcel.obtain();
         Parcel reply = Parcel.obtain();
         data.writeInterfaceToken(IActivityManager.descriptor);
@@ -2625,6 +2627,12 @@ public IIntentSender getIntentSender(int type,
             data.writeInt(0);
         }
         data.writeInt(flags);
+        if (options != null) {
+            data.writeInt(1);
+            options.writeToParcel(data, 0);
+        } else {
+            data.writeInt(0);
+        }
         mRemote.transact(GET_INTENT_SENDER_TRANSACTION, data, reply, 0);
         reply.readException();
         IIntentSender res = IIntentSender.Stub.asInterface(

core/java/android/app/Fragment.java

@@ -965,6 +965,8 @@ public LoaderManager getLoaderManager() {
     /**
      * Call {@link Activity#startActivity(Intent)} on the fragment's
      * containing Activity.
+     *
+     * @param intent The intent to start.
      */
     public void startActivity(Intent intent) {
         startActivity(intent, null);
@@ -973,6 +975,11 @@ public void startActivity(Intent intent) {
     /**
      * Call {@link Activity#startActivity(Intent, Bundle)} on the fragment's
      * containing Activity.
+     *
+     * @param intent The intent to start.
+     * @param options Additional options for how the Activity should be started.
+     * See {@link android.content.Context#startActivity(Intent, Bundle)
+     * Context.startActivity(Intent, Bundle)} for more details.
      */
     public void startActivity(Intent intent, Bundle options) {
         if (mActivity == null) {

core/java/android/app/IActivityManager.java

@@ -169,7 +169,7 @@ public void setRequestedOrientation(IBinder token,
     public IIntentSender getIntentSender(int type,
             String packageName, IBinder token, String resultWho,
             int requestCode, Intent[] intents, String[] resolvedTypes,
-            int flags) throws RemoteException;
+            int flags, Bundle options) throws RemoteException;
     public void cancelIntentSender(IIntentSender sender) throws RemoteException;
     public boolean clearApplicationUserData(final String packageName,
             final IPackageDataObserver observer, int userId) throws RemoteException;

core/java/android/app/PendingIntent.java

@@ -188,6 +188,35 @@ public void run() {
      */
     public static PendingIntent getActivity(Context context, int requestCode,
             Intent intent, int flags) {
+        return getActivity(context, requestCode, intent, flags, null);
+    }
+
+    /**
+     * Retrieve a PendingIntent that will start a new activity, like calling
+     * {@link Context#startActivity(Intent) Context.startActivity(Intent)}.
+     * Note that the activity will be started outside of the context of an
+     * existing activity, so you must use the {@link Intent#FLAG_ACTIVITY_NEW_TASK
+     * Intent.FLAG_ACTIVITY_NEW_TASK} launch flag in the Intent.
+     *
+     * @param context The Context in which this PendingIntent should start
+     * the activity.
+     * @param requestCode Private request code for the sender (currently
+     * not used).
+     * @param intent Intent of the activity to be launched.
+     * @param flags May be {@link #FLAG_ONE_SHOT}, {@link #FLAG_NO_CREATE},
+     * {@link #FLAG_CANCEL_CURRENT}, {@link #FLAG_UPDATE_CURRENT},
+     * or any of the flags as supported by
+     * {@link Intent#fillIn Intent.fillIn()} to control which unspecified parts
+     * of the intent that can be supplied when the actual send happens.
+     * @param options Additional options for how the Activity should be started.
+     * May be null if there are no options.
+     *
+     * @return Returns an existing or new PendingIntent matching the given
+     * parameters.  May return null only if {@link #FLAG_NO_CREATE} has been
+     * supplied.
+     */
+    public static PendingIntent getActivity(Context context, int requestCode,
+            Intent intent, int flags, Bundle options) {
         String packageName = context.getPackageName();
         String resolvedType = intent != null ? intent.resolveTypeIfNeeded(
                 context.getContentResolver()) : null;
@@ -197,7 +226,8 @@ public static PendingIntent getActivity(Context context, int requestCode,
                 ActivityManagerNative.getDefault().getIntentSender(
                     ActivityManager.INTENT_SENDER_ACTIVITY, packageName,
                     null, null, requestCode, new Intent[] { intent },
-                    resolvedType != null ? new String[] { resolvedType } : null, flags);
+                    resolvedType != null ? new String[] { resolvedType } : null,
+                    flags, options);
             return target != null ? new PendingIntent(target) : null;
         } catch (RemoteException e) {
         }
@@ -247,6 +277,52 @@ public static PendingIntent getActivity(Context context, int requestCode,
      */
     public static PendingIntent getActivities(Context context, int requestCode,
             Intent[] intents, int flags) {
+        return getActivities(context, requestCode, intents, flags, null);
+    }
+
+    /**
+     * Like {@link #getActivity(Context, int, Intent, int)}, but allows an
+     * array of Intents to be supplied.  The first Intent in the array is
+     * taken as the primary key for the PendingIntent, like the single Intent
+     * given to {@link #getActivity(Context, int, Intent, int)}.  Upon sending
+     * the resulting PendingIntent, all of the Intents are started in the same
+     * way as they would be by passing them to {@link Context#startActivities(Intent[])}.
+     *
+     * <p class="note">
+     * The <em>first</em> intent in the array will be started outside of the context of an
+     * existing activity, so you must use the {@link Intent#FLAG_ACTIVITY_NEW_TASK
+     * Intent.FLAG_ACTIVITY_NEW_TASK} launch flag in the Intent.  (Activities after
+     * the first in the array are started in the context of the previous activity
+     * in the array, so FLAG_ACTIVITY_NEW_TASK is not needed nor desired for them.)
+     * </p>
+     *
+     * <p class="note">
+     * The <em>last</em> intent in the array represents the key for the
+     * PendingIntent.  In other words, it is the significant element for matching
+     * (as done with the single intent given to {@link #getActivity(Context, int, Intent, int)},
+     * its content will be the subject of replacement by
+     * {@link #send(Context, int, Intent)} and {@link #FLAG_UPDATE_CURRENT}, etc.
+     * This is because it is the most specific of the supplied intents, and the
+     * UI the user actually sees when the intents are started.
+     * </p>
+     *
+     * @param context The Context in which this PendingIntent should start
+     * the activity.
+     * @param requestCode Private request code for the sender (currently
+     * not used).
+     * @param intents Array of Intents of the activities to be launched.
+     * @param flags May be {@link #FLAG_ONE_SHOT}, {@link #FLAG_NO_CREATE},
+     * {@link #FLAG_CANCEL_CURRENT}, {@link #FLAG_UPDATE_CURRENT},
+     * or any of the flags as supported by
+     * {@link Intent#fillIn Intent.fillIn()} to control which unspecified parts
+     * of the intent that can be supplied when the actual send happens.
+     *
+     * @return Returns an existing or new PendingIntent matching the given
+     * parameters.  May return null only if {@link #FLAG_NO_CREATE} has been
+     * supplied.
+     */
+    public static PendingIntent getActivities(Context context, int requestCode,
+            Intent[] intents, int flags, Bundle options) {
         String packageName = context.getPackageName();
         String[] resolvedTypes = new String[intents.length];
         for (int i=0; i<intents.length; i++) {
@@ -257,7 +333,7 @@ public static PendingIntent getActivities(Context context, int requestCode,
             IIntentSender target =
                 ActivityManagerNative.getDefault().getIntentSender(
                     ActivityManager.INTENT_SENDER_ACTIVITY, packageName,
-                    null, null, requestCode, intents, resolvedTypes, flags);
+                    null, null, requestCode, intents, resolvedTypes, flags, options);
             return target != null ? new PendingIntent(target) : null;
         } catch (RemoteException e) {
         }
@@ -294,7 +370,8 @@ public static PendingIntent getBroadcast(Context context, int requestCode,
                 ActivityManagerNative.getDefault().getIntentSender(
                     ActivityManager.INTENT_SENDER_BROADCAST, packageName,
                     null, null, requestCode, new Intent[] { intent },
-                    resolvedType != null ? new String[] { resolvedType } : null, flags);
+                    resolvedType != null ? new String[] { resolvedType } : null,
+                    flags, null);
             return target != null ? new PendingIntent(target) : null;
         } catch (RemoteException e) {
         }
@@ -332,7 +409,8 @@ public static PendingIntent getService(Context context, int requestCode,
                 ActivityManagerNative.getDefault().getIntentSender(
                     ActivityManager.INTENT_SENDER_SERVICE, packageName,
                     null, null, requestCode, new Intent[] { intent },
-                    resolvedType != null ? new String[] { resolvedType } : null, flags);
+                    resolvedType != null ? new String[] { resolvedType } : null,
+                    flags, null);
             return target != null ? new PendingIntent(target) : null;
         } catch (RemoteException e) {
         }