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