PreferenceActivity 安卓开发者译文

类概述

这个Activity用来向用户展示一个或者更多的preferences 的 headers,
每一个headers
都关联一个PreferenceFragment 来展示本headers的preferences
。 他们组合的布局或者样式可以使多样的; 目前主要有以下2种方式:

• 当第一次启动的时候，它只用一个单一的list来仅仅展示你的header.当你选中其中一个header 项时，他会重启Activity来展示和本header
  项相关的PreferenceFragment.
• 在你的屏幕上用窗格的形式同时展示你的headers 和当前的PreferenceFragment.当你选中其中一个header
  项时就转换为本header
  项相关的PreferenceFragment.

PreferenceActivity的子类应该实现 onBuildHeaders(List)来放置你相关的header .这样做来实现我们的"headers
+ fragments"模式远远好于老式只是显示一个单一的喜好列表preferences list.

Developer Guides

关于使用PreferenceActivity 的更多信息, 请阅读 Settings 指导.

样例代码

下面的例子展示了一个带有两种不同preferences集的简单preference
activity . 它的实现包括这个Activity本身和2个小的preference Fragment

public class PreferenceWithHeaders extends PreferenceActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Add a button to the header list.
        if (hasHeaders()) {
            Button button = new Button(this);
            button.setText("Some action");
            setListFooter(button);
        }
    }

    /**
     * Populate the activity with the top-level headers.
     */
    @Override
    public void onBuildHeaders(List<Header> target) {
        loadHeadersFromResource(R.xml.preference_headers, target);
    }

    /**
     * This fragment shows the preferences for the first header.
     */
    public static class Prefs1Fragment extends PreferenceFragment {
        @Override
        public void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);

            // Make sure default values are applied.  In a real app, you would
            // want this in a shared function that is used to retrieve the
            // SharedPreferences wherever they are needed.
            PreferenceManager.setDefaultValues(getActivity(),
                    R.xml.advanced_preferences, false);

            // Load the preferences from an XML resource
            addPreferencesFromResource(R.xml.fragmented_preferences);
        }
    }

    /**
     * This fragment contains a second-level set of preference that you
     * can get to by tapping an item in the first preferences fragment.
     */
    public static class Prefs1FragmentInner extends PreferenceFragment {
        @Override
        public void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);

            // Can retrieve arguments from preference XML.
            Log.i("args", "Arguments: " + getArguments());

            // Load the preferences from an XML resource
            addPreferencesFromResource(R.xml.fragmented_preferences_inner);
        }
    }

    /**
     * This fragment shows the preferences for the second header.
     */
    public static class Prefs2Fragment extends PreferenceFragment {
        @Override
        public void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);

            // Can retrieve arguments from headers XML.
            Log.i("args", "Arguments: " + getArguments());

            // Load the preferences from an XML resource
            addPreferencesFromResource(R.xml.preference_dependencies);
        }
    }
}

The preference_headers resource describes the headers to be displayed and the fragments associated with them. It is:

<preference-headers
        xmlns:android="http://schemas.android.com/apk/res/android">

    <header android:fragment="com.example.android.apis.preference.PreferenceWithHeaders$Prefs1Fragment"
            android:icon="@drawable/ic_settings_applications"
            android:title="Prefs 1"
            android:summary="An example of some preferences." />

    <header android:fragment="com.example.android.apis.preference.PreferenceWithHeaders$Prefs2Fragment"
            android:icon="@drawable/ic_settings_display"
            android:title="Prefs 2"
            android:summary="Some other preferences you can see.">
        <!-- Arbitrary key/value pairs can be included with a header as
             arguments to its fragment. -->
        <extra android:name="someKey" android:value="someHeaderValue" />
    </header>

    <header android:icon="@drawable/ic_settings_display"
            android:title="Intent"
            android:summary="Launches an Intent.">
        <intent android:action="android.intent.action.VIEW"
                android:data="http://www.android.com" />
    </header>

</preference-headers>

第一个header 用来打开 Prefs1Fragment,
Prefs1Fragment使用下面的 XML 文件:

