added in version 1.0.0
belongs to Maven artifact androidx.preference:preference:1.0.0-beta01

PreferenceGroup

public abstract class PreferenceGroup
extends Preference

java.lang.Object
   ↳ androidx.preference.Preference
     ↳ androidx.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

Nested classes

interface PreferenceGroup.PreferencePositionCallback

Interface for PreferenceGroup Adapters to implement so that PreferenceFragment.scrollToPreference(String) and PreferenceFragment.scrollToPreference(Preference) or PreferenceFragmentCompat.scrollToPreference(String) and PreferenceFragmentCompat.scrollToPreference(Preference) can determine the correct scroll position to request. 

XML attributes

PreferenceGroup_initialExpandedChildrenCount  

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.

int getInitialExpandedChildrenCount()

Gets the maximal number of children that are initially shown.

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 onAttached()

Called when the Preference hierarchy has been attached to the list of preferences.

void onDetached()

Called when the Preference hierarchy has been detached from the list of preferences.

void removeAll()

Removes all Preferences from this group.

boolean removePreference(Preference preference)

Removes a Preference from this group.

void setInitialExpandedChildrenCount(int expandedCount)

Sets the maximal number of children that are shown when the preference group is launched where the rest of the children will be hidden.

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.

boolean onPrepareAddPreference(Preference preference)

Prepares a Preference to be added to the group.

void onRestoreInstanceState(Parcelable state)

Hook allowing a Preference to re-apply a representation of its internal state that had previously been generated by onSaveInstanceState().

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.

Inherited methods

XML attributes

PreferenceGroup_initialExpandedChildrenCount

Related methods:

Public constructors

PreferenceGroup

added in version 1.0.0
public PreferenceGroup (Context context, 
                AttributeSet attrs, 
                int defStyleAttr, 
                int defStyleRes)

Parameters
context Context

attrs AttributeSet

defStyleAttr int

defStyleRes int

PreferenceGroup

added in version 1.0.0
public PreferenceGroup (Context context, 
                AttributeSet attrs, 
                int defStyleAttr)

Parameters
context Context

attrs AttributeSet

defStyleAttr int

PreferenceGroup

added in version 1.0.0
public PreferenceGroup (Context context, 
                AttributeSet attrs)

Parameters
context Context

attrs AttributeSet

Public methods

addItemFromInflater

added in version 1.0.0
public void addItemFromInflater (Preference preference)

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

Parameters
preference Preference

addPreference

added in version 1.0.0
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 version 1.0.0
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.

getInitialExpandedChildrenCount

added in version 1.0.0
public int getInitialExpandedChildrenCount ()

Gets the maximal number of children that are initially shown.

Related XML Attributes:

Returns
int the maximal number of children that are initially shown.

getPreference

added in version 1.0.0
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 version 1.0.0
public int getPreferenceCount ()

Returns the number of children Preferences.

Returns
int The number of preference children in this group.

isOrderingAsAdded

added in version 1.0.0
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 version 1.0.0
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.

onAttached

added in version 1.0.0
public void onAttached ()

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

onDetached

added in version 1.0.0
public void onDetached ()

Called when the Preference hierarchy has been detached from the list of preferences. This can also be called when this Preference has been removed from a group that was attached to the list of preferences.

removeAll

added in version 1.0.0
public void removeAll ()

Removes all Preferences from this group.

removePreference

added in version 1.0.0
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.

setInitialExpandedChildrenCount

added in version 1.0.0
public void setInitialExpandedChildrenCount (int expandedCount)

Sets the maximal number of children that are shown when the preference group is launched where the rest of the children will be hidden. If some children are hidden an expand button will be provided to show all the hidden children. Any child in any level of the hierarchy that is also a preference group (e.g. preference category) will not be counted towards the limit. But instead the children of such group will be counted. By default, all children will be shown, so the default value of this attribute is equal to Integer.MAX_VALUE.

Note: The group should have a key defined if an expandable preference is present to correctly persist state.

Related XML Attributes:

Parameters
expandedCount int: the number of children that is initially shown.

setOrderingAsAdded

added in version 1.0.0
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 version 1.0.0
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 version 1.0.0
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 version 1.0.0
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.

onPrepareAddPreference

added in version 1.0.0
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).

onRestoreInstanceState

added in version 1.0.0
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(). This function will never be called with a null state.

Parameters
state Parcelable: The saved state that had previously been returned by onSaveInstanceState().

onSaveInstanceState

added in version 1.0.0
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. This state should only contain information that is not persistent or can be reconstructed later.

Returns
Parcelable A Parcelable object containing the current dynamic state of this preference, or null if there is nothing interesting to save. The default implementation returns null.