/ Dialogs

Android library that allows applications to add dialog-based slider widgets to their settings

Android library that allows applications to add dialog-based slider widgets to their settings

Android Slider Preference Library

Android library that allows applications to add dialog-based slider widgets to their settings.

Overview

  • Slider represents a float between 0.0 and 1.0
  • Supports multiple summaries (e.g. "Low", "Medium", "High") and selects one based on the slider's position
    • Java: SliderPreference.setSummary(CharSequence[] summaries)
    • XML: android:summary="@array/string_array_of_summaries"
    • A single String still works too
  • Subclass of DialogPreference
    • Supports all dialog-specific attributes such as android:dialogMessage
    • Visually-consistent with Android's built-in preferences
    • Less error-prone than displaying the slider directly on the settings screen
  • MIT License

How To Use

Android Studio

Using Gradle

  1. Step: Add this to your root build.gradle
allprojects {
	repositories {
		// [...]
		maven { url "https://jitpack.io" }
	}

}
  1. Step: Add the dependency to your project build.gradle
dependencies {
    // [...]
    compile 'com.github.jayschwa:AndroidSliderPreference:1.0'
}

Using a Module

  1. Paste or clone this library into the /libs folder, in the root directory of your project. Create a new folder: /libs if not already present. (This step is not required - only for keeping cleaner project structure)

  2. Edit settings.gradle by adding the library. You have also define a project directory for the library. Your settings.gradle should look like below:

    include ':app', ':SliderPreference'
    project(':SliderPreference').projectDir = new File('libs/AndroidSliderPreference')
    
  3. In app/build.gradle add the SliderPreference library as a dependency:

    dependencies {
        compile fileTree(dir: 'libs', include: ['*.jar'])
        compile 'com.android.support:appcompat-v7:21.0.3'
        compile project(":SliderPreference")
    }
    
  4. Sync project, clean and build. You can use the SliderPreference as part of your project now.

Eclipse

Before you can add a SliderPreference to your application, you must first add a library reference:

  1. Clone or download a copy of the library
  2. Import the library into Eclipse: File menu -> Import -> Existing Project into Workspace
  3. Open your application's project properties and add a library reference to "SliderPreference"

Add a slider to your application

<!-- preferences.xml -->
<net.jayschwa.android.preference.SliderPreference
    android:key="my_slider"
    android:title="@string/slider_title"
    android:summary="@array/slider_summaries"
    android:defaultValue="@string/slider_default"
    android:dialogMessage="@string/slider_message" />
<!-- strings.xml -->
<string name="slider_title">Temperature</string>
<string-array name="slider_summaries">
    <!-- You can define as many summaries as you'd like -->
    <!-- The active summary will reflect the preference's current value -->
    <item>Freezing</item> <!-- 0.00 to 0.25 -->
    <item>Chilly</item>   <!-- 0.25 to 0.50 -->
    <item>Warm</item>     <!-- 0.50 to 0.75 -->
    <item>Boiling</item>  <!-- 0.75 to 1.00 -->
</string-array>
<item name="slider_default" format="float" type="string">0.5</item>
<string name="slider_message">Optional message displayed in the dialog above the slider</string>

It is possible to define the default value directly in the attribute. The summary can also be a regular string, instead of a string array:

<net.jayschwa.android.preference.SliderPreference
    android:summary="This summary is static and boring"
    android:defaultValue="0.5" />

Background

Sliders are recommended by Android's official design documentation for specific types of settings:

Use this pattern for a setting where the range of values are not discrete and fall along a continuum.

Slider design pattern example

Despite this recommendation, the Android SDK does not actually provide a Preference with slider functionality. Various custom implementations can be found around the web, but many have issues such as:

  • The slider is displayed directly on the settings screen
    • Higher chance of accidental clicks
    • No way to confirm or cancel potential changes
  • Discrete values are displayed to the user
    • Not ideal for this design pattern

This library aims to be as consistent as possible with the design pattern and Android's built-in Preference implementations.

GitHub