<PreferenceScreen
        xmlns:android="http://schemas.android.com/apk/res/android">

    <PreferenceCategory
            android:title="@string/inline_preferences">

        <CheckBoxPreference
                android:key="checkbox_preference"
                android:title="@string/title_checkbox_preference"
                android:summary="@string/summary_checkbox_preference" />

    </PreferenceCategory>

    <PreferenceCategory
            android:title="@string/dialog_based_preferences">

        <EditTextPreference
                android:key="edittext_preference"
                android:title="@string/title_edittext_preference"
                android:summary="@string/summary_edittext_preference"
                android:dialogTitle="@string/dialog_title_edittext_preference" />

        <ListPreference
                android:key="list_preference"
                android:title="@string/title_list_preference"
                android:summary="@string/summary_list_preference"
                android:entries="@array/entries_list_preference"
                android:entryValues="@array/entryvalues_list_preference"
                android:dialogTitle="@string/dialog_title_list_preference" />

    </PreferenceCategory>

    <PreferenceCategory
            android:title="@string/launch_preferences">

        <!-- This PreferenceScreen tag sends the user to a new fragment of
             preferences.  If running in a large screen, they can be embedded
             inside of the overall preferences UI. -->
        <PreferenceScreen
                android:fragment="com.example.android.apis.preference.PreferenceWithHeaders$Prefs1FragmentInner"
                android:title="@string/title_fragment_preference"
                android:summary="@string/summary_fragment_preference">
            <!-- Arbitrary key/value pairs can be included for fragment arguments -->
            <extra android:name="someKey" android:value="somePrefValue" />
        </PreferenceScreen>

        <!-- This PreferenceScreen tag sends the user to a completely different
             activity, switching out of the current preferences UI. -->
        <PreferenceScreen
                android:title="@string/title_intent_preference"
                android:summary="@string/summary_intent_preference">

            <intent android:action="android.intent.action.VIEW"
                    android:data="http://www.android.com" />

        </PreferenceScreen>

    </PreferenceCategory>

    <PreferenceCategory
            android:title="@string/preference_attributes">

        <CheckBoxPreference
                android:key="parent_checkbox_preference"
                android:title="@string/title_parent_preference"
                android:summary="@string/summary_parent_preference" />

        <!-- The visual style of a child is defined by this styled theme attribute. -->
        <CheckBoxPreference
                android:key="child_checkbox_preference"
                android:dependency="parent_checkbox_preference"
                android:layout="?android:attr/preferenceLayoutChild"
                android:title="@string/title_child_preference"
                android:summary="@string/summary_child_preference" />

    </PreferenceCategory>

</PreferenceScreen>

你需要注意的是，在这个XML 文件中我们在PreferenceScreen 标签的内部包含了一个新的fragment。Prefs1FragmentInner 的存在， 允许用户乡下逐层遍历 preferences; 而当我们按下返回键的时候就从栈中弹出上一个fragment来返回我们的上一级preferences.

See PreferenceFragment for
information on implementing the fragments themselves.

概述 （部分信息缺失，请查看官方文档）

嵌套类
用来描述Header的类 公有构造函数 PreferenceActivity()

[展开] 继承方法
From class android.app.ListActivity
From class android.app.Activity
From class android.view.ContextThemeWrapper
From class android.content.ContextWrapper
From class android.content.Context
From class java.lang.Object
From interface android.content.ComponentCallbacks
From interface android.content.ComponentCallbacks2
From interface android.preference.PreferenceFragment.OnPreferenceStartFragmentCallback
From interface android.view.KeyEvent.Callback
From interface android.view.LayoutInflater.Factory
From interface android.view.LayoutInflater.Factory2
From interface android.view.View.OnCreateContextMenuListener
From interface android.view.Window.Callback

常量

public static final String EXTRA_NO_HEADERS

添加于 API 级别 11

当启动activity时，相关的intent如果putExtra(EXTRA_NO_HEADERS,true),那么我们的header
list就不会展示出来。同时他会搭配EXTRA_SHOW_FRAGMENT 来展示我们希望的fragment.

常量值： ":android:no_headers"

public static final String EXTRA_SHOW_FRAGMENT

添加于 API 级别 11

当启动activity时，当相关的intent包含EXTRA_SHOW_FRAGMENT就通知我们的activity去展示相关的fragment.

常量值： ":android:show_fragment"

public static final String EXTRA_SHOW_FRAGMENT_ARGUMENTS

添加于 API 级别 11

