universum.studios.android.setting

Class SettingSelectionDialogPreference

java.lang.Object

androidx.preference.Preference

universum.studios.android.setting.SettingPreference

universum.studios.android.setting.SettingDialogPreference<SelectionDialog.SelectionOptions>

universum.studios.android.setting.SettingSelectionDialogPreference

All Implemented Interfaces:

Comparable<androidx.preference.Preference>

public class SettingSelectionDialogPreference
extends SettingDialogPreference<SelectionDialog.SelectionOptions>

A SettingDialogPreference implementation that may be used to allow to a user to select its preferred values, either in single or multiple choice mode, for a specific setting preference. Entries that should be available for selection may be specified via setEntries(CharSequence[]) along with theirs corresponding entry values that should be specified via setEntryValues(String[]).

This preference implementation by default displays the preferred entry values as its summary text, using SettingSelectionDialogPreference.SummaryTextBuilder, that may be specified via setSummaryTextBuilder(SummaryTextBuilder), to build the summary text from the selected entry values. If there are no preferred entry values selected yet, the standard summary text is displayed. The selected entry values are persisted as String in Json Array format. The preferred entry values may be specified via setSelection(long[]) where the passed array should contain indexes of entry values specified via setEntryValues(String[]) to be persisted. The current selection array may be obtained via getSelection(). Array of persisted entry values may be obtained via getSelectedEntryValues(). Outside of context of the selection preference it may be obtained via createEntryValuesFromPersistedValues(String) method which accepts String containing persisted entry values in Json Array format.

When SettingDialogPreference.handleDialogButtonClick(Dialog, int) is called, this preference implementation handles only SelectionDialog type of dialog. If its Dialog.BUTTON_POSITIVE button has been clicked, the selection array provided via SelectionDialog.getSelection() is set as selection for this preference via setSelection(long[]).

Default value

Default value for this preference is parsed as String which should contain entry values that should be by default selected, in Json Array format like "["entry_value_1", "entry_value_2"]". See TypedArray.getString(int).

Xml attributes

See SettingDialogPreference, SettingSelectionDialogPreference Attributes

Default style attribute

settingSelectionDialogPreferenceStyle

Since:

1.0

Author:

Martin Albedinsky

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	SettingSelectionDialogPreference.SummaryTextBuilder Interface for builder that is used by SettingSelectionDialogPreference to build its summary text from the current selection of entry items.

Nested classes/interfaces inherited from class universum.studios.android.setting.SettingDialogPreference

SettingDialogPreference.OnClickListener

Nested classes/interfaces inherited from class androidx.preference.Preference

androidx.preference.Preference.BaseSavedState, androidx.preference.Preference.OnPreferenceChangeListener, androidx.preference.Preference.OnPreferenceClickListener, androidx.preference.Preference.SummaryProvider<T extends androidx.preference.Preference>

Field Summary

Fields inherited from class universum.studios.android.setting.SettingDialogPreference

NO_DIALOG_ID

Fields inherited from class androidx.preference.Preference

DEFAULT_ORDER

Constructor Summary

Constructors

Constructor and Description
SettingSelectionDialogPreference(android.content.Context context) Same as SettingSelectionDialogPreference(Context, AttributeSet) without attributes.
SettingSelectionDialogPreference(android.content.Context context, android.util.AttributeSet attrs) Same as SettingSelectionDialogPreference(Context, AttributeSet, int) with R.attr.settingSelectionDialogPreferenceStyle as attribute for default style.
SettingSelectionDialogPreference(android.content.Context context, android.util.AttributeSet attrs, int defStyleAttr) Same as SettingSelectionDialogPreference(Context, AttributeSet, int, int) with 0 as default style.
SettingSelectionDialogPreference(android.content.Context context, android.util.AttributeSet attrs, int defStyleAttr, int defStyleRes) Creates a new instance of SettingSelectionDialogPreference for the given context.

Method Summary

