Skip to content

Latest commit

 

History

History
287 lines (242 loc) · 14.1 KB

README.md

File metadata and controls

287 lines (242 loc) · 14.1 KB
Raw

Simple Settings Library for Android

Maven Central GitHub release Android CI API Article on Medium PRs Welcome

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.

Try it

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

Screenshots (Android 11)

Usage

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

Add repository to build.gradle file on project level:

allprojects {
    repositories {
        ...
        maven { url "https://jitpack.io" }
    }
}

Add dependencies to build.gradle file on module level (e.g. app/build.gradle):

implementation 'com.chillibits:simplesettings:1.3.4'

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

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

Provide items programmatically

Depending on the complexity of your app, you can stick with a single-paged settings screen or you might choose a paged settings screen for more complex configurations.

Single-Paged configuration

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: If you want to pass a string / drawable / layout with its resource id, please use the properties with the Res suffix. For example: titleRes = R.string.app_name.

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.

Paged Settings Screens

The library offers a solution for overloaded single-paged settings screens by supporting paged settings configurations.

SimpleSettings(this).show {
    Section {
        title = "Section"
        Page {
            title = "Page 1"
            summary = "Demo summary 1"
            displayHomeAsUpEnabled = false
            Section {
                title = "Demo subsection"
                TextPref {
                    title = "LibsClickListener"
                    onClick = LibsClickListener(this@MainActivity)
                }
                /*...*/
            }
        }
        Page {
            title = "Page 2"
            summary = "Demo summary 2"
            activityTitle = "Page 2.2"
            Section {
                DropDownPref {
                    title = "DropDownPreference"
                    simpleSummaryProvider = true
                    entries = listOf("Apple", "Banana", "Avocado", "Pineapple")
                }
                /*...*/
            }
        }
        /*...*/
    }
    Section {
        InputPref {
            title = "InputPreference"
            summary = "Click to set text"
            defaultValue = "Default text"
        }
        /*...*/
    }
    /*...*/ 
}

To learn more about the Page component, please visit its wiki entry.

Page Headers

The library supports page headers and allows you to pass layout resources to every page of your settings screen. For more information and code samples, please visit the corresponding wiki entry.

Provide items with xml file (only for single-paged configuration)

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)
    }
}

Preference Types

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:

val inputPref = getPreferenceLiveData(this@MainActivity, "listpreference")

or you can retrieve it directly as an LiveData Observer:

getPrefObserver(this@MainActivity, "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 classes, which implement LifecycleOwner.

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
setPendingTransition(Int, Int) Specifies custom activity transition animations for closing the activity. More details here.

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.

Contribute to the project

If you want to contribute to this project, please feel free to send us a pull request.

Used third party libraries

Credits

Thanks to all contributors and translators!

© Marc Auberer 2020-2022