当使用EXTRA_SHOW_FRAGMENT 来启动我们的activity,
这个 extra能够传递一个类型为 Bundle 的对象给我们的fragment when it is 来初始化我们的PreferenceActivity.

常量值： ":android:show_fragment_args"

public static final String EXTRA_SHOW_FRAGMENT_SHORT_TITLE

添加于 API 级别 14

当我们使用 EXTRA_SHOW_FRAGMENT,
这个extra 决定我们 fragment 的short title.

常量值： ":android:show_fragment_short_title"

public static final String EXTRA_SHOW_FRAGMENT_TITLE

添加于 API 级别 14

当我们使用 EXTRA_SHOW_FRAGMENT,这个extra
决定我们 fragment 的title.

常量值： ":android:show_fragment_title"

public static final long HEADER_ID_UNDEFINED

添加于 API 级别 11

Default value for Header.id indicating
that no identifier value is set. All other values (including those below -1) are valid.

默认Header.id

常量值： -1 (0xffffffffffffffff)

公有构造函数

public PreferenceActivity ()

添加于 API 级别 1

公有方法

public void addPreferencesFromIntent (Intent intent)

添加于 API 级别 1

该 method 从 API 级别 11 开始已经废弃。。

Adds preferences from activities that match the given Intent.

参数

public void addPreferencesFromResource (int preferencesResId)

添加于 API 级别 1

该 method 从 API 级别 11 开始已经废弃。。

Inflates the given XML resource and adds the preference hierarchy to the current preference hierarchy.

参数

public Preference findPreference (CharSequence key)

添加于 API 级别 1

该 method 从 API 级别 11 开始已经废弃。。

Finds a Preference based
on its key.

参数

返回值

• The Preference with
  the key, or null.

参见

• findPreference(CharSequence)

public void finishPreferencePanel (Fragment caller,
int resultCode, Intent resultData)

添加于 API 级别 11

Called by a preference panel fragment to finish itself.

参数

public PreferenceManager getPreferenceManager ()

添加于 API 级别 1

该 method 从 API 级别 11 开始已经废弃。。

Returns the PreferenceManager used
by this activity.

返回值

• The PreferenceManager.

public PreferenceScreen getPreferenceScreen ()

添加于 API 级别 1

该 method 从 API 级别 11 开始已经废弃。。

Gets the root of the preference hierarchy that this activity is showing.

返回值

• The PreferenceScreen that
  is the root of the preference hierarchy.

public boolean hasHeaders ()

添加于 API 级别 11

如果Activity当前展示的是 header list返回true  否则false.

public void invalidateHeaders ()

添加于 API 级别 11

重新加载headers，当你需要改变headers是调用.

public boolean isMultiPane ()

添加于 API 级别 11

如果你的activity使用多窗格来同事展示 the headers and a preference fragment返回true.

public void loadHeadersFromResource (int resid, List<PreferenceActivity.Header>
target)

添加于 API 级别 11

从你的xml文件中加载headers到list中（核心方法）

参数

public void onBuildHeaders (List<PreferenceActivity.Header>
target)

添加于 API 级别 11

当你完善你的headers是调用（核心方法）。实现它你的activity至少有一个header item, 如果有的话你的mode就自动转为 fragment mode. 当你的activity没有headers  不要调用，那么就是之前的mode

Typical implementations will use loadHeadersFromResource(int,
List) to fill in the list from a resource.

参数

public Intent onBuildStartFragmentIntent (String fragmentName, Bundle args,
int titleRes, int shortTitleRes)

添加于 API 级别 14

Called by startWithFragment(String,
Bundle, Fragment, int, int, int) when in single-pane mode, to build an Intent to launch a new activity showing the selected fragment. The default implementation constructs an Intent that re-launches the current activity with the appropriate arguments
to display the fragment.

被startWithFragment(String,
Bundle, Fragment, int, int, int) 调用产生展示相关Fragment的Intent

参数

返回值

• 返回 调用对应fragment的intent

public void onContentChanged ()

添加于 API 级别 1

内容改变时更新状态

public PreferenceActivity.Header onGetInitialHeader ()

添加于 API 级别 11

Called to determine the initial header to be shown. The default implementation simply returns the fragment of the first header. Note that the returned Header object does not actually need to exist
in your header list -- whatever its fragment is will simply be used to show for the initial UI.

初始化Header

public PreferenceActivity.Header onGetNewHeader ()

