CovePrefs

A variety of Material preferences for Android. These preferences are dependent on the Jetpack appcompat and preference libraries.

Usage

CovePrefs is available via Maven Central.

Import the coveprefs library with

compile com.cyphercove.coveprefs:coveprefs:3.0.0

The AndroidX support library prepares dialogs for dialog preferences separately from the preferences themselves. Therefore, in order to use CovePrefs, you must do one of the following.

It's easiest to make your preference fragment extend CovePreferenceFragmentCompat. This class takes care of creating the dialog fragments for CovePrefs used in the layout.

However, you might want to extend from some other fragment class, possibly if you are using another library. In this case you can still use CovePrefs by making your host Activity implement androidx.preference.PreferenceFragmentCompat.OnPreferenceDisplayDialogCallback and calling through to CovePrefs.onPreferenceDisplayDialog() like this:

public class MySettingsActivity extends AppCompatActivity implements PreferenceFragmentCompat.OnPreferenceDisplayDialogCallback {

    @Override
    public boolean onPreferenceDisplayDialog(@NonNull PreferenceFragmentCompat caller, Preference pref) {
        return CovePrefs.onPreferenceDisplayDialog(caller, pref);
    }
    
}

If you want to support other custom dialog preferences, you can tack them on like this:

    @Override
    public boolean onPreferenceDisplayDialog(@NonNull PreferenceFragmentCompat caller, Preference pref) {
        if (CovePrefs.onPreferenceDisplayDialog(caller, pref))
            return true;
        // Create dialog fragments for other types of preferences here.
    }

Preferences

AboutPreference

AboutPreference is a DialogPreference intended for showing information about the app, such as the version number and libraries used. It uses the same properties as a DialogPreference with some behavior changes.

Property	Property type	Description
`key`	String	Although no value is stored for this type of preference, a unique key must be set if more than AboutPreference is used in a layout.
`dialogTitle`	String	If the dialog title includes a `%s`, the string will automatically be formatted to fill in the app's version number.
`dialogMessage`	String	The dialog message may include HTML, which can be used for links to libraries used.

BannerLinkPreference

BannerLinkPreference is a generic Preference with a property for setting a background drawable. This can be used for making a preference that stands out and links to something else. Convenience URI properties are provided for defining the Intent. The banner image is stretched and cropped to fill the background of the preference. By default, it replaces the background drawable of the preference so the Material touch ripple will be missing. To avoid losing the ripple, app:layout="@layout/coveprefs_preference_banner_link" can be set on the preference. It requires the Jetpack ConstraintLayout library.

Property	Property type	Description
`key`	String	Although no value is stored for this type of preference, a unique key must be set if more than one is used in a layout.
`coveprefs_banner`	Drawable	The image to fill the background of the preference
`coveprefs_uri`	String	Convenience URI link. If used, the Preference will automatically be given an Action.VIEW Intent with the provided URI.
`coveprefs_backupUri`	String	Backup URI used if no Activity can be found that can open `coveprefs_uri`.
`coveprefs_uriFormatArg`	String	If used, both `coveprefs_uri` and `coveprefs_backupUri` are treated as format Strings, with this as the sole argument.

ColorPreference

A preference that shows a color picker. The preference value is saved as an Integer in AARRGGBB format.

Property	Property type	Description
`coveprefs_colorPickerWidgets`	Flags:`hsv\|hex\|recent`	Which types of color selection widgets to show. `hsv` is a large HSV color picker. `hex` is a text box for typing in the color with hexadecimal. `recent` shows a scrolling list of recently picked color swatches. Any combination can be used. Defaults to all three.

MultiColorPreference

A preference that shows a color picker. The user can select multiple colors at once for different purposes, and select between different sets of purposes.

The possible sets of colors are defined as an array of String arrays. Each String array is a set of colors that can be picked, and one of these sets can be picked. The value is stored as a String that consists of the integer index of the String array set selected, followed by space-separated color values for that set of colors in #AARRGGBB format.

The value of the preference can be interpreted by using the MultiColor and MultiColor.Definition classes.

Property	Property type	Description
`coveprefs_colorPickerWidgets`	Flags:`hsv\|hex\|recent`	Which types of color selection widgets to show. `hsv` is a large HSV color picker. `hex` is a text box for typing in the color with hexadecimal. `recent` shows a scrolling list of recently picked color swatches. Any combination can be used. Defaults to all three.
`coveprefs_multiColorDefinition`	Array of String arrays	Each String array in the array defines one set of colors that can be picked. The Strings are the names of the color options. The user can switch between the arrays by tapping arrows in the dialog. If a String array is empty, it is treated as a disabled state.
`coveprefs_multiColorDisabledLabel`	String	If there is an empty String array in the multi-color definition, it will be labeled with this string when selected in the picker.

ImageListPreference

Behaves similarly to a ListPreference, but the user selects from an array of drawables. The value is stored as a String from the entry values array.

Property	Property type	Description
`entries`	Array of Drawables	The drawables the user must select from.
`entryValues`	Array of Strings	An array of values corresponding to the drawables in `entries`. Must be the same size array as `entries`. The values should not be translated by locale.
`tint`	Color State List	Colors used to tint the clickable images in the dialog box.
`coveprefs_tintMode`	`coveprefs_tintmode` enum value	PorterDuff mode used to tint the drawables with the `tint` attribute. One of `src_over`, `src_in`, `src_stop`, `multiply`, `screen`, and `add`.
`coveprefs_entryContentDescriptions`	Array of Strings	An array of values corresponding with the drawables, used for the accessibility content descriptions.

RatingRequestPreference

RatingRequestPreference is a TwoStatePreference that uses a Boolean value. It does not show a widget and automatically disappears when its value is true. Its value becomes true and it disappears when clicked. It is intended to be used for prompting the user to leave a review on the store, and so should presumably be forever hidden once the user clicks it. Naturally, an intent should be set. Convenience URI properties are provided for defining the Intent. To make it appear again, set its value back to false in SharedPreferences.

Property	Property type	Description
`coveprefs_uri`	String	Convenience URI link. If used, the Preference will automatically be given an Action.VIEW Intent with the provided URI.
`coveprefs_backupUri`	String	Backup URI used if no Activity can be found that can open `coveprefs_uri`.
`coveprefs_uriFormatArg`	String	If used, both `coveprefs_uri` and `coveprefs_backupUri` are treated as format Strings, with this as the sole argument.

RotaryPreference

Allows user to pick an integer from 0-359 with a dialog that depicts an arrow radiating from the center of a circle. The value is represented in the preference as an arrow pointing in the corresponding direction.

Property	Property type	Description
`useSimpleSummaryProvider`	boolean	If true, the value selected with a ° symbol appended is shown as the summary of the preference. Default false.

StringPreference

A DialogPreference with an EditText for entering the String value of the preference. This is similar to the androidx EditTextPreference but has additional customization available.

Property	Property type	Description
`coveprefs_editTextHint`	String	The hint text for the edit test.
`coveprefs_allowEmptyString`	boolean	If false, the positive button of the dialog is hidden if the edit text is empty. Default true.
`useSimpleSummaryProvider`	boolean	If true, the String value of the preference is automatically set as the Preference summary.

SeekBarPlusPreference

A subclass of SeekBarPreference that injects labels on either end of the seek bar. All the properties of a typical SeekBarPreference apply.

Property	Property type	Description
`coveprefs_leftLabel`	String	Text label placed to the left of the SeekBar.
`coveprefs_rightLabel`	String	Text label placed to the right of the SeekBar.