Preference types - gregkorossy/Android-Support-Preference-V7-Fix GitHub Wiki

Contents

RingtonePreference

Available since 26.0.2.0

A Preference that allows the user to choose a ringtone from those on the device. The chosen ringtone's URI will be persisted as a string.

If the user chooses the "Default" item, the saved string will be one of DEFAULT_RINGTONE_URI, DEFAULT_NOTIFICATION_URI, or DEFAULT_ALARM_ALERT_URI. If the user chooses the "Silent" item, the saved string will be an empty string.

Copied from https://developer.android.com/reference/android/preference/RingtonePreference.html

Package

implementation 'com.takisoft.fix:preference-v7-ringtone:+'

Attributes

Name Default value Description
android:ringtoneType ringtone The sound type(s) that are shown in the picker.
android:showDefault true Whether to a show an item for the default sound/ringtone.
android:showSilent true Whether to a show an item for 'Silent'.
app:pref_showAdd true Sets whether to show an item for 'Add new ringtone'. It requires the application to declare the android.permission.WRITE_EXTERNAL_STORAGE permission in the manifest. If that permission is not declared, the 'Add new ringtone' item will not be displayed in the list.
app:pref_summaryHasRingtone null The summary that should be displayed if a selected ringtone is present. It can contain a %s param for showing the selected ringtone's name.

Methods & fields

Name Description
setCustomRingtoneRequestCode(int code) Sets the request code that will be used to start the file picker activity that the user can use to add new ringtones. Defaults to 0x9000.
setPermissionRequestCode(int code) Sets the request code that will be used to ask for user permission to save (write) the new ringtone to one of the public external storage directories (only applies to API 23+). Defaults to 0x9001.

Example

<RingtonePreference
    android:dialogTitle="Perfect ringtone"
    android:key="pref_ringtone"
    android:persistent="true"
    android:ringtoneType="ringtone"
    android:showDefault="true"
    android:showSilent="true"
    android:summary="Select a nice ringtone"
    android:title="RingtonePreference"
    app:pref_showAdd="true"
    app:pref_summaryHasRingtone="The best ringtone: %s" />

DatePickerPreference

Available since 26.0.2.0

A Preference that allows the user to choose a date. The date is saved as a string in the usual format of Android: MM/dd/yyyy (e.g. 08/31/2017).

Uses https://github.com/Gericop/DateTimePicker to provide material pickers on all supported platforms.

Package

implementation 'com.takisoft.fix:preference-v7-datetimepicker:+'

Attributes

Name Default value Description
app:pref_pickerDate null The date shown by this picker if there's no defaultValue set and the user hadn't selected a date yet, in MM/dd/yyyy format.
app:pref_minDate null The minimal date shown by this picker in MM/dd/yyyy format.
app:pref_maxDate null The maximal date shown by this picker in MM/dd/yyyy format.
app:pref_summaryHasDate null The summary that should be displayed if a selected date is present. It can contain a %s param for showing the selected date.
app:pref_summaryDatePattern local format The date pattern that will be used in the summary to format the selected date. If not set, the default format will be used based on the current locale. It can contain the usual formatting characters. See SimpleDateFormat for more details.
android:defaultValue null The default value of the preference. It should use the format MM/dd/yyyy (e.g. 08/31/2017).

Methods & fields

Name Description
getDate() Returns the selected date.
setDate(Date date) Sets and persists the desired date. Can be null to delete the date.
setDate(int year, int month, int day) Sets and persists the desired date. The month uses the usual numbering from Calendar (so January = 0, February = 1, etc.).
getPickerDate() Returns the default picker date described by app:pref_pickerDate.
setPickerDate(Date date) Sets the desired picker date. Can be null to let the picker automatically use the current date.
getMinDate() Returns the minimal date shown by this picker.
setMinDate(Date date) Sets the minimal date shown by this picker. Can be null to let the picker use the date set by the style or the default value (January 1, 1900).
getMaxDate() Returns the maximal date shown by this picker.
setMaxDate(Date date) Sets the maximal date shown by this picker. Can be null to let the picker use the date set by the style or the default value (December 31, 2100).
PATTERN The pattern that is used for parsing the default and the persisted values.
FORMAT The date format that can be used to convert the saved value to Date objects.

Example

<DatePickerPreference
    android:key="pref_date"
    android:persistent="false"
    android:summary="Select a date"
    android:title="DatePickerPreference"
    app:pref_minDate="08/31/2017"
    app:pref_summaryHasDate="Selected date: %s" />

TimePickerPreference

Available since 26.0.2.0

A Preference that allows the user to choose a time. The time is saved as a string in the format of HH:mm (24-hour version where the hours could span 0-23, no matter what the locale is).

Uses https://github.com/Gericop/DateTimePicker to provide material pickers on all supported platforms.

Package

implementation 'com.takisoft.fix:preference-v7-datetimepicker:+'

Attributes

