Simple Settings library for Android

by androidexample

Simple Settings Activity

Simple Settings is a library, which provides a simple to use, lightweight solution to create a settings screen without any boilerplate code. This behaviour saves cost, time and effort.

Screenshots (Android 10)

Try it

If you want to test the library, please visit the sample app on Google Play!

Usage

The first step for using this library is, to add it to the dependency section in your project:

implementation 'com.chillibits:simplesettings:1.0.0-alpha11'

// Required dependencies
implementation 'com.google.android.material:material:<latest-version>'
implementation 'androidx.preference:preference:<latest-version>'

You also have to register the activity in your manifest:

<activity
    android:name="com.chillibits.simplesettings.ui.SimpleSettingsActivity"
    android:theme="@style/Theme.MaterialComponents.DayNight.NoActionBar" />

The library accepts two different ways, for providing the settings screen information.

Provide items programmatically

You can create the settings items, by using the show() method with the callback like this:

SimpleSettings(this).show {
    Section {
        title = "Test section"
        for (i in 1..4) {
            SwitchPref {
                title = "Test 1.$i"
                summary = "This is a Test 1.$i"
                defaultValue = if(i % 2 == 0) SimpleSwitchPreference.ON else SimpleSwitchPreference.OFF
            }
        }
        if(true) {
            TextPref {
                title = "Test 2"
                summary = "This is a Test 2"
            }
        }
    }
    Section {
        InputPref {
            title = "Test 3"
            summary = "This is a Test 3"
        }
    }
}

This is especially useful, when you need to generate your preferences at runtime. You can use loops and conditions as you can see above.

Note: It is not mandatory to pass keys to each preference. In this cases, the library does auto-generate a key by converting the title of each preference to CamelCase.

Examples:

List Preference --> listPreference
ListPreference --> listpreference
This is a custom preference --> thisIsACustomPreference
custom --> custom

You can optionally pass an object of SimpleSettingsConfig to the constructor of your SimpleSettings instance, to customize the appearance of the settings activity. The different customization options are listed below.

Provide items with xml file

You also can specify your preference screen as an usual xml file:

<PreferenceScreen
    xmlns:app="http://schemas.android.com/apk/res-auto">

    <PreferenceCategory
        app:key="preference_category"
        app:title="Preference category">

        <Preference
            app:key="preference_test"
            app:title="Test"
            app:summary="This is a test preference"/>

        <SwitchPreferenceCompat
            app:key="test"
            app:defaultValue="true"
            app:title="Test"
            app:summary="This is a test"/>
    </PreferenceCategory>
</PreferenceScreen>

to build the settings screen in its default configuration, you can simply call the show method of SimpleSettings and pass the prepared xml resource file to it.

SimpleSettings(this@MainActivity).show(R.xml.preferences)

or (if you need to add PreferenceClickListeners to the preference items)

private fun showPreferences() {
    val config = SimpleSettingsConfig().apply {
        showResetOption = true
        preferenceCallback = this@MainActivity
    }
    SimpleSettings(this@MainActivity, config).show(R.xml.preferences)
}

override fun onPreferenceClick(context: Context, key: String): Preference.OnPreferenceClickListener? {
    return when(key) {
        "preference" -> WebsiteClickListener(this@MainActivity, getString(R.string.url_github))
        "custom-preference" -> Preference.OnPreferenceClickListener {

            true
        }

        else -> super.onPreferenceClick(context, key)
    }
}

Retrieve preference values

One-Time-Retrieval

You can either retrieve the values of the preferences as usual via the SharedPreferences or you can use the built-in shortcuts, coming with the library.
It provides extension functions for the Context class to easily access the preference values:

val value1 = getPrefStringValue("stringPreference", "default value")
val value2 = getPrefIntValue("intPreference", 99)
val value3 = getPrefBooleanValue("booleanPreference", true)
val value4 = getPrefFloatValue("floatPreference", 101.6f)
val value5 = getPrefLongValue("longPreference", 4834597833234)
val value6 = getPrefStringSetValue("stringSetPreference", setOf("Default 1", "Default 2"))

As you can see, this works for the types String, Int, Boolean, Float, Long, StringSet.

Retrieval as LiveData

Furthermore, the library offers a feature to observe preference values as LiveData as follows:

getPrefObserver( "listpreference", Observer<String> { value ->
    textField.text = value
})

Like above, this works for the types String, Int, Boolean, Float, Long, StringSet.

Note: This extension functions are only available for the AppCompatActivity class, because there is a LifecycleOwner required to create Observables.

Library customization

The library offers a few customization options. For applying those options, you have to pass an object of SimpleSettingsConfig to the constructor of your SimpleSettings instance.

Method Description
setActivityTitle(String) Sets the toolbar title for the SettingsActivity. The default value is 'Settings', translated to all supported languages
setActivityTitle(Context, Int) Sets the toolbar title for the SettingsActivity with a string resource. The default value is 'Settings', translated to all supported languages
displayHomeAsUpEnabled(Boolean) Enables or disables the arrow icon in the top left corner of the activity to return to the calling activity. Default is true
showResetOption(Boolean) Enables or disables an options menu item for resetting all preferences to the default values. Default is false
setPreferenceCallback(Context) Sets a callback for subscribing to click events of preference items

If you miss a customization option, please let us know, by opening an issue.

Predefined click listeners

The library offers a few predefined click listeners to save you lots of boilerplate code. These click listeners are available:

Dive in deeper into the project

Please visit the wiki, if you want to understand the perks of this library or if you want to learn more about certain preference types.

Supported languages

Here are the currently supported languages for this library.

  • English
  • German
  • French

New translations are highly appreciated. If you want to translate the lib, please open a pr.

GitHub