添加于 API 级别 11

Called after the header list has been updated (onBuildHeaders(List) has
been called and returned due to invalidateHeaders())
to specify the header that should now be selected. The default implementation returns null to keep whatever header is currently selected.

public void onHeaderClick (PreferenceActivity.Header header,
int position)

添加于 API 级别 11

Called when the user selects an item in the header list. The default implementation will call either startWithFragment(String,
Bundle, Fragment, int, int, int) orswitchToHeader(Header) as
appropriate.

参数

public boolean onIsHidingHeaders ()

添加于 API 级别 11

Called to determine whether the header list should be hidden. The default implementation returns the value given in EXTRA_NO_HEADERS or
false if it is not supplied. This is set to false, for example, when the activity is being re-launched to show a particular preference activity.

public boolean onIsMultiPane ()

添加于 API 级别 11

Called to determine if the activity should run in multi-pane mode. The default implementation returns true if the screen is large enough.

public boolean onPreferenceStartFragment (PreferenceFragment caller, Preference pref)

添加于 API 级别 11

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.

public boolean onPreferenceTreeClick (PreferenceScreen preferenceScreen, Preference preference)

添加于 API 级别 1

该 method 从 API 级别 11 开始已经废弃。。

public void setListFooter (View view)

添加于 API 级别 11

Set a footer that should be shown at the bottom of the header list.

public void setParentTitle (CharSequence title, CharSequence shortTitle, View.OnClickListener listener)

添加于 API 级别 11

Should be called after onCreate to ensure that the breadcrumbs, if any, were created. This prepends a title to the fragment breadcrumbs and attaches a listener to any clicks on the parent entry.

参数

public void setPreferenceScreen (PreferenceScreen preferenceScreen)

添加于 API 级别 1

该 method 从 API 级别 11 开始已经废弃。。

Sets the root of the preference hierarchy that this activity is showing.

参数

public void showBreadCrumbs (CharSequence title, CharSequence shortTitle)

添加于 API 级别 11

Change the base title of the bread crumbs for the current preferences. This will normally be called for you. See FragmentBreadCrumbs for
more information.

public void startPreferenceFragment (Fragment fragment,
boolean push)

添加于 API 级别 11

Start a new fragment.

参数

public void startPreferencePanel (String fragmentClass, Bundle args,
int titleRes, CharSequence titleText, Fragment resultTo,
int resultRequestCode)

添加于 API 级别 11

Start a new fragment containing a preference panel. If the prefences are being displayed in multi-pane mode, the given fragment class will be instantiated and placed in the appropriate pane. If running
in single-pane mode, a new activity will be launched in which to show the fragment.

参数

public void startWithFragment (String fragmentName, Bundle args, Fragment resultTo,
int resultRequestCode)

添加于 API 级别 11

Like startWithFragment(String,
Bundle, Fragment, int, int, int) but uses a 0 titleRes.

public void startWithFragment (String fragmentName, Bundle args, Fragment resultTo,
int resultRequestCode, int titleRes, int shortTitleRes)

添加于 API 级别 14

Start a new instance of this activity, showing only the given preference fragment. When launched in this mode, the header list will be hidden and the given preference fragment will be instantiated
and fill the entire activity.

参数

public void switchToHeader (PreferenceActivity.Header header)

添加于 API 级别 11

When in two-pane mode, switch to the fragment pane to show the given preference fragment.

参数

public void switchToHeader (String fragmentName, Bundle args)

添加于 API 级别 11

When in two-pane mode, switch the fragment pane to show the given preference fragment.

参数

保护方法

protected void onActivityResult (int requestCode, int resultCode, Intent data)

添加于 API 级别 1

Called when an activity you launched exits, giving you the requestCode you started it with, the resultCode it returned, and any additional data from it. The resultCode will beRESULT_CANCELED if
the activity explicitly returned that, didn‘t return any result, or crashed during its operation.

You will receive this call immediately before onResume() when your activity is re-starting.

参数

protected void onCreate (Bundle savedInstanceState)

添加于 API 级别 1

当Activity创建时调用. 继承自Activity，一般用来初始化。

This is where most initialization should go: calling setContentView(int) to
inflate the activity‘s UI, using findViewById(int) to
programmatically interact with widgets in the UI, calling managedQuery(android.net.Uri,
String[], String, String[], String) to retrieve cursors for data being displayed, etc.

