Join us on the livestream at Android Dev Summit on 7-8 November 2018, starting at 10AM PDT!

PreferenceGroup

public abstract class PreferenceGroup
extends Preference

java.lang.Object
   ↳ android.preference.Preference
     ↳ android.preference.PreferenceGroup


A container for multiple Preference objects. It is a base class for Preference objects that are parents, such as PreferenceCategory and PreferenceScreen.

Developer Guides

For information about building a settings UI with Preferences, read the Settings guide.

Summary

XML attributes

android:orderingFromXml Whether to order the Preference under this group as they appear in the XML file. 

Inherited XML attributes

Inherited constants

Public constructors

PreferenceGroup(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes)
PreferenceGroup(Context context, AttributeSet attrs, int defStyleAttr)
PreferenceGroup(Context context, AttributeSet attrs)

Public methods

void addItemFromInflater(Preference preference)

Called by the inflater to add an item to this group.

boolean addPreference(Preference preference)

Adds a Preference at the correct position based on the preference's order.

Preference findPreference(CharSequence key)

Finds a Preference based on its key.

Preference getPreference(int index)

Returns the Preference at a particular index.

int getPreferenceCount()

Returns the number of children Preferences.

boolean isOrderingAsAdded()

Whether this group is ordering preferences in the order they are added.

void notifyDependencyChange(boolean disableDependents)

Notifies any listening dependents of a change that affects the dependency.

void removeAll()

Removes all Preferences from this group.

boolean removePreference(Preference preference)

Removes a Preference from this group.

void setOrderingAsAdded(boolean orderingAsAdded)

Whether to order the Preference children of this group as they are added.

Protected methods

void dispatchRestoreInstanceState(Bundle container)

Called by restoreHierarchyState(Bundle) to retrieve the saved state for this Preference and its children.

void dispatchSaveInstanceState(Bundle container)

Called by saveHierarchyState(Bundle) to store the instance for this Preference and its children.

boolean isOnSameScreenAsChildren()

Whether this preference group should be shown on the same screen as its contained preferences.

void onAttachedToActivity()

Called when the Preference hierarchy has been attached to the PreferenceActivity.

boolean onPrepareAddPreference(Preference preference)

Prepares a Preference to be added to the group.

void onPrepareForRemoval()

Called when this Preference is being removed from the hierarchy.

Inherited methods

XML attributes

android:orderingFromXml

Whether to order the Preference under this group as they appear in the XML file. If this is false, the ordering will follow the Preference order attribute and default to alphabetic for those without the order attribute.

May be a boolean value, such as "true" or "false".

Public constructors

PreferenceGroup

added in API level 21
public PreferenceGroup (Context context, 
                AttributeSet attrs, 
                int defStyleAttr, 
                int defStyleRes)

Parameters
context Context

attrs AttributeSet

defStyleAttr int

defStyleRes int

PreferenceGroup

added in API level 1
public PreferenceGroup (Context context, 
                AttributeSet attrs, 
                int defStyleAttr)

Parameters
context Context

attrs AttributeSet

defStyleAttr int

PreferenceGroup

added in API level 1
public PreferenceGroup (Context context, 
                AttributeSet attrs)

Parameters
context Context

attrs AttributeSet

Public methods

addItemFromInflater

added in API level 1
public void addItemFromInflater (Preference preference)

Called by the inflater to add an item to this group.

Parameters
preference Preference

addPreference

added in API level 1
public boolean addPreference (Preference preference)

Adds a Preference at the correct position based on the preference's order.

Parameters
preference Preference: The preference to add.

Returns
boolean Whether the preference is now in this group.

findPreference

added in API level 1
public Preference findPreference (CharSequence key)

Finds a Preference based on its key. If two Preference share the same key (not recommended), the first to appear will be returned (to retrieve the other preference with the same key, call this method on the first preference). If this preference has the key, it will not be returned.

This will recursively search for the preference into children that are also PreferenceGroups.

Parameters
key CharSequence: The key of the preference to retrieve.

Returns
Preference The Preference with the key, or null.

getPreference

added in API level 1
public Preference getPreference (int index)

Returns the Preference at a particular index.

Parameters
index int: The index of the Preference to retrieve.

Returns
Preference The Preference.

getPreferenceCount

added in API level 1
public int getPreferenceCount ()

Returns the number of children Preferences.

Returns
int The number of preference children in this group.

isOrderingAsAdded

added in API level 1
public boolean isOrderingAsAdded ()

Whether this group is ordering preferences in the order they are added.

Returns
boolean Whether this group orders based on the order the children are added.

notifyDependencyChange

added in API level 1
public void notifyDependencyChange (boolean disableDependents)

Notifies any listening dependents of a change that affects the dependency.

Parameters
disableDependents boolean: Whether this Preference should disable its dependents.

removeAll

added in API level 1
public void removeAll ()

Removes all Preferences from this group.

removePreference

added in API level 1
public boolean removePreference (Preference preference)

Removes a Preference from this group.

Parameters
preference Preference: The preference to remove.

Returns
boolean Whether the preference was found and removed.

setOrderingAsAdded

added in API level 1
public void setOrderingAsAdded (boolean orderingAsAdded)

Whether to order the Preference children of this group as they are added. If this is false, the ordering will follow each Preference order and default to alphabetic for those without an order.

If this is called after preferences are added, they will not be re-ordered in the order they were added, hence call this method early on.

Parameters
orderingAsAdded boolean: Whether to order according to the order added.

Protected methods

dispatchRestoreInstanceState

added in API level 1
protected void dispatchRestoreInstanceState (Bundle container)

Called by restoreHierarchyState(Bundle) to retrieve the saved state for this Preference and its children. May be overridden to modify how restoring happens to the children of a Preference. For example, some Preference objects may not want to save state for their children.

Parameters
container Bundle: The Bundle that holds the previously saved state.

dispatchSaveInstanceState

added in API level 1
protected void dispatchSaveInstanceState (Bundle container)

Called by saveHierarchyState(Bundle) to store the instance for this Preference and its children. May be overridden to modify how the save happens for children. For example, some Preference objects may want to not store an instance for their children.

Parameters
container Bundle: The Bundle in which to save the instance of this Preference.

isOnSameScreenAsChildren

added in API level 1
protected boolean isOnSameScreenAsChildren ()

Whether this preference group should be shown on the same screen as its contained preferences.

Returns
boolean True if the contained preferences should be shown on the same screen as this preference.

onAttachedToActivity

added in API level 1
protected void onAttachedToActivity ()

Called when the Preference hierarchy has been attached to the PreferenceActivity. This can also be called when this Preference has been attached to a group that was already attached to the PreferenceActivity.

onPrepareAddPreference

added in API level 1
protected boolean onPrepareAddPreference (Preference preference)

Prepares a Preference to be added to the group.

Parameters
preference Preference: The preference to add.

Returns
boolean Whether to allow adding the preference (true), or not (false).

onPrepareForRemoval

added in API level 1
protected void onPrepareForRemoval ()

Called when this Preference is being removed from the hierarchy. You should remove any references to this Preference that you know about. Make sure to call through to the superclass implementation.