From bbb3f41e26ac5a996913907dc63786146132b4ce Mon Sep 17 00:00:00 2001 From: Scott Main Date: Fri, 9 Mar 2012 19:10:40 -0800 Subject: [PATCH] docs: add Settings dev guide; a few changes to javadocs Change-Id: I2d671aafe91e4c6e224e2a556a60dce9f93f11ae --- .../android/preference/PreferenceManager.java | 36 +- docs/html/guide/components/fragments.jd | 6 + docs/html/guide/guide_toc.cs | 3 + docs/html/guide/topics/ui/settings.jd | 1171 +++++++++++++++++ .../ui/settings/settings-headers-handset.png | Bin 0 -> 57277 bytes .../ui/settings/settings-headers-tablet.png | Bin 0 -> 52567 bytes .../images/ui/settings/settings-subscreen.png | Bin 0 -> 49541 bytes .../images/ui/settings/settings-titles.png | Bin 0 -> 66806 bytes docs/html/images/ui/settings/settings.png | Bin 0 -> 96681 bytes 9 files changed, 1208 insertions(+), 8 deletions(-) create mode 100644 docs/html/guide/topics/ui/settings.jd create mode 100644 docs/html/images/ui/settings/settings-headers-handset.png create mode 100644 docs/html/images/ui/settings/settings-headers-tablet.png create mode 100644 docs/html/images/ui/settings/settings-subscreen.png create mode 100644 docs/html/images/ui/settings/settings-titles.png create mode 100644 docs/html/images/ui/settings/settings.png diff --git a/core/java/android/preference/PreferenceManager.java b/core/java/android/preference/PreferenceManager.java index 6562de90a3c82..5ca7d79c13946 100644 --- a/core/java/android/preference/PreferenceManager.java +++ b/core/java/android/preference/PreferenceManager.java @@ -415,19 +415,20 @@ public class PreferenceManager { } /** - * Sets the default values from a preference hierarchy in XML. This should + * Sets the default values from an XML preference file by reading the values defined + * by each {@link Preference} item's {@code android:defaultValue} attribute. This should * be called by the application's main activity. *

- * If {@code readAgain} is false, this will only set the default values if this - * method has never been called in the past (or the + * + * @param context The context of the shared preferences. + * @param resId The resource ID of the preference XML file. + * @param readAgain Whether to re-read the default values. + * If false, this method sets the default values only if this + * method has never been called in the past (or if the * {@link #KEY_HAS_SET_DEFAULT_VALUES} in the default value shared * preferences file is false). To attempt to set the default values again * bypassing this check, set {@code readAgain} to true. - * - * @param context The context of the shared preferences. - * @param resId The resource ID of the preference hierarchy XML file. - * @param readAgain Whether to re-read the default values. - *

+ *

* Note: this will NOT reset preferences back to their default * values. For that functionality, use * {@link PreferenceManager#getDefaultSharedPreferences(Context)} @@ -445,6 +446,25 @@ public class PreferenceManager { * Similar to {@link #setDefaultValues(Context, int, boolean)} but allows * the client to provide the filename and mode of the shared preferences * file. + * + * @param context The context of the shared preferences. + * @param sharedPreferencesName A custom name for the shared preferences file. + * @param sharedPreferencesMode The file creation mode for the shared preferences file, such + * as {@link android.content.Context#MODE_PRIVATE} or {@link + * android.content.Context#MODE_PRIVATE} + * @param resId The resource ID of the preference XML file. + * @param readAgain Whether to re-read the default values. + * If false, this method will set the default values only if this + * method has never been called in the past (or if the + * {@link #KEY_HAS_SET_DEFAULT_VALUES} in the default value shared + * preferences file is false). To attempt to set the default values again + * bypassing this check, set {@code readAgain} to true. + *

+ * Note: this will NOT reset preferences back to their default + * values. For that functionality, use + * {@link PreferenceManager#getDefaultSharedPreferences(Context)} + * and clear it followed by a call to this method with this + * parameter set to true. * * @see #setDefaultValues(Context, int, boolean) * @see #setSharedPreferencesName(String) diff --git a/docs/html/guide/components/fragments.jd b/docs/html/guide/components/fragments.jd index 938e0ab02ea6e..4f620339355aa 100644 --- a/docs/html/guide/components/fragments.jd +++ b/docs/html/guide/components/fragments.jd @@ -709,6 +709,12 @@ href="{@docRoot}guide/components/activities.html#Lifecycle">managing the activit lifecycle also apply to fragments. What you also need to understand, though, is how the life of the activity affects the life of the fragment.

+

Caution: If you need a {@link android.content.Context} object +within your {@link android.app.Fragment}, you can call {@link android.app.Fragment#getActivity()}. +However, be careful to call {@link android.app.Fragment#getActivity()} only when the fragment is +attached to an activity. When the fragment is not yet attached, or was detached during the end of +its lifecycle, {@link android.app.Fragment#getActivity()} will return null.

+

Coordinating with the activity lifecycle

diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 94b9773474ba8..9465f1882a06c 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -197,6 +197,9 @@
  • Action Bar
  • +
  • + Settings +