Save the date! Android Dev Summit is coming to Sunnyvale, CA on Oct 23-24, 2019.

PreferenceGroup

abstract class PreferenceGroup : Preference
kotlin.Any
   ↳ androidx.preference.Preference
   ↳ androidx.preference.PreferenceGroup

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

For information about building a settings screen using the AndroidX Preference library, see Settings.

Summary

Nested classes
abstract

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

Inherited constants
Public constructors
<init>(context: Context!, attrs: AttributeSet!, defStyleAttr: Int, defStyleRes: Int)

<init>(context: Context!, attrs: AttributeSet!, defStyleAttr: Int)

<init>(context: Context!, attrs: AttributeSet!)

Public methods
open Unit

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

open T?

Finds a Preference based on its key.

open Unit
setOrderingAsAdded(orderingAsAdded: Boolean)

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

open Unit

open Boolean

Removes a Preference from this group.

open Preference!

Returns the Preference at a particular index.

open Unit

Removes all Preferences from this group.

open Boolean

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

open Boolean
addPreference(preference: Preference!)

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

open Boolean

Recursively finds and removes a Preference from this group or a nested group lower down in the hierarchy.

open Unit

open Unit
notifyDependencyChange(disableDependents: Boolean)

open Int

Gets the maximal number of children that are initially shown.

open Unit

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

open Int

Returns the number of children Preferences.

Protected methods
open Boolean

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

open Parcelable!

open Unit

open Boolean

Prepares a Preference to be added to the group.

open Unit

open Unit

Inherited functions
Extension functions
From androidx.preference
operator T?

Returns the preference with key, or null if no preference with key is found.

operator Preference

Returns the preference at index.

operator Boolean

Returns true if preference is found in this preference group.

operator Unit

Adds preference to this preference group.

operator Unit

Removes preference from this preference group.

Boolean

Returns true if this preference group contains no preferences.

Boolean

Returns true if this preference group contains one or more preferences.

Unit
PreferenceGroup.forEach(action: (preference: Preference) -> Unit)

Performs the given action on each preference in this preference group.

Unit
PreferenceGroup.forEachIndexed(action: (index: Int, preference: Preference) -> Unit)

Performs the given action on each preference in this preference group, providing its sequential index.

operator MutableIterator<Preference>

Returns a MutableIterator over the preferences in this preference group.

Extension properties

From androidx.preference
Int

Returns the number of preferences in this preference group.

Sequence<Preference>

Returns a Sequence over the preferences in this preference group.

Public constructors

<init>

PreferenceGroup(context: Context!, attrs: AttributeSet!, defStyleAttr: Int, defStyleRes: Int)

<init>

PreferenceGroup(context: Context!, attrs: AttributeSet!, defStyleAttr: Int)

<init>

PreferenceGroup(context: Context!, attrs: AttributeSet!)

Public methods

addItemFromInflater

open fun addItemFromInflater(preference: Preference!): Unit

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

findPreference

@Nullable open fun <T : Preference!> findPreference(@NonNull key: CharSequence): T?

Finds a Preference based on its key. If two Preferences share the same key (not recommended), the first to appear will be returned.

This will recursively search for the Preference in any children that are also PreferenceGroups.

Parameters
key CharSequence: The key of the Preference to retrieve
Return
T?: The Preference with the key, or null

setOrderingAsAdded

open fun setOrderingAsAdded(orderingAsAdded: Boolean): Unit

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

onAttached

open fun onAttached(): Unit

removePreference

open fun removePreference(preference: Preference!): Boolean

Removes a Preference from this group.

Note: This action is not recursive, and will only remove a preference if it exists in this group, ignoring preferences found in nested groups. Use removePreferenceRecursively(CharSequence) to recursively find and remove a preference.

Parameters
preference Preference!: The preference to remove
Return
Boolean: Whether the preference was found and removed

getPreference

open fun getPreference(index: Int): Preference!

Returns the Preference at a particular index.

Parameters
index Int: The index of the Preference to retrieve
Return
Preference!: The Preference

removeAll

open fun removeAll(): Unit

Removes all Preferences from this group.

isOrderingAsAdded

open fun isOrderingAsAdded(): Boolean

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

Return
Boolean: Whether this group orders based on the order the children are added

addPreference

open fun addPreference(preference: Preference!): Boolean

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

Parameters
preference Preference!: The preference to add
Return
Boolean: Whether the preference is now in this group

removePreferenceRecursively

open fun removePreferenceRecursively(@NonNull key: CharSequence): Boolean

Recursively finds and removes a Preference from this group or a nested group lower down in the hierarchy. If two Preferences share the same key (not recommended), the first to appear will be removed.

Parameters
key CharSequence: The key of the preference to remove
Return
Boolean: Whether the preference was found and removed

onDetached

open fun onDetached(): Unit

notifyDependencyChange

open fun notifyDependencyChange(disableDependents: Boolean): Unit

getInitialExpandedChildrenCount

open fun getInitialExpandedChildrenCount(): Int

Gets the maximal number of children that are initially shown.

Return
Int: The maximal number of children that are initially shown androidx.preference.R.attr#initialExpandedChildrenCount

setInitialExpandedChildrenCount

open fun setInitialExpandedChildrenCount(expandedCount: Int): Unit

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.

Parameters
expandedCount Int: The number of children that is initially shown androidx.preference.R.attr#initialExpandedChildrenCount

getPreferenceCount

open fun getPreferenceCount(): Int

Returns the number of children Preferences.

Return
Int: The number of preference children in this group

Protected methods

isOnSameScreenAsChildren

protected open fun isOnSameScreenAsChildren(): Boolean

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

Return
Boolean: true if the contained preferences should be shown on the same screen as this preference.

onSaveInstanceState

protected open fun onSaveInstanceState(): Parcelable!

dispatchRestoreInstanceState

protected open fun dispatchRestoreInstanceState(container: Bundle!): Unit

onPrepareAddPreference

protected open fun onPrepareAddPreference(preference: Preference!): Boolean

Prepares a Preference to be added to the group.

Parameters
preference Preference!: The preference to add
Return
Boolean: Whether to allow adding the preference (true), or not (false)

dispatchSaveInstanceState

protected open fun dispatchSaveInstanceState(container: Bundle!): Unit

onRestoreInstanceState

protected open fun onRestoreInstanceState(state: Parcelable!): Unit