Add facility to switch to new fragments from preferences.

Change-Id: I009315b59cf81b4962e9c5a4490f0f82743ed64a

4 files changed, 89 insertions, 4 deletions

diff --git a/core/java/android/preference/Preference.java b/core/java/android/preference/Preference.java
index 381f794..117e507 100644
--- a/core/java/android/preference/Preference.java
+++ b/core/java/android/preference/Preference.java
@@ -56,6 +56,7 @@ import java.util.Set;
  * @attr ref android.R.styleable#Preference_title
  * @attr ref android.R.styleable#Preference_summary
  * @attr ref android.R.styleable#Preference_order
+ * @attr ref android.R.styleable#Preference_fragment
  * @attr ref android.R.styleable#Preference_layout
  * @attr ref android.R.styleable#Preference_widgetLayout
  * @attr ref android.R.styleable#Preference_enabled
@@ -88,6 +89,7 @@ public class Preference implements Comparable<Preference>, OnDependencyChangeLis
     private CharSequence mSummary;
     private String mKey;
     private Intent mIntent;
+    private String mFragment;
     private boolean mEnabled = true;
     private boolean mSelectable = true;
     private boolean mRequiresKey;
@@ -210,6 +212,10 @@ public class Preference implements Comparable<Preference>, OnDependencyChangeLis
                     mOrder = a.getInt(attr, mOrder);
                     break;
 
+                case com.android.internal.R.styleable.Preference_fragment:
+                    mFragment = a.getString(attr);
+                    break;
+
                 case com.android.internal.R.styleable.Preference_layout:
                     mLayoutResId = a.getResourceId(attr, mLayoutResId);
                     break;
@@ -315,6 +321,24 @@ public class Preference implements Comparable<Preference>, OnDependencyChangeLis
     }
 
     /**
+     * Sets the class name of a fragment to be shown when this Preference is clicked.
+     *
+     * @param fragment The class name of the fragment associated with this Preference.
+     */
+    public void setFragment(String fragment) {
+        mFragment = fragment;
+    }
+
+    /**
+     * Return the fragment class name associated with this Preference.
+     *
+     * @return The fragment class name last set via {@link #setFragment} or XML.
+     */
+    public String getFragment() {
+        return mFragment;
+    }
+
+    /**
      * Sets the layout resource that is inflated as the {@link View} to be shown
      * for this Preference. In most cases, the default layout is sufficient for
      * custom Preference objects and only the widget layout needs to be changed.
diff --git a/core/java/android/preference/PreferenceActivity.java b/core/java/android/preference/PreferenceActivity.java
index fdc874b..e13c3e8 100644
--- a/core/java/android/preference/PreferenceActivity.java
+++ b/core/java/android/preference/PreferenceActivity.java
@@ -93,11 +93,22 @@ import java.util.List;
  *
  * {@sample development/samples/ApiDemos/res/xml/preference_headers.xml headers}
  *
- * See {@link PreferenceFragment} for information on implementing the
+ * <p>The first header is shown by Prefs1Fragment, which populates itself
+ * from the following XML resource:</p>
+ *
+ * {@sample development/samples/ApiDemos/res/xml/fragmented_preferences.xml preferences}
+ *
+ * <p>Note that this XML resource contains a preference screen holding another
+ * fragment, the Prefs1FragmentInner implemented here.  This allows the user
+ * to traverse down a hierarchy of preferences; pressing back will pop each
+ * fragment off the stack to return to the previous preferences.
+ *
+ * <p>See {@link PreferenceFragment} for information on implementing the
  * fragments themselves.
  */
 public abstract class PreferenceActivity extends ListActivity implements
