16904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler/* 26904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * Copyright (C) 2015 The Android Open Source Project 36904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * 46904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * Licensed under the Apache License, Version 2.0 (the "License"); 56904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * you may not use this file except in compliance with the License. 66904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * You may obtain a copy of the License at 76904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * 86904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * http://www.apache.org/licenses/LICENSE-2.0 96904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * 106904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * Unless required by applicable law or agreed to in writing, software 116904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * distributed under the License is distributed on an "AS IS" BASIS, 126904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 136904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * See the License for the specific language governing permissions and 146904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * limitations under the License 156904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler */ 166904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler 176904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantlerpackage android.support.v7.preference; 186904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler 196904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantlerimport android.content.Context; 20c39d9c75590eca86a5e7e32a8824ba04a0d42e9bAlan Viveretteimport android.support.annotation.RestrictTo; 213fadd62b614e4a69aefe920aac640bdb629e502eJason Monkimport android.support.v4.content.res.TypedArrayUtils; 226904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantlerimport android.util.AttributeSet; 236904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler 24c39d9c75590eca86a5e7e32a8824ba04a0d42e9bAlan Viveretteimport static android.support.annotation.RestrictTo.Scope.GROUP_ID; 25c39d9c75590eca86a5e7e32a8824ba04a0d42e9bAlan Viverette 266904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler/** 276904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * Represents a top-level {@link Preference} that 286904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * is the root of a Preference hierarchy. A {@link PreferenceFragmentCompat} 296904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * points to an instance of this class to show the preferences. To instantiate 306904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * this class, use {@link PreferenceManager#createPreferenceScreen(android.content.Context)}. 316904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * <ul> 326904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * This class can appear in two places: 336904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * <li> When a {@link PreferenceFragmentCompat} points to this, it is used as the root 346904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * and is not shown (only the contained preferences are shown). 356904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * <li> When it appears inside another preference hierarchy, it is shown and 366904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * serves as the gateway to another screen of preferences (either by showing 376904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * another screen of preferences as a {@link android.app.Dialog} or via a 386904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * {@link android.content.Context#startActivity(android.content.Intent)} from the 396904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * {@link Preference#getIntent()}). The children of this {@link PreferenceScreen} 406904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * are NOT shown in the screen that this {@link PreferenceScreen} is shown in. 416904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * Instead, a separate screen will be shown when this preference is clicked. 426904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * </ul> 436904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * <p>Here's an example XML layout of a PreferenceScreen:</p> 446904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * <pre> 456904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler <PreferenceScreen 466904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler xmlns:android="http://schemas.android.com/apk/res/android" 476904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler android:key="first_preferencescreen"> 486904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler <CheckBoxPreference 496904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler android:key="wifi enabled" 506904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler android:title="WiFi" /> 516904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler <PreferenceScreen 526904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler android:key="second_preferencescreen" 536904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler android:title="WiFi settings"> 546904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler <CheckBoxPreference 556904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler android:key="prefer wifi" 566904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler android:title="Prefer WiFi" /> 576904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler ... other preferences here ... 586904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler </PreferenceScreen> 596904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler </PreferenceScreen> </pre> 606904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * <p> 616904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * In this example, the "first_preferencescreen" will be used as the root of the 624c867cf4f0537d940d512aad679acacbcdf16765Tony Mantler * hierarchy and given to a {@link android.support.v14.preference.PreferenceFragment} 634c867cf4f0537d940d512aad679acacbcdf16765Tony Mantler * or {@link PreferenceFragmentCompat}. 646904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * The first screen will 656904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * show preferences "WiFi" (which can be used to quickly enable/disable WiFi) 666904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * and "WiFi settings". The "WiFi settings" is the "second_preferencescreen" and when 676904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * clicked will show another screen of preferences such as "Prefer WiFi" (and 686904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * the other preferences that are children of the "second_preferencescreen" tag). 696904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * 706904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * <div class="special reference"> 716904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * <h3>Developer Guides</h3> 726904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * <p>For information about building a settings UI with Preferences, 736904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * read the <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a> 746904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * guide.</p> 756904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * </div> 766904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * 776904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * @see PreferenceCategory 786904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler */ 796904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantlerpublic final class PreferenceScreen extends PreferenceGroup { 806904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler 8183deca7547a76f037c32fdc946173b4708b8d05bTony Mantler private boolean mShouldUseGeneratedIds = true; 8283deca7547a76f037c32fdc946173b4708b8d05bTony Mantler 836904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler /** 846904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler * Do NOT use this constructor, use {@link PreferenceManager#createPreferenceScreen(Context)}. 85c39d9c75590eca86a5e7e32a8824ba04a0d42e9bAlan Viverette * @hide 866904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler */ 87c39d9c75590eca86a5e7e32a8824ba04a0d42e9bAlan Viverette @RestrictTo(GROUP_ID) 886904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler public PreferenceScreen(Context context, AttributeSet attrs) { 893fadd62b614e4a69aefe920aac640bdb629e502eJason Monk super(context, attrs, TypedArrayUtils.getAttr(context, R.attr.preferenceScreenStyle, 903fadd62b614e4a69aefe920aac640bdb629e502eJason Monk android.R.attr.preferenceScreenStyle)); 916904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler } 926904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler 936904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler @Override 946904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler protected void onClick() { 956904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler if (getIntent() != null || getFragment() != null || getPreferenceCount() == 0) { 966904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler return; 976904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler } 986904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler final PreferenceManager.OnNavigateToScreenListener listener = 996904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler getPreferenceManager().getOnNavigateToScreenListener(); 1006904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler if (listener != null) { 1016904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler listener.onNavigateToScreen(this); 1026904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler } 1036904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler } 1046904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler 1056904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler @Override 1066904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler protected boolean isOnSameScreenAsChildren() { 1076904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler return false; 1086904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler } 1096904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler 11083deca7547a76f037c32fdc946173b4708b8d05bTony Mantler /** 11183deca7547a76f037c32fdc946173b4708b8d05bTony Mantler * See {@link #setShouldUseGeneratedIds(boolean)} 112f4c69e7d7d5b52335b8ea80845aa914550ebd967Tony Mantler * @return {@code true} if the adapter should use the preference IDs generated by 113f4c69e7d7d5b52335b8ea80845aa914550ebd967Tony Mantler * {@link PreferenceGroup#addPreference(Preference)} as stable item IDs 11483deca7547a76f037c32fdc946173b4708b8d05bTony Mantler */ 11583deca7547a76f037c32fdc946173b4708b8d05bTony Mantler public boolean shouldUseGeneratedIds() { 11683deca7547a76f037c32fdc946173b4708b8d05bTony Mantler return mShouldUseGeneratedIds; 11783deca7547a76f037c32fdc946173b4708b8d05bTony Mantler } 11883deca7547a76f037c32fdc946173b4708b8d05bTony Mantler 11983deca7547a76f037c32fdc946173b4708b8d05bTony Mantler /** 12019cf5bca465d5e6e1837f905a3a993dd35173df6Tony Mantler * Set whether the adapter created for this screen should attempt to use the preference IDs 12119cf5bca465d5e6e1837f905a3a993dd35173df6Tony Mantler * generated by {@link PreferenceGroup#addPreference(Preference)} as stable item IDs. Setting 12219cf5bca465d5e6e1837f905a3a993dd35173df6Tony Mantler * this to false can suppress unwanted animations if {@link Preference} objects are frequently 12319cf5bca465d5e6e1837f905a3a993dd35173df6Tony Mantler * removed from and re-added to their containing {@link PreferenceGroup}. 12483deca7547a76f037c32fdc946173b4708b8d05bTony Mantler * <p> 12583deca7547a76f037c32fdc946173b4708b8d05bTony Mantler * This method may only be called when the preference screen is not attached to the hierarchy. 12683deca7547a76f037c32fdc946173b4708b8d05bTony Mantler * <p> 12783deca7547a76f037c32fdc946173b4708b8d05bTony Mantler * Default value is {@code true}. 12883deca7547a76f037c32fdc946173b4708b8d05bTony Mantler * 12983deca7547a76f037c32fdc946173b4708b8d05bTony Mantler * @param shouldUseGeneratedIds {@code true} if the adapter should use the preference ID as a 13083deca7547a76f037c32fdc946173b4708b8d05bTony Mantler * stable ID, or {@code false} to disable the use of 13183deca7547a76f037c32fdc946173b4708b8d05bTony Mantler * stable IDs 13283deca7547a76f037c32fdc946173b4708b8d05bTony Mantler */ 13383deca7547a76f037c32fdc946173b4708b8d05bTony Mantler public void setShouldUseGeneratedIds(boolean shouldUseGeneratedIds) { 13483deca7547a76f037c32fdc946173b4708b8d05bTony Mantler if (isAttached()) { 13583deca7547a76f037c32fdc946173b4708b8d05bTony Mantler throw new IllegalStateException("Cannot change the usage of generated IDs while" + 13683deca7547a76f037c32fdc946173b4708b8d05bTony Mantler " attached to the preference hierarchy"); 13783deca7547a76f037c32fdc946173b4708b8d05bTony Mantler } 13883deca7547a76f037c32fdc946173b4708b8d05bTony Mantler mShouldUseGeneratedIds = shouldUseGeneratedIds; 13983deca7547a76f037c32fdc946173b4708b8d05bTony Mantler } 1406904f67c96a28a0e5966b4fb6d37a0ad5f136858Tony Mantler} 141