to top
Android APIs
public abstract class

PreferenceGroup

extends Preference
java.lang.Object
   ↳ android.preference.Preference
     ↳ android.preference.PreferenceGroup
Known Direct Subclasses

Class Overview

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
Attribute Name Related Method Description
android:orderingFromXml Whether to order the Preference under this group as they appear in the XML file. 
[Expand]
Inherited XML Attributes
From class android.preference.Preference
[Expand]
Inherited Constants
From class android.preference.Preference
Public Constructors
PreferenceGroup(Context context, AttributeSet attrs, int defStyle)
PreferenceGroup(Context context, AttributeSet attrs)
Public Methods
void addItemFromInflater(Preference preference)
Called by the inflater to add an item to this group.
abstract void addItemFromInflater(T child)
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 removeAll()
Removes all Preferences from this group.
boolean removePreference(Preference preference)
Removes a Preference from this group.
void setEnabled(boolean enabled)
Sets whether this Preference is enabled.
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.
[Expand]
Inherited Methods
From class android.preference.Preference
From class java.lang.Object
From interface java.lang.Comparable

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.

Must be a boolean value, either "true" or "false".

This may also be a reference to a resource (in the form "@[package:]type:name") or theme attribute (in the form "?[package:][type:]name") containing a value of this type.

This corresponds to the global attribute resource symbol orderingFromXml.

Related Methods

Public Constructors

public PreferenceGroup (Context context, AttributeSet attrs, int defStyle)

Added in API level 1

public PreferenceGroup (Context context, AttributeSet attrs)

Added in API level 1

Public Methods

public void addItemFromInflater (Preference preference)

Added in API level 1

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

public abstract void addItemFromInflater (T child)

public boolean addPreference (Preference preference)

Added in API level 1

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

Parameters
preference The preference to add.
Returns
  • Whether the preference is now in this group.

public Preference findPreference (CharSequence key)

Added in API level 1

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 The key of the preference to retrieve.
Returns

public Preference getPreference (int index)

Added in API level 1

Returns the Preference at a particular index.

Parameters
index The index of the Preference to retrieve.
Returns

public int getPreferenceCount ()

Added in API level 1

Returns the number of children Preferences.

Returns
  • The number of preference children in this group.

public boolean isOrderingAsAdded ()

Added in API level 1

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

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

public void removeAll ()

Added in API level 1

Removes all Preferences from this group.

public boolean removePreference (Preference preference)

Added in API level 1

Removes a Preference from this group.

Parameters
preference The preference to remove.
Returns
  • Whether the preference was found and removed.

public void setEnabled (boolean enabled)

Added in API level 1

Sets whether this Preference is enabled. If disabled, it will not handle clicks.

Parameters
enabled Set true to enable it.

public void setOrderingAsAdded (boolean orderingAsAdded)

Added in API level 1

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 Whether to order according to the order added.
See Also

Protected Methods

protected void dispatchRestoreInstanceState (Bundle container)

Added in API level 1

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 The Bundle that holds the previously saved state.

protected void dispatchSaveInstanceState (Bundle container)

Added in API level 1

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 The Bundle in which to save the instance of this Preference.

protected boolean isOnSameScreenAsChildren ()

Added in API level 1

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

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

protected void onAttachedToActivity ()

Added in API level 1

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.

protected boolean onPrepareAddPreference (Preference preference)

Added in API level 1

Prepares a Preference to be added to the group.

Parameters
preference The preference to add.
Returns
  • Whether to allow adding the preference (true), or not (false).

protected void onPrepareForRemoval ()

Added in API level 1

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.