Modifier and Type	Method and Description
static String[]	createEntryValuesFromPersistedValues(String persistedValues) Creates an array of selected entry values from the given persistedValues String.
SelectionDialog.SelectionOptions	getDialogOptions() Returns the dialog options specific for the dialog associated with this dialog preference.
CharSequence[]	getEntries() Returns the array of entries specified for this preference.
String[]	getEntryValues() Returns the array of entry values associated with the entries specified for this preference.
String[]	getSelectedEntryValues() Returns the array of preferred entry values of this preference.
long[]	getSelection() Returns the array of indexes of the preferred entry values of this preference.
void	onBindViewHolder(androidx.preference.PreferenceViewHolder holder)
protected void	onConfigureDialogOptions(SelectionDialog.SelectionOptions options, android.content.Context context, android.util.AttributeSet attrs, int defStyleAttr, int defStyleRes) Called from one of constructors to configure dialog options specific for this dialog preference.
protected SelectionDialog.SelectionOptions	onCreateDialogOptions(android.content.res.Resources resources) Called to create instance of dialog options specific for this dialog preference.
protected Object	onGetDefaultValue(android.content.res.TypedArray typedArray, int index)
protected CharSequence	onGetSummaryText() Called from SettingDialogPreference.synchronizeSummaryView(PreferenceViewHolder) to retrieve the current summary text for this dialog preference.
protected boolean	onHandleDialogButtonClick(Dialog dialog, int button) Called from SettingDialogPreference.handleDialogButtonClick(Dialog, int) if the given dialog has id associated with this dialog preference.
protected void	onSetInitialValue(Object defaultValue)
void	setEntries(CharSequence[] entries) Specifies an array of entries that should be displayed in the associated selection dialog.
void	setEntries(int resId) Same as setEntries(CharSequence[]) for resource id.
void	setEntryValues(int resId) Same as setEntryValues(String[]) for resource id.
void	setEntryValues(String[] entryValues) Specifies an array of entry values where each value should be associated with corresponding entry from the entries array specified via setEntries(CharSequence[]).
void	setSelection(long[] selection) Sets a selection array containing indexes of preferred entry values that have been specified via setEntryValues(String[]) for this preference.
void	setSummaryTextBuilder(SettingSelectionDialogPreference.SummaryTextBuilder textBuilder) Sets a builder that should be used by this preference to build its summary text for the current selected entry items.

Methods inherited from class universum.studios.android.setting.SettingDialogPreference

getDialogId, handleDialogButtonClick, setDialogId, setOnClickListener, synchronizeSummaryView

Methods inherited from class universum.studios.android.setting.SettingPreference

setKey

Methods inherited from class androidx.preference.Preference

callChangeListener, compareTo, findPreferenceInHierarchy, getContext, getDependency, getExtras, getFragment, getIcon, getIntent, getKey, getLayoutResource, getOnPreferenceChangeListener, getOnPreferenceClickListener, getOrder, getParent, getPersistedBoolean, getPersistedFloat, getPersistedInt, getPersistedLong, getPersistedString, getPersistedStringSet, getPreferenceDataStore, getPreferenceManager, getSharedPreferences, getShouldDisableView, getSummary, getSummaryProvider, getTitle, getWidgetLayoutResource, hasKey, isCopyingEnabled, isEnabled, isIconSpaceReserved, isPersistent, isSelectable, isShown, isSingleLineTitle, isVisible, notifyChanged, notifyDependencyChange, notifyHierarchyChanged, onAttached, onAttachedToHierarchy, onAttachedToHierarchy, onClick, onDependencyChanged, onDetached, onInitializeAccessibilityNodeInfo, onParentChanged, onPrepareForRemoval, onRestoreInstanceState, onSaveInstanceState, onSetInitialValue, peekExtras, performClick, performClick, persistBoolean, persistFloat, persistInt, persistLong, persistString, persistStringSet, restoreHierarchyState, saveHierarchyState, setCopyingEnabled, setDefaultValue, setDependency, setEnabled, setFragment, setIcon, setIcon, setIconSpaceReserved, setIntent, setLayoutResource, setOnPreferenceChangeListener, setOnPreferenceClickListener, setOrder, setPersistent, setPreferenceDataStore, setSelectable, setShouldDisableView, setSingleLineTitle, setSummary, setSummary, setSummaryProvider, setTitle, setTitle, setViewId, setVisible, setWidgetLayoutResource, shouldDisableDependents, shouldPersist, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SettingSelectionDialogPreference