-        PreferenceManager.OnPreferenceTreeClickListener {
+        PreferenceManager.OnPreferenceTreeClickListener,
+        PreferenceFragment.OnPreferenceStartFragmentCallback {
     private static final String TAG = "PreferenceActivity";
 
     private static final String PREFERENCES_TAG = "android:preferences";
@@ -106,6 +117,8 @@ public abstract class PreferenceActivity extends ListActivity implements
 
     private static final String EXTRA_PREFS_NO_HEADERS = ":android:no_headers";
 
+    private static final String BACK_STACK_PREFS = ":android:prefs";
+
     // extras that allow any preference activity to be launched as part of a wizard
 
     // show Back and Next buttons? takes boolean parameter
@@ -206,16 +219,19 @@ public abstract class PreferenceActivity extends ListActivity implements
     public static class Header {
         /**
          * Title of the header that is shown to the user.
+         * @attr ref android.R.styleable#PreferenceHeader_title
          */
         CharSequence title;
 
         /**
          * Optional summary describing what this header controls.
+         * @attr ref android.R.styleable#PreferenceHeader_summary
          */
         CharSequence summary;
 
         /**
          * Optional icon resource to show for this header.
+         * @attr ref android.R.styleable#PreferenceHeader_icon
          */
         int iconRes;
 
@@ -228,6 +244,7 @@ public abstract class PreferenceActivity extends ListActivity implements
         /**
          * Full class name of the fragment to display when this header is
          * selected.
+         * @attr ref android.R.styleable#PreferenceHeader_fragment
          */
         String fragment;
     }
@@ -551,6 +568,8 @@ public abstract class PreferenceActivity extends ListActivity implements
      * @param fragmentName The name of the fragment to display.
      */
     public void switchToHeader(String fragmentName) {
+        popBackStack(BACK_STACK_PREFS, POP_BACK_STACK_INCLUSIVE);
+
         Fragment f;
         try {
             f = Fragment.instantiate(this, fragmentName);
@@ -561,6 +580,20 @@ public abstract class PreferenceActivity extends ListActivity implements
         openFragmentTransaction().replace(com.android.internal.R.id.prefs, f).commit();
     }
 
+    @Override
+    public boolean onPreferenceStartFragment(PreferenceFragment caller, Preference pref) {
+        Fragment f;
+        try {
+            f = Fragment.instantiate(this, pref.getFragment());
+        } catch (Exception e) {
+            Log.w(TAG, "Failure instantiating fragment " + pref.getFragment(), e);
+            return false;
+        }
+        openFragmentTransaction().replace(com.android.internal.R.id.prefs, f)
+                .addToBackStack(BACK_STACK_PREFS).commit();
+        return true;
+    }
+
     /**
      * Posts a message to bind the preferences to the list view.
      * <p>
diff --git a/core/java/android/preference/PreferenceFragment.java b/core/java/android/preference/PreferenceFragment.java
index ac61574..a5395e2 100644
--- a/core/java/android/preference/PreferenceFragment.java
+++ b/core/java/android/preference/PreferenceFragment.java
@@ -125,6 +125,21 @@ public abstract class PreferenceFragment extends Fragment implements
         }
     };
 
+    /**
+     * Interface that PreferenceFragment's containing activity should
+     * implement to be able to process preference items that wish to
+     * switch to a new fragment.
+     */
+    public interface OnPreferenceStartFragmentCallback {
+        /**
+         * Called when the user has clicked on a Preference that has
+         * a fragment class name associated with it.  The implementation
+         * to should instantiate and switch to an instance of the given
+         * fragment.
+         */
+        boolean onPreferenceStartFragment(PreferenceFragment caller, Preference pref);
+    }
+
     @Override
     public void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
@@ -168,6 +183,13 @@ public abstract class PreferenceFragment extends Fragment implements
     }
 
     @Override
+    public void onDestroyView() {
+        mList = null;
+        mHandler.removeCallbacks(mRequestFocus);
+        super.onDestroyView();
+    }
+
+    @Override
     public void onDestroy() {
         super.onDestroy();
         mPreferenceManager.dispatchActivityDestroy();
@@ -251,7 +273,13 @@ public abstract class PreferenceFragment extends Fragment implements
     /**
      * {@inheritDoc}
      */
-    public boolean onPreferenceTreeClick(PreferenceScreen preferenceScreen, Preference preference) {
+    public boolean onPreferenceTreeClick(PreferenceScreen preferenceScreen,
+            Preference preference) {
+        if (preference.getFragment() != null &&
+                getActivity() instanceof OnPreferenceStartFragmentCallback) {
+            return ((OnPreferenceStartFragmentCallback)getActivity()).onPreferenceStartFragment(
+                    this, preference);
+        }
         return false;
     }
 
diff --git a/core/java/android/preference/PreferenceScreen.java b/core/java/android/preference/PreferenceScreen.java
index 95e5432..f34f4a3 100644
--- a/core/java/android/preference/PreferenceScreen.java
+++ b/core/java/android/preference/PreferenceScreen.java
@@ -136,7 +136,7 @@ public final class PreferenceScreen extends PreferenceGroup implements AdapterVi
     
     @Override
     protected void onClick() {
-        if (getIntent() != null || getPreferenceCount() == 0) {
+        if (getIntent() != null || getFragment() != null || getPreferenceCount() == 0) {
             return;
         }