public class Preference extends Object implements Comparable<Preference>
PreferenceActivity
in the form of a
ListView
. This class provides the View
to be displayed in
the activity and associates with a SharedPreferences
to
store/retrieve the preference data.
When specifying a preference hierarchy in XML, each element can point to a
subclass of Preference
, similar to the view hierarchy and layouts.
This class contains a key
that will be used as the key into the
SharedPreferences
. It is up to the subclass to decide how to store
the value.
For information about building a settings UI with Preferences, read the Settings guide.
Modifier and Type | Class and Description |
---|---|
static class |
Preference.BaseSavedState
A base class for managing the instance state of a
Preference . |
static interface |
Preference.OnPreferenceChangeListener
Interface definition for a callback to be invoked when the value of this
Preference has been changed by the user and is
about to be set and/or persisted. |
static interface |
Preference.OnPreferenceClickListener
Interface definition for a callback to be invoked when a
Preference is
clicked. |
Modifier and Type | Field and Description |
---|---|
static int |
DEFAULT_ORDER
Specify for
setOrder(int) if a specific order is not required. |
Constructor and Description |
---|
Preference(Context context)
Constructor to create a Preference.
|
Preference(Context context,
AttributeSet attrs)
Constructor that is called when inflating a Preference from XML.
|
Preference(Context context,
AttributeSet attrs,
int defStyle)
Perform inflation from XML and apply a class-specific base style.
|
Modifier and Type | Method and Description |
---|---|
protected boolean |
callChangeListener(Object newValue)
Call this method after the user changes the preference, but before the
internal state is set.
|
int |
compareTo(Preference another)
Compares Preference objects based on order (if set), otherwise alphabetically on the titles.
|
protected Preference |
findPreferenceInHierarchy(String key)
Finds a Preference in this hierarchy (the whole thing,
even above/below your
PreferenceScreen screen break) with the given
key. |
Context |
getContext()
Returns the
Context of this Preference. |
String |
getDependency()
Returns the key of the dependency on this Preference.
|
SharedPreferences.Editor |
getEditor()
Returns an
SharedPreferences.Editor where this Preference can
save its value(s). |
Bundle |
getExtras()
Return the extras Bundle object associated with this preference, creating
a new Bundle if there currently isn't one.
|
String |
getFragment()
Return the fragment class name associated with this Preference.
|
Drawable |
getIcon()
Returns the icon of this Preference.
|
Intent |
getIntent()
Return the
Intent associated with this Preference. |
String |
getKey()
Gets the key for this Preference, which is also the key used for storing
values into SharedPreferences.
|
int |
getLayoutResource()
Gets the layout resource that will be shown as the
View for this Preference. |
Preference.OnPreferenceChangeListener |
getOnPreferenceChangeListener()
Returns the callback to be invoked when this Preference is changed by the
user (but before the internal state has been updated).
|
Preference.OnPreferenceClickListener |
getOnPreferenceClickListener()
Returns the callback to be invoked when this Preference is clicked.
|
int |
getOrder()
Gets the order of this Preference with respect to other Preference objects
on the same level.
|
protected boolean |
getPersistedBoolean(boolean defaultReturnValue)
Attempts to get a persisted boolean from the
SharedPreferences . |
protected float |
getPersistedFloat(float defaultReturnValue)
Attempts to get a persisted float from the
SharedPreferences . |
protected int |
getPersistedInt(int defaultReturnValue)
Attempts to get a persisted int from the
SharedPreferences . |
protected long |
getPersistedLong(long defaultReturnValue)
Attempts to get a persisted long from the
SharedPreferences . |
protected String |
getPersistedString(String defaultReturnValue)
Attempts to get a persisted String from the
SharedPreferences . |
protected Set<String> |
getPersistedStringSet(Set<String> defaultReturnValue)
Attempts to get a persisted set of Strings from the
SharedPreferences . |
PreferenceManager |
getPreferenceManager()
Gets the
PreferenceManager that manages this Preference object's tree. |
SharedPreferences |
getSharedPreferences()
Returns the
SharedPreferences where this Preference can read its
value(s). |
boolean |
getShouldDisableView()
Checks whether this Preference should disable its view when it's action is disabled.
|
CharSequence |
getSummary()
Returns the summary of this Preference.
|
CharSequence |
getTitle()
Returns the title of this Preference.
|
int |
getTitleRes()
Returns the title resource ID of this Preference.
|
View |
getView(View convertView,
ViewGroup parent)
Gets the View that will be shown in the
PreferenceActivity . |
int |
getWidgetLayoutResource()
Gets the layout resource for the controllable widget portion of this Preference.
|
boolean |
hasKey()
Checks whether this Preference has a valid key.
|
boolean |
isEnabled()
Checks whether this Preference should be enabled in the list.
|
boolean |
isPersistent()
Checks whether this Preference is persistent.
|
boolean |
isSelectable()
Checks whether this Preference should be selectable in the list.
|
protected void |
notifyChanged()
Should be called when the data of this
Preference has changed. |
void |
notifyDependencyChange(boolean disableDependents)
Notifies any listening dependents of a change that affects the
dependency.
|
protected void |
notifyHierarchyChanged()
Should be called when a Preference has been
added/removed from this group, or the ordering should be
re-evaluated.
|
protected void |
onAttachedToActivity()
Called when the Preference hierarchy has been attached to the
PreferenceActivity . |
protected void |
onAttachedToHierarchy(PreferenceManager preferenceManager)
Called when this Preference has been attached to a Preference hierarchy.
|
protected void |
onBindView(View view)
Binds the created View to the data for this Preference.
|
protected void |
onClick()
Processes a click on the preference.
|
protected View |
onCreateView(ViewGroup parent)
Creates the View to be shown for this Preference in the
PreferenceActivity . |
void |
onDependencyChanged(Preference dependency,
boolean disableDependent)
Called when the dependency changes.
|
protected Object |
onGetDefaultValue(TypedArray a,
int index)
Called when a Preference is being inflated and the default value
attribute needs to be read.
|
boolean |
onKey(View v,
int keyCode,
KeyEvent event)
Allows a Preference to intercept key events without having focus.
|
protected void |
onPrepareForRemoval()
Called when this Preference is being removed from the hierarchy.
|
protected void |
onRestoreInstanceState(Parcelable state)
Hook allowing a Preference to re-apply a representation of its internal
state that had previously been generated by
onSaveInstanceState() . |
protected Parcelable |
onSaveInstanceState()
Hook allowing a Preference to generate a representation of its internal
state that can later be used to create a new instance with that same
state.
|
protected void |
onSetInitialValue(boolean restorePersistedValue,
Object defaultValue)
Implement this to set the initial value of the Preference.
|
Bundle |
peekExtras()
Return the extras Bundle object associated with this preference,
returning null if there is not currently one.
|
protected boolean |
persistBoolean(boolean value)
Attempts to persist a boolean to the
SharedPreferences . |
protected boolean |
persistFloat(float value)
Attempts to persist a float to the
SharedPreferences . |
protected boolean |
persistInt(int value)
Attempts to persist an int to the
SharedPreferences . |
protected boolean |
persistLong(long value)
Attempts to persist a long to the
SharedPreferences . |
protected boolean |
persistString(String value)
Attempts to persist a String to the
SharedPreferences . |
protected boolean |
persistStringSet(Set<String> values)
Attempts to persist a set of Strings to the
SharedPreferences . |
void |
restoreHierarchyState(Bundle container)
Restore this Preference hierarchy's previously saved state from the given container.
|
void |
saveHierarchyState(Bundle container)
Store this Preference hierarchy's frozen state into the given container.
|
void |
setDefaultValue(Object defaultValue)
Sets the default value for this Preference, which will be set either if
persistence is off or persistence is on and the preference is not found
in the persistent storage.
|
void |
setDependency(String dependencyKey)
Sets the key of a Preference that this Preference will depend on.
|
void |
setEnabled(boolean enabled)
Sets whether this Preference is enabled.
|
void |
setFragment(String fragment)
Sets the class name of a fragment to be shown when this Preference is clicked.
|
void |
setIcon(Drawable icon)
Sets the icon for this Preference with a Drawable.
|
void |
setIcon(int iconResId)
Sets the icon for this Preference with a resource ID.
|
void |
setIntent(Intent intent)
Sets an
Intent to be used for
Context.startActivity(Intent) when this Preference is clicked. |
void |
setKey(String key)
Sets the key for this Preference, which is used as a key to the
SharedPreferences . |
void |
setLayoutResource(int layoutResId)
Sets the layout resource that is inflated as the
View to be shown
for this Preference. |
void |
setOnPreferenceChangeListener(Preference.OnPreferenceChangeListener onPreferenceChangeListener)
Sets the callback to be invoked when this Preference is changed by the
user (but before the internal state has been updated).
|
void |
setOnPreferenceClickListener(Preference.OnPreferenceClickListener onPreferenceClickListener)
Sets the callback to be invoked when this Preference is clicked.
|
void |
setOrder(int order)
Sets the order of this Preference with respect to other
Preference objects on the same level.
|
void |
setPersistent(boolean persistent)
Sets whether this Preference is persistent.
|
void |
setSelectable(boolean selectable)
Sets whether this Preference is selectable.
|
void |
setShouldDisableView(boolean shouldDisableView)
Sets whether this Preference should disable its view when it gets
disabled.
|
void |
setSummary(CharSequence summary)
Sets the summary for this Preference with a CharSequence.
|
void |
setSummary(int summaryResId)
Sets the summary for this Preference with a resource ID.
|
void |
setTitle(CharSequence title)
Sets the title for this Preference with a CharSequence.
|
void |
setTitle(int titleResId)
Sets the title for this Preference with a resource ID.
|
void |
setWidgetLayoutResource(int widgetLayoutResId)
Sets The layout for the controllable widget portion of this Preference.
|
boolean |
shouldCommit()
Returns whether the
Preference should commit its saved value(s) in
getEditor() . |
boolean |
shouldDisableDependents()
Checks whether this preference's dependents should currently be
disabled.
|
protected boolean |
shouldPersist()
Checks whether, at the given time this method is called,
this Preference should store/restore its value(s) into the
SharedPreferences . |
String |
toString()
Returns a string containing a concise, human-readable description of this
object.
|
public static final int DEFAULT_ORDER
setOrder(int)
if a specific order is not required.public Preference(Context context, AttributeSet attrs, int defStyle)
CheckBoxPreference
constructor calls this version of the super class constructor and
supplies android.R.attr.checkBoxPreferenceStyle
for defStyle.
This allows the theme's checkbox preference style to modify all of the base
preference attributes as well as the CheckBoxPreference
class's
attributes.context
- The Context this is associated with, through which it can
access the current theme, resources, SharedPreferences
,
etc.attrs
- The attributes of the XML tag that is inflating the preference.defStyle
- The default style to apply to this preference. If 0, no style
will be applied (beyond what is included in the theme). This
may either be an attribute resource, whose value will be
retrieved from the current theme, or an explicit style
resource.Preference(Context, AttributeSet)
public Preference(Context context, AttributeSet attrs)
context
- The Context this is associated with, through which it can
access the current theme, resources, SharedPreferences
,
etc.attrs
- The attributes of the XML tag that is inflating the
preference.Preference(Context, AttributeSet, int)
public Preference(Context context)
context
- The Context in which to store Preference values.protected Object onGetDefaultValue(TypedArray a, int index)
For example, if the value type is String, the body of the method would
proxy to TypedArray.getString(int)
.
a
- The set of attributes.index
- The index of the default value attribute.public void setIntent(Intent intent)
Intent
to be used for
Context.startActivity(Intent)
when this Preference is clicked.intent
- The intent associated with this Preference.public Intent getIntent()
Intent
associated with this Preference.Intent
last set via setIntent(Intent)
or XML.public void setFragment(String fragment)
fragment
- The class name of the fragment associated with this Preference.public String getFragment()
setFragment(java.lang.String)
or XML.public Bundle getExtras()
public Bundle peekExtras()
public void setLayoutResource(int layoutResId)
View
to be shown
for this Preference. In most cases, the default layout is sufficient for
custom Preference objects and only the widget layout needs to be changed.
This layout should contain a ViewGroup
with ID
android.R.id#widget_frame
to be the parent of the specific widget
for this Preference. It should similarly contain
android.R.id#title
and android.R.id#summary
.
layoutResId
- The layout resource ID to be inflated and returned as
a View
.setWidgetLayoutResource(int)
public int getLayoutResource()
View
for this Preference.public void setWidgetLayoutResource(int widgetLayoutResId)
CheckBoxPreference
would specify a custom layout (consisting of just the CheckBox) here,
instead of creating its own main layout.widgetLayoutResId
- The layout resource ID to be inflated into the
main layout.setLayoutResource(int)
public int getWidgetLayoutResource()
public View getView(View convertView, ViewGroup parent)
PreferenceActivity
.convertView
- The old View to reuse, if possible. Note: You should
check that this View is non-null and of an appropriate type
before using. If it is not possible to convert this View to
display the correct data, this method can create a new View.parent
- The parent that this View will eventually be attached to.onCreateView(ViewGroup)
,
onBindView(View)
protected View onCreateView(ViewGroup parent)
PreferenceActivity
. The default behavior is to inflate the main
layout of this Preference (see setLayoutResource(int)
. If
changing this behavior, please specify a ViewGroup
with ID
android.R.id#widget_frame
.
Make sure to call through to the superclass's implementation.
parent
- The parent that this View will eventually be attached to.onBindView(View)
protected void onBindView(View view)
This is a good place to grab references to custom Views in the layout and set properties on them.
Make sure to call through to the superclass's implementation.
view
- The View that shows this Preference.onCreateView(ViewGroup)
public void setOrder(int order)
PreferenceGroup.setOrderingAsAdded(boolean)
can be used to order
Preference objects based on the order they appear in the XML.order
- The order for this Preference. A lower value will be shown
first. Use DEFAULT_ORDER
to sort alphabetically or
allow ordering from XML.PreferenceGroup.setOrderingAsAdded(boolean)
,
DEFAULT_ORDER
public int getOrder()
setOrder(int)
public void setTitle(CharSequence title)
android.R.id#title
within the View created by
onCreateView(ViewGroup)
.title
- The title for this Preference.public void setTitle(int titleResId)
titleResId
- The title as a resource ID.setTitle(CharSequence)
public int getTitleRes()
setTitle(int)
public CharSequence getTitle()
setTitle(CharSequence)
public void setIcon(Drawable icon)
android.R.id#icon
within the View created by
onCreateView(ViewGroup)
.icon
- The optional icon for this Preference.public void setIcon(int iconResId)
iconResId
- The icon as a resource ID.setIcon(Drawable)
public Drawable getIcon()
setIcon(Drawable)
public CharSequence getSummary()
setSummary(CharSequence)
public void setSummary(CharSequence summary)
summary
- The summary for the preference.public void setSummary(int summaryResId)
summaryResId
- The summary as a resource.setSummary(CharSequence)
public void setEnabled(boolean enabled)
enabled
- Set true to enable it.public boolean isEnabled()
public void setSelectable(boolean selectable)
selectable
- Set true to make it selectable.public boolean isSelectable()
public void setShouldDisableView(boolean shouldDisableView)
For example, set this and setEnabled(boolean)
to false for
preferences that are only displaying information and 1) should not be
clickable 2) should not have the view set to the disabled state.
shouldDisableView
- Set true if this preference should disable its view
when the preference is disabled.public boolean getShouldDisableView()
setShouldDisableView(boolean)
protected void onClick()
SharedPreferences
. However, the overridden method should
call callChangeListener(Object)
to make sure the client wants to
update the preference's state with the new value.public void setKey(String key)
SharedPreferences
. This should be unique for the package.key
- The key for the preference.public String getKey()
public boolean hasKey()
public boolean isPersistent()
SharedPreferences
storage.protected boolean shouldPersist()
SharedPreferences
. This, at minimum, checks whether this
Preference is persistent and it currently has a key. Before you
save/restore from the SharedPreferences
, check this first.public void setPersistent(boolean persistent)
SharedPreferences
storage.persistent
- Set true if it should store its value(s) into the SharedPreferences
.protected boolean callChangeListener(Object newValue)
newValue
- The new value of this Preference.public void setOnPreferenceChangeListener(Preference.OnPreferenceChangeListener onPreferenceChangeListener)
onPreferenceChangeListener
- The callback to be invoked.public Preference.OnPreferenceChangeListener getOnPreferenceChangeListener()
public void setOnPreferenceClickListener(Preference.OnPreferenceClickListener onPreferenceClickListener)
onPreferenceClickListener
- The callback to be invoked.public Preference.OnPreferenceClickListener getOnPreferenceClickListener()
public boolean onKey(View v, int keyCode, KeyEvent event)
public Context getContext()
Context
of this Preference.
Each Preference in a Preference hierarchy can be
from different Context (for example, if multiple activities provide preferences into a single
PreferenceActivity
). This Context will be used to save the Preference values.public SharedPreferences getSharedPreferences()
SharedPreferences
where this Preference can read its
value(s). Usually, it's easier to use one of the helper read methods:
getPersistedBoolean(boolean)
, getPersistedFloat(float)
,
getPersistedInt(int)
, getPersistedLong(long)
,
getPersistedString(String)
. To save values, see
getEditor()
.
In some cases, writes to the getEditor()
will not be committed
right away and hence not show up in the returned
SharedPreferences
, this is intended behavior to improve
performance.
SharedPreferences
where this Preference reads its
value(s), or null if it isn't attached to a Preference hierarchy.getEditor()
public SharedPreferences.Editor getEditor()
SharedPreferences.Editor
where this Preference can
save its value(s). Usually it's easier to use one of the helper save
methods: persistBoolean(boolean)
, persistFloat(float)
,
persistInt(int)
, persistLong(long)
,
persistString(String)
. To read values, see
getSharedPreferences()
. If shouldCommit()
returns
true, it is this Preference's responsibility to commit.
In some cases, writes to this will not be committed right away and hence not show up in the SharedPreferences, this is intended behavior to improve performance.
SharedPreferences.Editor
where this preference saves
its value(s), or null if it isn't attached to a Preference
hierarchy.shouldCommit()
,
getSharedPreferences()
public boolean shouldCommit()
Preference
should commit its saved value(s) in
getEditor()
. This may return false in situations where batch
committing is being done (by the manager) to improve performance.getEditor()
public int compareTo(Preference another)
compareTo
in interface Comparable<Preference>
another
- The Preference to compare to this one.protected void notifyChanged()
Preference
has changed.protected void notifyHierarchyChanged()
public PreferenceManager getPreferenceManager()
PreferenceManager
that manages this Preference object's tree.PreferenceManager
.protected void onAttachedToHierarchy(PreferenceManager preferenceManager)
preferenceManager
- The PreferenceManager of the hierarchy.protected void onAttachedToActivity()
PreferenceActivity
. This can also be called when this
Preference has been attached to a group that was already attached
to the PreferenceActivity
.protected Preference findPreferenceInHierarchy(String key)
PreferenceScreen
screen break) with the given
key.
This only functions after we have been attached to a hierarchy.
key
- The key of the Preference to find.public void notifyDependencyChange(boolean disableDependents)
disableDependents
- Whether this Preference should disable
its dependents.public void onDependencyChanged(Preference dependency, boolean disableDependent)
dependency
- The Preference that this Preference depends on.disableDependent
- Set true to disable this Preference.public boolean shouldDisableDependents()
public void setDependency(String dependencyKey)
dependencyKey
- The key of the Preference that this depends on.public String getDependency()
setDependency(String)
protected void onPrepareForRemoval()
public void setDefaultValue(Object defaultValue)
defaultValue
- The default value.protected void onSetInitialValue(boolean restorePersistedValue, Object defaultValue)
If restorePersistedValue is true, you should restore the
Preference value from the SharedPreferences
. If
restorePersistedValue is false, you should set the Preference
value to defaultValue that is given (and possibly store to SharedPreferences
if shouldPersist()
is true).
This may not always be called. One example is if it should not persist but there is no default value given.
restorePersistedValue
- True to restore the persisted value;
false to use the given defaultValue.defaultValue
- The default value for this Preference. Only use this
if restorePersistedValue is false.protected boolean persistString(String value)
SharedPreferences
.
This will check if this Preference is persistent, get an editor from
the PreferenceManager
, put in the string, and check if we should commit (and
commit if so).
value
- The value to persist.getPersistedString(String)
protected String getPersistedString(String defaultReturnValue)
SharedPreferences
.
This will check if this Preference is persistent, get the SharedPreferences
from the PreferenceManager
, and get the value.
defaultReturnValue
- The default value to return if either the
Preference is not persistent or the Preference is not in the
shared preferences.persistString(String)
protected boolean persistStringSet(Set<String> values)
SharedPreferences
.
This will check if this Preference is persistent, get an editor from
the PreferenceManager
, put in the strings, and check if we should commit (and
commit if so).
values
- The values to persist.#getPersistedString(Set)
protected Set<String> getPersistedStringSet(Set<String> defaultReturnValue)
SharedPreferences
.
This will check if this Preference is persistent, get the SharedPreferences
from the PreferenceManager
, and get the value.
defaultReturnValue
- The default value to return if either the
Preference is not persistent or the Preference is not in the
shared preferences.persistStringSet(Set)
protected boolean persistInt(int value)
SharedPreferences
.value
- The value to persist.persistString(String)
,
getPersistedInt(int)
protected int getPersistedInt(int defaultReturnValue)
SharedPreferences
.defaultReturnValue
- The default value to return if either this
Preference is not persistent or this Preference is not in the
SharedPreferences.getPersistedString(String)
,
persistInt(int)
protected boolean persistFloat(float value)
SharedPreferences
.value
- The value to persist.persistString(String)
,
getPersistedFloat(float)
protected float getPersistedFloat(float defaultReturnValue)
SharedPreferences
.defaultReturnValue
- The default value to return if either this
Preference is not persistent or this Preference is not in the
SharedPreferences.getPersistedString(String)
,
persistFloat(float)
protected boolean persistLong(long value)
SharedPreferences
.value
- The value to persist.persistString(String)
,
getPersistedLong(long)
protected long getPersistedLong(long defaultReturnValue)
SharedPreferences
.defaultReturnValue
- The default value to return if either this
Preference is not persistent or this Preference is not in the
SharedPreferences.getPersistedString(String)
,
persistLong(long)
protected boolean persistBoolean(boolean value)
SharedPreferences
.value
- The value to persist.persistString(String)
,
getPersistedBoolean(boolean)
protected boolean getPersistedBoolean(boolean defaultReturnValue)
SharedPreferences
.defaultReturnValue
- The default value to return if either this
Preference is not persistent or this Preference is not in the
SharedPreferences.getPersistedString(String)
,
persistBoolean(boolean)
public String toString()
Object
getClass().getName() + '@' + Integer.toHexString(hashCode())
See Writing a useful
toString
method
if you intend implementing your own toString
method.
public void saveHierarchyState(Bundle container)
container
- The Bundle in which to save the instance of this Preference.restoreHierarchyState(android.os.Bundle)
,
onSaveInstanceState()
protected Parcelable onSaveInstanceState()
onRestoreInstanceState(android.os.Parcelable)
,
saveHierarchyState(android.os.Bundle)
public void restoreHierarchyState(Bundle container)
container
- The Bundle that holds the previously saved state.saveHierarchyState(android.os.Bundle)
,
onRestoreInstanceState(android.os.Parcelable)
protected void onRestoreInstanceState(Parcelable state)
onSaveInstanceState()
.
This function will never be called with a null state.state
- The saved state that had previously been returned by
onSaveInstanceState()
.onSaveInstanceState()
,
restoreHierarchyState(android.os.Bundle)