ShouldSet
ShouldSet is an Android library written in Kotlin used to build and menage preferences screens.
Inspired by Telegram X android app material style, specifically by the settings one, it provides a declarative way to add ready-to-use preference items in your views and manage the preference values everywhere in your code.
ShouldSet lay upon the android SharedPreferences, by this making it fully compatible with them.
Getting started
Installing
If you haven't yet add the jitpack repository in your project gradle:
allprojects {
repositories {
maven { url: 'https://jitpack.io' }
}
}
Add the ShouldSet dependency in your app gradle and sync the project:
dependencies {
implementation 'com.github.MontiniCristian:ShouldSet:v0.1.1'
}
Configuring
In order to use this library you need to initialize the [ShouldManager] into the Application class:
class Application: Application() {
override fun onCreate() {
super.onCreate()
ShouldManager.init(this)
}
}
or in your first usable Activity:
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
ShouldManager.init(this)
}
}
Basic usage
Start using this library is as easy as adding a view to your xml, so let's do this:
Add a ShouldSetScreen in your fragment or Conductor controller layout:
<com.cristian.shouldset.view.ShouldSetScreen
android:id="@+id/shouldSetScreen"
android:layout_width="match_parent"
android:layout_height="match_parent">
</com.cristian.shouldset.view.ShouldSetScreen>
Here's an example from my SettingsFragment:
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:orientation="vertical"
android:layout_width="match_parent"
android:layout_height="match_parent">
<androidx.appcompat.widget.Toolbar
android:layout_width="match_parent"
android:layout_height="wrap_content"
app:title="@string/settings_toolbar_title"/>
<com.cristian.shouldset.view.ShouldSetScreen
android:id="@+id/myShouldSetScreen"
android:layout_width="match_parent"
android:layout_height="match_parent">
</com.cristian.shouldset.view.ShouldSetScreen>
</LinearLayout>
Once you have done with it you can access myShouldSetScreen from your fragment's onViewCreated method and start populating the screen:
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
super.onViewCreated(view, savedInstanceState)
myShouldSetScreen.build {
categoryTitle {
title = "Social Skills"
textColor = R.color.colorSecondary
backgroundColor = R.color.colorPrimaryDark
}
checkBoxPreference("areGreetingsHappening") {
backgroundColor = R.color.colorPrimary
textColor = android.R.color.white
setOnValueChangeListener {
if (it) print("Say hello")
if (!it) print("I'll be quiet")
}
title = "Enable Greetings"
}
descriptor {
backgroundColor = R.color.colorPrimaryDark
description = "Enabling this option will improve your social skills."
textColor = R.color.colorSecondary
}
}
}
And then with a little bit of fantasy you can go on and customize your preference screens:
myShouldSetScreen.build {
categoryTitle {
title = "Social Skills"
textColor = R.color.colorSecondary
backgroundColor = R.color.colorPrimaryDark
}
checkBoxPreference("areGreetingsHappening") {
backgroundColor = R.color.colorPrimary
textColor = android.R.color.white
setOnValueChangeListener {
if (it) print("Say hello")
if (!it) print("I'll be quiet")
}
title = "Enable Greetings"
}
descriptor {
backgroundColor = R.color.colorPrimaryDark
description = "Enabling this option will improve your social skills."
textColor = R.color.colorSecondary
}
bottomRadioGroupPreference {
keyLabelPair = hashMapOf(
"isSomething" to "Something",
"isMagic" to "Magic",
"areGreetingsHappening" to "Alternative Greet"
)
backgroundColor = R.color.colorPrimary
textColor = android.R.color.white
title = "Other Greetings"
dividerColor = R.color.colorPrimaryDark
}
dividerLine {
color = R.color.colorPrimaryDark
}
categoryTitle {
title = "Items"
textColor = R.color.colorSecondary
}
switchPreference("isSwitched") {
backgroundColor = R.color.colorPrimary
textColor = android.R.color.white
title = "Switch this"
}
dividerLine {
color = R.color.colorPrimaryDark
}
bottomCheckBoxGroupPreference("magic_kind", "duperMagic") {
backgroundColor = R.color.colorPrimary
textColor = android.R.color.white
title = "Magic kind"
dividerColor = R.color.colorPrimaryDark
textValueColor = R.color.colorSecondary
valueLabelPair = hashMapOf(
"superMagic" to "Super Magic",
"duperMagic" to "Duper Magic",
"anotherMagic" to "Another Magic",
"strangeMagic" to "Strange Magic",
"iperMagic" to "Iper Magic"
)
}
descriptor {
backgroundColor = R.color.colorPrimaryDark
description = "Select the magic kind you prefer in order to do some magic."
textColor = R.color.colorSecondary
}
}
Getting the preferences
You can read them once unig the default PreferenceManager:
val bool = PreferenceManager.getDefaultSharedPreferences(context).getBoolean("areGreetingsHappening", true)
Or you can read as BehaviorSubject to automagically update instantly your preference result:
ShouldManager.getBooleanAsBehaviorSubject("areGreetingsHappening", true).subscribe {
print("Updated value $it")
}
Contributing
Please read CONTRIBUTING.md