Name Default value Description
app:pref_hourFormat auto The hour format that should be used by the picker. The possible values are auto, h24, and h12 for auto, 24-hour, and 12-hour formats, respectively.
app:pref_pickerTime null The time shown by this picker if there's no defaultValue set and the user hadn't selected a time yet, in HH:mm format.
app:pref_summaryHasTime null The summary that should be displayed if a selected time is present. It can contain a %s param for showing the selected time.
app:pref_summaryTimePattern local format The time pattern that will be used in the summary to format the selected time. If not set, the default format will be used based on the current locale. It can contain the usual formatting characters. See SimpleDateFormat for more details.
android:defaultValue null The default value of the preference. It should use the format HH:mm (e.g. 19:35).

Methods & fields

Name Description
getTime() Returns the selected time. The date part should be discarded as it's not relevant here.
setTime(Date date) Sets and persists the desired time. Can be null to delete the time.
setTime(int hourOfDay, int minute) Sets and persists the desired time, in 24-hour format.
getPickerTime() Returns the default picker time described by app:pref_pickerTime.
setPickerTime(Date date) Sets the desired picker time. Can be null to let the picker automatically use the current time.
getHourOfDay() Returns the hour of the day (a.k.a. 24-hour clock version). The range is 0-23, or -1 if the time is not set.
getMinute() Returns the minute of the hour. The range is 0-59, or -1 if the time is not set.
PATTERN The pattern that is used for parsing the default and the persisted values.
FORMAT The time format that can be used to convert the saved value to Date objects.

Example

<TimePickerPreference
    android:key="pref_time"
    android:persistent="false"
    android:summary="Select the perfect time"
    android:title="TimePickerPreference"
    app:pref_hourFormat="auto"
    app:pref_pickerTime="19:35"
    app:pref_summaryHasTime="Selected time: %s" />

ColorPickerPreference

Available since 26.1.0.0

A Preference that allows the user to pick a color. The color is saved as an int value.

Uses https://github.com/Gericop/ColorPicker to provide the color picker dialog.

Package

implementation 'com.takisoft.fix:preference-v7-colorpicker:+'

Attributes

Name Default value Description
android:defaultValue #000000 The initial value of the preference. It uses Color.parseColor(...) internally to parse the value, so make sure the given string is formatted according to Color.parseColor(...).
app:pref_currentColor 0 The picker's default color.
app:pref_colors null The available colors. This is an int array that contains all of the selectable colors that should be displayed in the picker dialog.
app:pref_sortColors false Whether to automatically sort the supplied colors based on their HSV values.
app:pref_colorDescriptions null A string array that holds the description (i.e. the name) of the colors. This is useful for accessibility services.
app:pref_columns 0 The number of columns to show in the picker dialog. If it is less than or equals to 0, the column count will be determined automatically using FlexboxLayoutManager from the Flexbox for Android project.
app:pref_size small The size of the color swatches in the picker dialog. It can be either small or large.

Methods & fields

TBD

Example

<ColorPickerPreference
    android:defaultValue="#88C440"
    android:dialogTitle="@string/color_picker_default_title"
    android:key="pref_color"
    android:persistent="false"
    android:summary="Very nice color"
    android:title="ColorPickerPreference"
    app:pref_size="small" />

AutoSummaryEditTextPreference

Available since 27.0.2.0

A preference extending EditTextPreference that automatically displays the entered value as the summary.

Package

(Available in the base package.)

implementation 'com.takisoft.fix:preference-v7:+'

Attributes

Name Default value Description
app:pref_summaryHasText null The summary that should be displayed if a selected ringtone is present. It can contain a %s param for showing the entered value (or substitute text for passwords). If this attribute is not set, the user-entered value will replace the summary completely.
app:pref_summaryPasswordSubstitute • The substitute character / string used for hiding passwords in the summary.
app:pref_summaryPasswordSubstituteLength 5 The length of the substitute character / string used for hiding passwords. If this number is less than or equals to zero, the substitute texts length will be the actual value's length.

Example

<AutoSummaryEditTextPreference
    android:dialogMessage="This is the dialog\'s message"
    android:inputType="numberPassword"
    android:key="auto_edit_text_test2"
    android:persistent="false"
    android:summary="Should be a number password input (it is now!)"
    android:title="AutoSummaryEditTextPreference"
    app:pref_summaryHasText="%s is a secret number"
    app:pref_summaryPasswordSubstitute="\u00A9"
    app:pref_summaryPasswordSubstituteLength="0" />

SimpleMenuPreference

Available since 27.0.2.0

A preference displaying a simple menu, originally implemented by RikkaW. On pre-Lollipop devices it falls back to a ListPreference as the older devices can't handle elevation and animation properly introduced in API 21.

Package

implementation 'com.takisoft.fix:preference-v7-simplemenu:+'

Attributes

Name Default value Description
app:nope null test

Example

<SimpleMenuPreference
    android:defaultValue="1"
    android:entries="@array/pref_list_entries"
    android:entryValues="@array/pref_list_values"
    android:key="pref_simple_menu"
    android:persistent="false"
    android:summary="%s"
    android:title="SimpleMenuPreference" />