Merge "Deprecate a bunch of APIs."
diff --git a/api/current.txt b/api/current.txt
index 1c7c11b..05b7c35 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -2180,7 +2180,7 @@
method public void closeContextMenu();
method public void closeOptionsMenu();
method public android.app.PendingIntent createPendingResult(int, android.content.Intent, int);
- method public final void dismissDialog(int);
+ method public final deprecated void dismissDialog(int);
method public boolean dispatchGenericMotionEvent(android.view.MotionEvent);
method public boolean dispatchKeyEvent(android.view.KeyEvent);
method public boolean dispatchKeyShortcutEvent(android.view.KeyEvent);
@@ -2202,7 +2202,7 @@
method public android.view.View getCurrentFocus();
method public android.app.FragmentManager getFragmentManager();
method public android.content.Intent getIntent();
- method public java.lang.Object getLastNonConfigurationInstance();
+ method public deprecated java.lang.Object getLastNonConfigurationInstance();
method public android.view.LayoutInflater getLayoutInflater();
method public android.app.LoaderManager getLoaderManager();
method public java.lang.String getLocalClassName();
@@ -2239,7 +2239,7 @@
method public void onCreateContextMenu(android.view.ContextMenu, android.view.View, android.view.ContextMenu.ContextMenuInfo);
method public java.lang.CharSequence onCreateDescription();
method protected deprecated android.app.Dialog onCreateDialog(int);
- method protected android.app.Dialog onCreateDialog(int, android.os.Bundle);
+ method protected deprecated android.app.Dialog onCreateDialog(int, android.os.Bundle);
method public boolean onCreateOptionsMenu(android.view.Menu);
method public boolean onCreatePanelMenu(int, android.view.Menu);
method public android.view.View onCreatePanelView(int);
@@ -2265,13 +2265,13 @@
method protected void onPostCreate(android.os.Bundle);
method protected void onPostResume();
method protected deprecated void onPrepareDialog(int, android.app.Dialog);
- method protected void onPrepareDialog(int, android.app.Dialog, android.os.Bundle);
+ method protected deprecated void onPrepareDialog(int, android.app.Dialog, android.os.Bundle);
method public boolean onPrepareOptionsMenu(android.view.Menu);
method public boolean onPreparePanel(int, android.view.View, android.view.Menu);
method protected void onRestart();
method protected void onRestoreInstanceState(android.os.Bundle);
method protected void onResume();
- method public java.lang.Object onRetainNonConfigurationInstance();
+ method public deprecated java.lang.Object onRetainNonConfigurationInstance();
method protected void onSaveInstanceState(android.os.Bundle);
method public boolean onSearchRequested();
method protected void onStart();
@@ -2289,7 +2289,7 @@
method public void overridePendingTransition(int, int);
method public void recreate();
method public void registerForContextMenu(android.view.View);
- method public final void removeDialog(int);
+ method public final deprecated void removeDialog(int);
method public final boolean requestWindowFeature(int);
method public final void runOnUiThread(java.lang.Runnable);
method public void setContentView(int);
@@ -2315,8 +2315,8 @@
method public void setTitleColor(int);
method public void setVisible(boolean);
method public final void setVolumeControlStream(int);
- method public final void showDialog(int);
- method public final boolean showDialog(int, android.os.Bundle);
+ method public final deprecated void showDialog(int);
+ method public final deprecated boolean showDialog(int, android.os.Bundle);
method public android.view.ActionMode startActionMode(android.view.ActionMode.Callback);
method public void startActivityForResult(android.content.Intent, int);
method public void startActivityFromChild(android.app.Activity, android.content.Intent, int);
@@ -3042,12 +3042,12 @@
}
public class KeyguardManager {
- method public void exitKeyguardSecurely(android.app.KeyguardManager.OnKeyguardExitResult);
+ method public deprecated void exitKeyguardSecurely(android.app.KeyguardManager.OnKeyguardExitResult);
method public boolean inKeyguardRestrictedInputMode();
- method public android.app.KeyguardManager.KeyguardLock newKeyguardLock(java.lang.String);
+ method public deprecated android.app.KeyguardManager.KeyguardLock newKeyguardLock(java.lang.String);
}
- public class KeyguardManager.KeyguardLock {
+ public deprecated class KeyguardManager.KeyguardLock {
method public void disableKeyguard();
method public void reenableKeyguard();
}
@@ -13961,7 +13961,7 @@
field public static final int FULL_WAKE_LOCK = 26; // 0x1a
field public static final int ON_AFTER_RELEASE = 536870912; // 0x20000000
field public static final int PARTIAL_WAKE_LOCK = 1; // 0x1
- field public static final int SCREEN_BRIGHT_WAKE_LOCK = 10; // 0xa
+ field public static final deprecated int SCREEN_BRIGHT_WAKE_LOCK = 10; // 0xa
field public static final int SCREEN_DIM_WAKE_LOCK = 6; // 0x6
}
diff --git a/core/java/android/app/Activity.java b/core/java/android/app/Activity.java
index ed39457..389d4856 100644
--- a/core/java/android/app/Activity.java
+++ b/core/java/android/app/Activity.java
@@ -1437,6 +1437,10 @@
}
/**
+ * @deprecated Use the new {@link Fragment} API
+ * {@link Fragment#setRetainInstance(boolean)} instead; this is also
+ * available on older platforms through the Android compatibility package.
+ *
* Retrieve the non-configuration instance data that was previously
* returned by {@link #onRetainNonConfigurationInstance()}. This will
* be available from the initial {@link #onCreate} and
@@ -1453,12 +1457,17 @@
* @return Returns the object previously returned by
* {@link #onRetainNonConfigurationInstance()}.
*/
+ @Deprecated
public Object getLastNonConfigurationInstance() {
return mLastNonConfigurationInstances != null
? mLastNonConfigurationInstances.activity : null;
}
/**
+ * @deprecated Use the new {@link Fragment} API
+ * {@link Fragment#setRetainInstance(boolean)} instead; this is also
+ * available on older platforms through the Android compatibility package.
+ *
* Called by the system, as part of destroying an
* activity due to a configuration change, when it is known that a new
* instance will immediately be created for the new configuration. You
@@ -1674,6 +1683,10 @@
}
/**
+ * @deprecated Use the new {@link android.content.CursorLoader} class with
+ * {@link LoaderManager} instead; this is also
+ * available on older platforms through the Android compatibility package.
+ *
* This method allows the activity to take care of managing the given
* {@link Cursor}'s lifecycle for you based on the activity's lifecycle.
* That is, when the activity is stopped it will automatically call
@@ -1689,8 +1702,6 @@
*
* @see #managedQuery(android.net.Uri , String[], String, String[], String)
* @see #stopManagingCursor
- *
- * @deprecated Use {@link CursorLoader} instead.
*/
@Deprecated
public void startManagingCursor(Cursor c) {
@@ -1700,6 +1711,10 @@
}
/**
+ * @deprecated Use the new {@link android.content.CursorLoader} class with
+ * {@link LoaderManager} instead; this is also
+ * available on older platforms through the Android compatibility package.
+ *
* Given a Cursor that was previously given to
* {@link #startManagingCursor}, stop the activity's management of that
* cursor.
@@ -1707,8 +1722,6 @@
* @param c The Cursor that was being managed.
*
* @see #startManagingCursor
- *
- * @deprecated Use {@link CursorLoader} instead.
*/
@Deprecated
public void stopManagingCursor(Cursor c) {
@@ -2714,6 +2727,10 @@
}
/**
+ * @deprecated Use the new {@link DialogFragment} class with
+ * {@link FragmentManager} instead; this is also
+ * available on older platforms through the Android compatibility package.
+ *
* Callback for creating dialogs that are managed (saved and restored) for you
* by the activity. The default implementation calls through to
* {@link #onCreateDialog(int)} for compatibility.
@@ -2742,6 +2759,7 @@
* @see #dismissDialog(int)
* @see #removeDialog(int)
*/
+ @Deprecated
protected Dialog onCreateDialog(int id, Bundle args) {
return onCreateDialog(id);
}
@@ -2756,6 +2774,10 @@
}
/**
+ * @deprecated Use the new {@link DialogFragment} class with
+ * {@link FragmentManager} instead; this is also
+ * available on older platforms through the Android compatibility package.
+ *
* Provides an opportunity to prepare a managed dialog before it is being
* shown. The default implementation calls through to
* {@link #onPrepareDialog(int, Dialog)} for compatibility.
@@ -2775,20 +2797,30 @@
* @see #dismissDialog(int)
* @see #removeDialog(int)
*/
+ @Deprecated
protected void onPrepareDialog(int id, Dialog dialog, Bundle args) {
onPrepareDialog(id, dialog);
}
/**
+ * @deprecated Use the new {@link DialogFragment} class with
+ * {@link FragmentManager} instead; this is also
+ * available on older platforms through the Android compatibility package.
+ *
* Simple version of {@link #showDialog(int, Bundle)} that does not
* take any arguments. Simply calls {@link #showDialog(int, Bundle)}
* with null arguments.
*/
+ @Deprecated
public final void showDialog(int id) {
showDialog(id, null);
}
/**
+ * @deprecated Use the new {@link DialogFragment} class with
+ * {@link FragmentManager} instead; this is also
+ * available on older platforms through the Android compatibility package.
+ *
* Show a dialog managed by this activity. A call to {@link #onCreateDialog(int, Bundle)}
* will be made with the same id the first time this is called for a given
* id. From thereafter, the dialog will be automatically saved and restored.
@@ -2814,6 +2846,7 @@
* @see #dismissDialog(int)
* @see #removeDialog(int)
*/
+ @Deprecated
public final boolean showDialog(int id, Bundle args) {
if (mManagedDialogs == null) {
mManagedDialogs = new SparseArray<ManagedDialog>();
@@ -2835,6 +2868,10 @@
}
/**
+ * @deprecated Use the new {@link DialogFragment} class with
+ * {@link FragmentManager} instead; this is also
+ * available on older platforms through the Android compatibility package.
+ *
* Dismiss a dialog that was previously shown via {@link #showDialog(int)}.
*
* @param id The id of the managed dialog.
@@ -2847,6 +2884,7 @@
* @see #showDialog(int)
* @see #removeDialog(int)
*/
+ @Deprecated
public final void dismissDialog(int id) {
if (mManagedDialogs == null) {
throw missingDialog(id);
@@ -2869,6 +2907,10 @@
}
/**
+ * @deprecated Use the new {@link DialogFragment} class with
+ * {@link FragmentManager} instead; this is also
+ * available on older platforms through the Android compatibility package.
+ *
* Removes any internal references to a dialog managed by this Activity.
* If the dialog is showing, it will dismiss it as part of the clean up.
*
@@ -2886,6 +2928,7 @@
* @see #showDialog(int)
* @see #dismissDialog(int)
*/
+ @Deprecated
public final void removeDialog(int id) {
if (mManagedDialogs != null) {
final ManagedDialog md = mManagedDialogs.get(id);
diff --git a/core/java/android/app/Fragment.java b/core/java/android/app/Fragment.java
index dd158f9..6f0bbd7 100644
--- a/core/java/android/app/Fragment.java
+++ b/core/java/android/app/Fragment.java
@@ -164,11 +164,21 @@
*
* <p>Topics covered here:
* <ol>
+ * <li><a href="#OlderPlatforms">Older Platforms</a>
* <li><a href="#Lifecycle">Lifecycle</a>
* <li><a href="#Layout">Layout</a>
* <li><a href="#BackStack">Back Stack</a>
* </ol>
*
+ * <a name="OlderPlatforms"></a>
+ * <h3>Older Platforms</h3>
+ *
+ * While the Fragment API was introduced in
+ * {@link android.os.Build.VERSION_CODES#HONEYCOMB}, a version of the API
+ * is also available for use on older platforms. See the blog post
+ * <a href="http://android-developers.blogspot.com/2011/03/fragments-for-all.html">
+ * Fragments For All</a> for more details.
+ *
* <a name="Lifecycle"></a>
* <h3>Lifecycle</h3>
*
diff --git a/core/java/android/app/KeyguardManager.java b/core/java/android/app/KeyguardManager.java
index a601fbf..0fe7b5c 100644
--- a/core/java/android/app/KeyguardManager.java
+++ b/core/java/android/app/KeyguardManager.java
@@ -35,6 +35,12 @@
private IWindowManager mWM;
/**
+ * @deprecated Use {@link android.view.WindowManager.LayoutParams#FLAG_DISMISS_KEYGUARD}
+ * and/or {@link android.view.WindowManager.LayoutParams#FLAG_SHOW_WHEN_LOCKED}
+ * instead; this allows you to seamlessly hide the keyguard as your application
+ * moves in and out of the foreground and does not require that any special
+ * permissions be requested.
+ *
* Handle returned by {@link KeyguardManager#newKeyguardLock} that allows
* you to disable / reenable the keyguard.
*/
@@ -103,6 +109,12 @@
}
/**
+ * @deprecated Use {@link android.view.WindowManager.LayoutParams#FLAG_DISMISS_KEYGUARD}
+ * and/or {@link android.view.WindowManager.LayoutParams#FLAG_SHOW_WHEN_LOCKED}
+ * instead; this allows you to seamlessly hide the keyguard as your application
+ * moves in and out of the foreground and does not require that any special
+ * permissions be requested.
+ *
* Enables you to lock or unlock the keyboard. Get an instance of this class by
* calling {@link android.content.Context#getSystemService(java.lang.String) Context.getSystemService()}.
* This class is wrapped by {@link android.app.KeyguardManager KeyguardManager}.
@@ -112,6 +124,7 @@
* @return A {@link KeyguardLock} handle to use to disable and reenable the
* keyguard.
*/
+ @Deprecated
public KeyguardLock newKeyguardLock(String tag) {
return new KeyguardLock(tag);
}
@@ -168,6 +181,12 @@
}
/**
+ * @deprecated Use {@link android.view.WindowManager.LayoutParams#FLAG_DISMISS_KEYGUARD}
+ * and/or {@link android.view.WindowManager.LayoutParams#FLAG_SHOW_WHEN_LOCKED}
+ * instead; this allows you to seamlessly hide the keyguard as your application
+ * moves in and out of the foreground and does not require that any special
+ * permissions be requested.
+ *
* Exit the keyguard securely. The use case for this api is that, after
* disabling the keyguard, your app, which was granted permission to
* disable the keyguard and show a limited amount of information deemed
@@ -181,6 +200,7 @@
* it is safe to launch anything that would normally be considered safe
* once the user has gotten past the keyguard.
*/
+ @Deprecated
public void exitKeyguardSecurely(final OnKeyguardExitResult callback) {
try {
mWM.exitKeyguardSecurely(new IOnKeyguardExitResult.Stub() {
diff --git a/core/java/android/app/LoaderManager.java b/core/java/android/app/LoaderManager.java
index 1ee386d..164141c 100644
--- a/core/java/android/app/LoaderManager.java
+++ b/core/java/android/app/LoaderManager.java
@@ -34,12 +34,18 @@
* {@link android.content.CursorLoader}, however applications are free to write
* their own loaders for loading other types of data.
*
+ * While the LoaderManager API was introduced in
+ * {@link android.os.Build.VERSION_CODES#HONEYCOMB}, a version of the API
+ * is also available for use on older platforms. See the blog post
+ * <a href="http://android-developers.blogspot.com/2011/03/fragments-for-all.html">
+ * Fragments For All</a> for more details.
+ *
* <p>As an example, here is the full implementation of a {@link Fragment}
* that displays a {@link android.widget.ListView} containing the results of
* a query against the contacts content provider. It uses a
* {@link android.content.CursorLoader} to manage the query on the provider.
*
- * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentListCursorLoader.java
+ * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/LoaderCursor.java
* fragment_cursor}
*/
public abstract class LoaderManager {
diff --git a/core/java/android/content/AsyncTaskLoader.java b/core/java/android/content/AsyncTaskLoader.java
index 383cb6b..0b54396 100644
--- a/core/java/android/content/AsyncTaskLoader.java
+++ b/core/java/android/content/AsyncTaskLoader.java
@@ -27,7 +27,24 @@
import java.util.concurrent.CountDownLatch;
/**
- * Abstract Loader that provides an {@link AsyncTask} to do the work.
+ * Abstract Loader that provides an {@link AsyncTask} to do the work. See
+ * {@link Loader} and {@link android.app.LoaderManager} for more details.
+ *
+ * <p>Here is an example implementation of an AsyncTaskLoader subclass that
+ * loads the currently installed applications from the package manager. This
+ * implementation takes care of retrieving the application labels and sorting
+ * its result set from them, monitoring for changes to the installed
+ * applications, and rebuilding the list when a change in configuration requires
+ * this (such as a locale change).
+ *
+ * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/LoaderCustom.java
+ * loader}
+ *
+ * <p>An example implementation of a fragment that uses the above loader to show
+ * the currently installed applications in a list is below.
+ *
+ * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/LoaderCustom.java
+ * fragment}
*
* @param <D> the data type to be loaded.
*/
diff --git a/core/java/android/content/Loader.java b/core/java/android/content/Loader.java
index a9d6117..4e70b74 100644
--- a/core/java/android/content/Loader.java
+++ b/core/java/android/content/Loader.java
@@ -26,7 +26,7 @@
/**
* An abstract class that performs asynchronous loading of data. While Loaders are active
* they should monitor the source of their data and deliver new results when the contents
- * change.
+ * change. See {@link android.app.LoaderManager} for more detail.
*
* <p><b>Note on threading:</b> Clients of loaders should as a rule perform
* any calls on to a Loader from the main thread of their process (that is,
@@ -36,7 +36,10 @@
* be done on the main thread.</p>
*
* <p>Subclasses generally must implement at least {@link #onStartLoading()},
- * {@link #onStopLoading()}, {@link #onForceLoad()}, and {@link #onReset()}.
+ * {@link #onStopLoading()}, {@link #onForceLoad()}, and {@link #onReset()}.</p>
+ *
+ * <p>Most implementations should not derive directly from this class, but
+ * instead inherit from {@link AsyncTaskLoader}.</p>
*
* @param <D> The result returned when the load is complete
*/
@@ -76,8 +79,12 @@
}
/**
- * Stores away the application context associated with context. Since Loaders can be used
- * across multiple activities it's dangerous to store the context directly.
+ * Stores away the application context associated with context.
+ * Since Loaders can be used across multiple activities it's dangerous to
+ * store the context directly; always use {@link #getContext()} to retrieve
+ * the Loader's Context, don't use the constructor argument directly.
+ * The Context returned by {@link #getContext} is safe to use across
+ * Activity instances.
*
* @param context used to retrieve the application context.
*/
diff --git a/core/java/android/os/PowerManager.java b/core/java/android/os/PowerManager.java
index 57fdb0c..c830f7a 100644
--- a/core/java/android/os/PowerManager.java
+++ b/core/java/android/os/PowerManager.java
@@ -131,14 +131,25 @@
/**
* Wake lock that ensures that the screen and keyboard are on at
* full brightness.
+ *
+ * <p class="note">Most applications should strongly consider using
+ * {@link android.view.WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON}.
+ * This window flag will be correctly managed by the platform
+ * as the user moves between applications and doesn't require a special permission.</p>
*/
public static final int FULL_WAKE_LOCK = WAKE_BIT_CPU_WEAK | WAKE_BIT_SCREEN_BRIGHT
| WAKE_BIT_KEYBOARD_BRIGHT;
/**
+ * @deprecated Most applications should use
+ * {@link android.view.WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON} instead
+ * of this type of wake lock, as it will be correctly managed by the platform
+ * as the user moves between applications and doesn't require a special permission.
+ *
* Wake lock that ensures that the screen is on at full brightness;
* the keyboard backlight will be allowed to go off.
*/
+ @Deprecated
public static final int SCREEN_BRIGHT_WAKE_LOCK = WAKE_BIT_CPU_WEAK | WAKE_BIT_SCREEN_BRIGHT;
/**
@@ -384,6 +395,11 @@
*wl.release();
* }
*
+ * <p class="note">If using this to keep the screen on, you should strongly consider using
+ * {@link android.view.WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON} instead.
+ * This window flag will be correctly managed by the platform
+ * as the user moves between applications and doesn't require a special permission.</p>
+ *
* @param flags Combination of flag values defining the requested behavior of the WakeLock.
* @param tag Your class name (or other tag) for debugging purposes.
*
diff --git a/core/java/android/view/inputmethod/InputConnection.java b/core/java/android/view/inputmethod/InputConnection.java
index ea9e402..a6639d1 100644
--- a/core/java/android/view/inputmethod/InputConnection.java
+++ b/core/java/android/view/inputmethod/InputConnection.java
@@ -26,8 +26,9 @@
* is used to perform such things as reading text around the cursor,
* committing text to the text box, and sending raw key events to the application.
*
- * <p>Implementations of this interface should generally be done by
- * subclassing {@link BaseInputConnection}.
+ * <p>Applications should never directly implement this interface, but instead
+ * subclass from {@link BaseInputConnection}. This will ensure that the
+ * application does not break when new methods are added to the interface.
*/
public interface InputConnection {
/**