You can call finish() from
within this function, in which case onDestroy() will be immediately called without any of the rest of the activity lifecycle (onStart(), onResume(), onPause(),
etc) executing.

Derived classes must call through to the super class‘s implementation of this method. If they do not, an exception will be thrown.

参数

protected void onDestroy ()

添加于 API 级别 1

Perform any final cleanup before an activity is destroyed. This can happen either because the activity is finishing (someone called finish() on
it, or because the system is temporarily destroying this instance of the activity to save space. You can distinguish between these two scenarios with the isFinishing() method.

Note: do not count on this method being called as a place for saving data! For example, if an activity is editing data in a content provider, those edits should be committed in eitheronPause() or onSaveInstanceState(Bundle),
not here. This method is usually implemented to free resources like threads that are associated with an activity, so that a destroyed activity does not leave such things around while the rest of its application is still running. There are situations where
the system will simply kill the activity‘s hosting process without calling this method (or any others) in it, so it should not be used to do things that are intended to remain around after the process goes away.

Derived classes must call through to the super class‘s implementation of this method. If they do not, an exception will be thrown.

protected void onListItemClick (ListView l, View v,
int position, long id)

添加于 API 级别 1

This method will be called when an item in the list is selected. Subclasses should override. Subclasses can call getListView().getItemAtPosition(position) if they need to access the data associated
with the selected item.

参数

protected void onNewIntent (Intent intent)

添加于 API 级别 1

This is called for activities that set launchMode to "singleTop" in their package, or if a client used the FLAG_ACTIVITY_SINGLE_TOP flag
when calling startActivity(Intent).
In either case, when the activity is re-launched while at the top of the activity stack instead of a new instance of the activity being started, onNewIntent() will be called on the existing instance with the Intent that was used to re-launch it.

An activity will always be paused before receiving a new intent, so you can count on onResume() being
called after this method.

Note that getIntent() still
returns the original Intent. You can use setIntent(Intent) to
update it to this new Intent.

参数

protected void onRestoreInstanceState (Bundle state)

添加于 API 级别 1

Ensures the list view has been created before Activity restores all of the view states.

参数

protected void onSaveInstanceState (Bundle outState)

添加于 API 级别 1

Called to retrieve per-instance state from an activity before being killed so that the state can be restored in onCreate(Bundle) or onRestoreInstanceState(Bundle) (the Bundlepopulated
by this method will be passed to both).

This method is called before an activity may be killed so that when it comes back some time in the future it can restore its state. For example, if activity B is launched in front of activity A,
and at some point activity A is killed to reclaim resources, activity A will have a chance to save the current state of its user interface via this method so that when the user returns to activity A, the state of the user interface can be restored via onCreate(Bundle) or onRestoreInstanceState(Bundle).

Do not confuse this method with activity lifecycle callbacks such as onPause(),
which is always called when an activity is being placed in the background or on its way to destruction, oronStop() which
is called before destruction. One example of when onPause() and onStop() is
called and not this method is when a user navigates back from activity B to activity A: there is no need to call onSaveInstanceState(Bundle) on
B because that particular instance will never be restored, so the system avoids calling it. An example when onPause() is
called and not onSaveInstanceState(Bundle) is
when activity B is launched in front of activity A: the system may avoid calling onSaveInstanceState(Bundle) on
activity A if it isn‘t killed during the lifetime of B since the state of the user interface of A will stay intact.

The default implementation takes care of most of the UI per-instance state for you by calling onSaveInstanceState() on
each view in the hierarchy that has an id, and by saving the id of the currently focused view (all of which is restored by the default implementation of onRestoreInstanceState(Bundle)).
If you override this method to save additional information not captured by each individual view, you will likely want to call through to the default implementation, otherwise be prepared to save all of the state of each view yourself.

If called, this method will occur before onStop().
There are no guarantees about whether it will occur before or after onPause().

参数

protected void onStop ()

添加于 API 级别 1

Called when you are no longer visible to the user. You will next receive either onRestart(), onDestroy(),
or nothing, depending on later user activity.

Note that this method may never be called, in low memory situations where the system does not have enough memory to keep your activity‘s process running after its onPause() method
is called.

Derived classes must call through to the super class‘s implementation of this method. If they do not, an exception will be thrown.