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.
If you want to test the library, please visit the sample app on Google Play!
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.
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.
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.
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.
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.
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)
}
}- SimpleTextPreference (usage information)
- SimpleSwitchPreference (usage information)
- SimpleInputPreference (usage information)
- SimpleListPreference (usage information)
- SimpleMultiSelectListPreference (usage information)
- SimpleCheckboxPreference (usage information)
- SimpleDropDownPreference (usage information)
- SimpleSeekbarPreference (usage information)
- SimpleLibsPreference (usage information)
- SimpleColorPreference (usage information)
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.
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.
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.
The library offers a few predefined click listeners to save you lots of boilerplate code. These click listeners are available:
- DialogClickListener (more information)
- LibsClickListener (more information)
- PlayStoreClickListener (more information)
- ToastClickListener (more information)
- WebsiteClickListener (more information)
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.
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.
If you want to contribute to this project, please feel free to send us a pull request.
- AboutLibraries by Mike Penz
- FastAdapter by Mike Penz
- LivePreferences by İbrahim Süren
- ColorPickerPreference by Jaewoong Eum
Thanks to all contributors and translators!
© Marc Auberer 2020-2022