public SettingSelectionDialogPreference(@NonNull
                                        android.content.Context context)

Same as SettingSelectionDialogPreference(Context, AttributeSet) without attributes.

SettingSelectionDialogPreference

public SettingSelectionDialogPreference(@NonNull
                                        android.content.Context context,
                                        @Nullable
                                        android.util.AttributeSet attrs)

Same as SettingSelectionDialogPreference(Context, AttributeSet, int) with R.attr.settingSelectionDialogPreferenceStyle as attribute for default style.

SettingSelectionDialogPreference

public SettingSelectionDialogPreference(@NonNull
                                        android.content.Context context,
                                        @Nullable
                                        android.util.AttributeSet attrs,
                                        @AttrRes
                                        int defStyleAttr)

Same as SettingSelectionDialogPreference(Context, AttributeSet, int, int) with 0 as default style.

SettingSelectionDialogPreference

public SettingSelectionDialogPreference(@NonNull
                                        android.content.Context context,
                                        @Nullable
                                        android.util.AttributeSet attrs,
                                        @AttrRes
                                        int defStyleAttr,
                                        @StyleRes
                                        int defStyleRes)

Creates a new instance of SettingSelectionDialogPreference for the given context.

Parameters:

context - Context in which will be the new setting preference presented.

attrs - Set of Xml attributes used to configure the new instance of this preference.

defStyleAttr - An attribute which contains a reference to a default style resource for this preference within a theme of the given context.

defStyleRes - Resource id of the default style for the new preference.

Method Detail

createEntryValuesFromPersistedValues

@Nullable
public static String[] createEntryValuesFromPersistedValues(@NonNull
                                                                      String persistedValues)

Creates an array of selected entry values from the given persistedValues String.

Parameters:

persistedValues - The string with entry values in Json Array format persisted for a particular SettingSelectionDialogPreference.

Returns:

Array of entry values that have been persisted or null if no preferred values have been selected/persisted yet.

onGetDefaultValue

protected Object onGetDefaultValue(@NonNull
                                   android.content.res.TypedArray typedArray,
                                   int index)

Overrides:

onGetDefaultValue in class androidx.preference.Preference

onSetInitialValue

protected void onSetInitialValue(@Nullable
                                 Object defaultValue)

Overrides:

onSetInitialValue in class androidx.preference.Preference

onCreateDialogOptions

@NonNull
protected SelectionDialog.SelectionOptions onCreateDialogOptions(@NonNull
                                                                          android.content.res.Resources resources)

Description copied from class: SettingDialogPreference

Called to create instance of dialog options specific for this dialog preference.

Default implementation creates instance of DialogOptions.

Overrides:

onCreateDialogOptions in class SettingDialogPreference<SelectionDialog.SelectionOptions>

Parameters:

resources - Application resources that may be used supply default values from resources for the options.

Returns:

New instance of dialog options.

onConfigureDialogOptions

protected void onConfigureDialogOptions(@NonNull
                                        SelectionDialog.SelectionOptions options,
                                        @NonNull
                                        android.content.Context context,
                                        @Nullable
                                        android.util.AttributeSet attrs,
                                        @AttrRes
                                        int defStyleAttr,
                                        @StyleRes
                                        int defStyleRes)

Description copied from class: SettingDialogPreference

Called from one of constructors to configure dialog options specific for this dialog preference.

Overrides:

onConfigureDialogOptions in class SettingDialogPreference<SelectionDialog.SelectionOptions>

Parameters:

options - The options created via SettingDialogPreference.onCreateDialogOptions(Resources).

setSummaryTextBuilder

public void setSummaryTextBuilder(@Nullable
                                  SettingSelectionDialogPreference.SummaryTextBuilder textBuilder)

Sets a builder that should be used by this preference to build its summary text for the current selected entry items.

By default, this preference uses internal implementation of the summary builder which separates the entry items in the summary text by ', '.

Parameters:

