PreferenceScreen.java revision 6904f67c96a28a0e5966b4fb6d37a0ad5f136858
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.v7.widget.RecyclerView; 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 <PreferenceScreen 43 xmlns:android="http://schemas.android.com/apk/res/android" 44 android:key="first_preferencescreen"> 45 <CheckBoxPreference 46 android:key="wifi enabled" 47 android:title="WiFi" /> 48 <PreferenceScreen 49 android:key="second_preferencescreen" 50 android:title="WiFi settings"> 51 <CheckBoxPreference 52 android:key="prefer wifi" 53 android:title="Prefer WiFi" /> 54 ... other preferences here ... 55 </PreferenceScreen> 56 </PreferenceScreen> </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 PreferenceFragment} or {@link PreferenceFragmentCompat}. 60 * The first screen will 61 * show preferences "WiFi" (which can be used to quickly enable/disable WiFi) 62 * and "WiFi settings". The "WiFi settings" is the "second_preferencescreen" and when 63 * clicked will show another screen of preferences such as "Prefer WiFi" (and 64 * the other preferences that are children of the "second_preferencescreen" tag). 65 * 66 * <div class="special reference"> 67 * <h3>Developer Guides</h3> 68 * <p>For information about building a settings UI with Preferences, 69 * read the <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a> 70 * guide.</p> 71 * </div> 72 * 73 * @see PreferenceCategory 74 */ 75public final class PreferenceScreen extends PreferenceGroup { 76 77 private RecyclerView.Adapter mRootAdapter; 78 79 /** 80 * Do NOT use this constructor, use {@link PreferenceManager#createPreferenceScreen(Context)}. 81 * @hide- 82 */ 83 public PreferenceScreen(Context context, AttributeSet attrs) { 84 super(context, attrs, R.attr.preferenceScreenStyle); 85 } 86 87 /** 88 * Returns an adapter that can be attached to a {@link PreferenceFragment} 89 * or {@link PreferenceFragmentCompat} to show the preferences contained in this 90 * {@link PreferenceScreen}. 91 * <p> 92 * This {@link PreferenceScreen} will NOT appear in the returned adapter, instead 93 * it appears in the hierarchy above this {@link PreferenceScreen}. 94 * 95 * @return An adapter that manages the {@link Preference} contained in this 96 * {@link PreferenceScreen}. 97 */ 98 public final RecyclerView.Adapter getAdapter() { 99 if (mRootAdapter == null) { 100 mRootAdapter = onCreateAdapter(); 101 } 102 103 return mRootAdapter; 104 } 105 106 /** 107 * Creates the root adapter. 108 * 109 * @return An adapter that contains the preferences contained in this {@link PreferenceScreen}. 110 * @see #getAdapter() 111 */ 112 protected RecyclerView.Adapter onCreateAdapter() { 113 return new PreferenceGroupAdapter(this); 114 } 115 116 @Override 117 protected void onClick() { 118 if (getIntent() != null || getFragment() != null || getPreferenceCount() == 0) { 119 return; 120 } 121 final PreferenceManager.OnNavigateToScreenListener listener = 122 getPreferenceManager().getOnNavigateToScreenListener(); 123 if (listener != null) { 124 listener.onNavigateToScreen(this); 125 } 126 } 127 128 @Override 129 protected boolean isOnSameScreenAsChildren() { 130 return false; 131 } 132 133} 134