PreferenceScreen.java revision 53b6dca0375b0b40d968f9e9d3dabda3e958fc41 
1/*
2 * Copyright (C) 2015 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License
15 */
16
17package android.support.v7.preference;
18
19import android.content.Context;
20import android.util.AttributeSet;
21
22/**
23 * Represents a top-level {@link Preference} that
24 * is the root of a Preference hierarchy. A {@link PreferenceFragmentCompat}
25 * points to an instance of this class to show the preferences. To instantiate
26 * this class, use {@link PreferenceManager#createPreferenceScreen(android.content.Context)}.
27 * <ul>
28 * This class can appear in two places:
29 * <li> When a {@link PreferenceFragmentCompat} points to this, it is used as the root
30 * and is not shown (only the contained preferences are shown).
31 * <li> When it appears inside another preference hierarchy, it is shown and
32 * serves as the gateway to another screen of preferences (either by showing
33 * another screen of preferences as a {@link android.app.Dialog} or via a
34 * {@link android.content.Context#startActivity(android.content.Intent)} from the
35 * {@link Preference#getIntent()}). The children of this {@link PreferenceScreen}
36 * are NOT shown in the screen that this {@link PreferenceScreen} is shown in.
37 * Instead, a separate screen will be shown when this preference is clicked.
38 * </ul>
39 * <p>Here's an example XML layout of a PreferenceScreen:</p>
40 * <pre>
41 &lt;PreferenceScreen
42 xmlns:android="http://schemas.android.com/apk/res/android"
43 android:key="first_preferencescreen"&gt;
44 &lt;CheckBoxPreference
45 android:key="wifi enabled"
46 android:title="WiFi" /&gt;
47 &lt;PreferenceScreen
48 android:key="second_preferencescreen"
49 android:title="WiFi settings"&gt;
50 &lt;CheckBoxPreference
51 android:key="prefer wifi"
52 android:title="Prefer WiFi" /&gt;
53 ... other preferences here ...
54 &lt;/PreferenceScreen&gt;
55 &lt;/PreferenceScreen&gt; </pre>
56 * <p>
57 * In this example, the "first_preferencescreen" will be used as the root of the
58 * hierarchy and given to a {@link PreferenceFragment} or {@link PreferenceFragmentCompat}.
59 * The first screen will
60 * show preferences "WiFi" (which can be used to quickly enable/disable WiFi)
61 * and "WiFi settings". The "WiFi settings" is the "second_preferencescreen" and when
62 * clicked will show another screen of preferences such as "Prefer WiFi" (and
63 * the other preferences that are children of the "second_preferencescreen" tag).
64 *
65 * <div class="special reference">
66 * <h3>Developer Guides</h3>
67 * <p>For information about building a settings UI with Preferences,
68 * read the <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a>
69 * guide.</p>
70 * </div>
71 *
72 * @see PreferenceCategory
73 */
74public final class PreferenceScreen extends PreferenceGroup  {
75
76    /**
77     * Do NOT use this constructor, use {@link PreferenceManager#createPreferenceScreen(Context)}.
78     * @hide-
79     */
80    public PreferenceScreen(Context context, AttributeSet attrs) {
81        super(context, attrs, R.attr.preferenceScreenStyle);
82    }
83
84    @Override
85    protected void onClick() {
86        if (getIntent() != null || getFragment() != null || getPreferenceCount() == 0) {
87            return;
88        }
89        final PreferenceManager.OnNavigateToScreenListener listener =
90                getPreferenceManager().getOnNavigateToScreenListener();
91        if (listener != null) {
92            listener.onNavigateToScreen(this);
93        }
94    }
95
96    @Override
97    protected boolean isOnSameScreenAsChildren() {
98        return false;
99    }
100
101}
102