textBuilder - The desired builder for the summary text. May be null to use the default one.

setEntries

public void setEntries(@ArrayRes
                       int resId)

Same as setEntries(CharSequence[]) for resource id.

Parameters:

resId - Resource id of the desired text array with entries.

setEntries

public void setEntries(@Nullable
                       CharSequence[] entries)

Specifies an array of entries that should be displayed in the associated selection dialog.

Parameters:

entries - The desired array of entries. May be null to clear the current ones.

See Also:

R.attr.entries, setEntryValues(String[])

getEntries

@Nullable
public CharSequence[] getEntries()

Returns the array of entries specified for this preference.

Returns:

Array with entries. May be null if no entries have been specified.

See Also:

setEntries(CharSequence[]), getEntryValues()

setEntryValues

public void setEntryValues(@ArrayRes
                           int resId)

Same as setEntryValues(String[]) for resource id.

Parameters:

resId - Resource id of the desired text array with values for entries.

setEntryValues

public void setEntryValues(@Nullable
                           String[] entryValues)

Specifies an array of entry values where each value should be associated with corresponding entry from the entries array specified via setEntries(CharSequence[]).

Note, that this method does not check if the entries and entry values arrays are consistent, that is that they are equal in length.

Parameters:

entryValues - The desired array of values associated with entries. May be null to clear the current ones.

See Also:

R.attr.entryValues

getEntryValues

@Nullable
public String[] getEntryValues()

Returns the array of entry values associated with the entries specified for this preference.

Returns:

Array with entry values. May be null if no entry values have been specified.

See Also:

setEntryValues(String[]), getEntries()

setSelection

public void setSelection(@Nullable
                         long[] selection)

Sets a selection array containing indexes of preferred entry values that have been specified via setEntryValues(String[]) for this preference.

Parameters:

selection - The desired selection array with indexes of the preferred entry values to be persisted as String in Json Array format.

See Also:

getSelection()

getSelection

@Nullable
public long[] getSelection()

Returns the array of indexes of the preferred entry values of this preference.

Returns:

Selection array either specified by the user, as default value or the persisted one.

See Also:

setSelection(long[]), getSelectedEntryValues(), getDialogOptions()

getSelectedEntryValues

@Nullable
public String[] getSelectedEntryValues()

Returns the array of preferred entry values of this preference.

Returns:

Array containing entry values that have been selected either by user, as default value or the persisted one.

See Also:

getSelection()

onBindViewHolder

public void onBindViewHolder(@NonNull
                             androidx.preference.PreferenceViewHolder holder)

Overrides:

onBindViewHolder in class SettingPreference

onGetSummaryText

@Nullable
protected CharSequence onGetSummaryText()

Description copied from class: SettingDialogPreference

Called from SettingDialogPreference.synchronizeSummaryView(PreferenceViewHolder) to retrieve the current summary text for this dialog preference.

Default implementation returns the text provided by Preference.getSummary() method.

Overrides:

onGetSummaryText in class SettingDialogPreference<SelectionDialog.SelectionOptions>

Returns:

The actual summary text that should be presented in the summary view of this preference.

getDialogOptions

@NonNull
public SelectionDialog.SelectionOptions getDialogOptions()

Description copied from class: SettingDialogPreference

Returns the dialog options specific for the dialog associated with this dialog preference.

Subclasses may override this method and provide the dialog options with the current preferred value so it may be properly displayed in the associated dialog.

Overrides:

getDialogOptions in class SettingDialogPreference<SelectionDialog.SelectionOptions>

Returns:

This preference's dialog options.

onHandleDialogButtonClick

protected boolean onHandleDialogButtonClick(@NonNull
                                            Dialog dialog,
                                            int button)

Description copied from class: SettingDialogPreference

Called from SettingDialogPreference.handleDialogButtonClick(Dialog, int) if the given dialog has id associated with this dialog preference.

Overrides:

onHandleDialogButtonClick in class SettingDialogPreference<SelectionDialog.SelectionOptions>

Parameters:

dialog - The dialog where the button has been clicked.

button - The clicked dialog button.

Returns:

True if the button click event has been successfully handled, false otherwise.