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.support.v4.content.res.TypedArrayUtils;
21import android.util.AttributeSet;
22
23/**
24 * Represents a top-level {@link Preference} that
25 * is the root of a Preference hierarchy. A {@link PreferenceFragmentCompat}
26 * points to an instance of this class to show the preferences. To instantiate
27 * this class, use {@link PreferenceManager#createPreferenceScreen(android.content.Context)}.
28 * <ul>
29 * This class can appear in two places:
30 * <li> When a {@link PreferenceFragmentCompat} points to this, it is used as the root
31 * and is not shown (only the contained preferences are shown).
32 * <li> When it appears inside another preference hierarchy, it is shown and
33 * serves as the gateway to another screen of preferences (either by showing
34 * another screen of preferences as a {@link android.app.Dialog} or via a
35 * {@link android.content.Context#startActivity(android.content.Intent)} from the
36 * {@link Preference#getIntent()}). The children of this {@link PreferenceScreen}
37 * are NOT shown in the screen that this {@link PreferenceScreen} is shown in.
38 * Instead, a separate screen will be shown when this preference is clicked.
39 * </ul>
40 * <p>Here's an example XML layout of a PreferenceScreen:</p>
41 * <pre>
42 &lt;PreferenceScreen
43 xmlns:android="http://schemas.android.com/apk/res/android"
44 android:key="first_preferencescreen"&gt;
45 &lt;CheckBoxPreference
46 android:key="wifi enabled"
47 android:title="WiFi" /&gt;
48 &lt;PreferenceScreen
49 android:key="second_preferencescreen"
50 android:title="WiFi settings"&gt;
51 &lt;CheckBoxPreference
52 android:key="prefer wifi"
53 android:title="Prefer WiFi" /&gt;
54 ... other preferences here ...
55 &lt;/PreferenceScreen&gt;
56 &lt;/PreferenceScreen&gt; </pre>
57 * <p>
58 * In this example, the "first_preferencescreen" will be used as the root of the
59 * hierarchy and given to a {@link android.support.v14.preference.PreferenceFragment}
60 * or {@link PreferenceFragmentCompat}.
61 * The first screen will
62 * show preferences "WiFi" (which can be used to quickly enable/disable WiFi)
63 * and "WiFi settings". The "WiFi settings" is the "second_preferencescreen" and when
64 * clicked will show another screen of preferences such as "Prefer WiFi" (and
65 * the other preferences that are children of the "second_preferencescreen" tag).
66 *
67 * <div class="special reference">
68 * <h3>Developer Guides</h3>
69 * <p>For information about building a settings UI with Preferences,
70 * read the <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a>
71 * guide.</p>
72 * </div>
73 *
74 * @see PreferenceCategory
75 */
76public final class PreferenceScreen extends PreferenceGroup  {
77
78    private boolean mShouldUseGeneratedIds = true;
79
80    /**
81     * Do NOT use this constructor, use {@link PreferenceManager#createPreferenceScreen(Context)}.
82     * @hide-
83     */
84    public PreferenceScreen(Context context, AttributeSet attrs) {
85        super(context, attrs, TypedArrayUtils.getAttr(context, R.attr.preferenceScreenStyle,
86                android.R.attr.preferenceScreenStyle));
87    }
88
89    @Override
90    protected void onClick() {
91        if (getIntent() != null || getFragment() != null || getPreferenceCount() == 0) {
92            return;
93        }
94        final PreferenceManager.OnNavigateToScreenListener listener =
95                getPreferenceManager().getOnNavigateToScreenListener();
96        if (listener != null) {
97            listener.onNavigateToScreen(this);
98        }
99    }
100
101    @Override
102    protected boolean isOnSameScreenAsChildren() {
103        return false;
104    }
105
106    /**
107     * See {@link #setShouldUseGeneratedIds(boolean)}
108     * @return {@code true} if the adapter should use the preference IDs generated by
109     *         {@link PreferenceGroup#addPreference(Preference)} as stable item IDs
110     */
111    public boolean shouldUseGeneratedIds() {
112        return mShouldUseGeneratedIds;
113    }
114
115    /**
116     * Set whether the adapter created for this screen should attempt to use the preference IDs
117     * generated by {@link PreferenceGroup#addPreference(Preference)} as stable item IDs. Setting
118     * this to false can suppress unwanted animations if {@link Preference} objects are frequently
119     * removed from and re-added to their containing {@link PreferenceGroup}.
120     * <p>
121     * This method may only be called when the preference screen is not attached to the hierarchy.
122     * <p>
123     * Default value is {@code true}.
124     *
125     * @param shouldUseGeneratedIds {@code true} if the adapter should use the preference ID as a
126     *                                          stable ID, or {@code false} to disable the use of
127     *                                          stable IDs
128     */
129    public void setShouldUseGeneratedIds(boolean shouldUseGeneratedIds) {
130        if (isAttached()) {
131            throw new IllegalStateException("Cannot change the usage of generated IDs while" +
132                    " attached to the preference hierarchy");
133        }
134        mShouldUseGeneratedIds = shouldUseGeneratedIds;
135    }
136}
137