Material Preferences
???? Installation
Add this in app's build.gradle file:
implementation 'com.imangazaliev.material-prefs:core:<version>'
implementation 'com.imangazaliev.material-prefs:dialogs:<version>'
implementation 'com.imangazaliev.material-prefs:date-time:<version>'
implementation 'com.imangazaliev.material-prefs:color-picker:<version>'⚠ Attention! The package name has been changed from com.github.imangazalievm.material-prefs:xxx due to the transfer of the library to Maven Central.
⭐ Features
- Convenient and extensible DSL
- Flexible appearance settings
- Unified view on Lollipop and Pre-Lollipop
- Ability to use custom storage
- Default prefs values
- Light and dark themes
???? Usage
To start using the library you need to do 3 simple steps:
- Add
MaterialPreferencesViewin your layout - Provide preferences storage:
3.1 Default storage -DefaultPreferencesStorage
3.1 Any custom storage which implements thePreferencesStorageinterface - Build prefs screen via MaterialPrefs DSL
If you want to use DefaultPreferencesStorage you have to provide initial values through DefaultValuesContainer.
Step 1 Place the MaterialPreferencesView in your layout:
<com.imangazaliev.materialprefs.views.MaterialPreferencesView
android:id="@+id/prefsView"
android:layout_width="match_parent"
android:layout_height="match_parent" />Step 2 Create prefs storage and provide initial values:
val defValues = defaultPrefValues {
"my_string" to "Jhon Doe"
"my_int" to 99
"my_long" to 5L
"my_float" to 2.5f
"my_boolean" to true
}
val storage = defaultPrefsStorage("my_prefs", defValues)Step 3 Add pref items via MaterialPrefs DSL:
prefs(prefsView, storage) {
category("My category") {
preference {
title("My pref item")
icon(R.drawable.my_icon)
onClick {
//my action
}
}
}
} ???? Documentation
The library includes 4 modules:
- core - contains main code: simple prefs, checkbox, switch
- dialogs - dialogs prefs: single and multiple choice
- date-time - date and time pickers
- color-picker - color picker
Three last modules based on Material Dialogs library.
Core
Simple preference:
preference {
title("Title")
summary("My description")
icon(R.drawable.ic_my_icon)
showArrow(true)
onClick {
//my action
}
}Switch:
switch("my_key") {
title("Title")
summary("My description")
onChecked { isChecked ->
//my action
}
}Checkbox:
checkbox("my_key") {
title("Title")
summary("My description")
onChecked { isChecked ->
//my action
}
}Label preference:
labelPreference("my_key", String::class) {
title("Title")
onClick {
//my action
}
}Dialogs
Single Choice:
listSingleChoice("my_key", String::class) {
title("Title")
icon(R.drawable.ic_my_icon)
showRadioButtons(true)
items(
listOf(
ListItem("ar", "Arabic"),
ListItem("en", "English"),
ListItem("ru", "Russian")
)
)
}Multi Choice:
listMultiChoice("my_key", String::class) {
title("Title")
allowEmptySelection(false)
//required
listValuesSerializer { it.joinToString() }
//required
listValuesDeserializer {
if (it.isNotEmpty()) {
it.split(",")
.map { number -> number.trim().toInt() }
} else emptyList()
}
items(
listOf(
ListItem("one", "Item 1"),
ListItem("two", "Item 2"),
ListItem("three", "Item 3")
)
)
}Text Input:
textInput("my_key") {
title("Title")
icon(R.drawable.ic_username)
onNewInput {
//my action
}
}DateTime
Date picker:
datePicker("my_key") {
title("Title")
val formatter = SimpleDateFormat("dd.MM.yyyy ", Locale.US)
valuePresenter { formatter.format(it) }
onValueSelected {
//my action
}
}Time picker:
timePicker("my_key") {
title("Title")
val formatter = SimpleDateFormat("hh:mm ", Locale.US)
valuePresenter { formatter.format(it) }
onValueSelected {
//my action
}
}Date and picker:
dateTimePicker("my_key") {
title("Title")
val formatter = SimpleDateFormat("hh:mm dd.MM.yyyy ", Locale.US)
valuePresenter { formatter.format(it) }
onValueSelected {
//my action
}
}ColorPicker
colorPicker("my_key") {
title("Title")
val colors = intArrayOf(Color.RED, Color.GREEN, Color.BLUE)
colors(colors)
onColorSelected {
//my action
}
}Custom preference item
To create custom preference item you have to do 3 steps:
Step 1: Create preference view class inherited from PreferenceView or BasePreferenceView.
If your view inherited from BasePreferenceView you have to implement createValueView method:
class MyPreferenceView(
context: Context,
attrs: AttributeSet? = null,
themeResId: Int = 0
) : BasePreferenceView(context, attrs, themeResId) {
override fun createValueView(parent: ViewGroup): View {
return parent.inflate(R.layout.my_pref_view)
}
}Step 2: Create preference class inherited from Preference or BasePreference and implement 3 methods:
abstract class MyPreference(
key: String,
container: PrefsContainer,
private val appearanceManager: PreferencesAppearance
) : BasePreference<MyPreference, MyPreferenceView, String>(
container = container,
key = key,
appearanceManager = appearanceManager
) {
override fun createView(): V {
}
override fun loadValue(view: V) {
}
override fun initView(view: V) {
}
}Third generic parameter of BasePreference is a type of data, that will be save in the preferences, so it must be one of the following types:
- String
- Int
- Long
- Float
- Boolean
Step 3: Create extension method for MaterialSettings:
fun myPreference(builder: PreferenceBuilder<MyPreference>) {
MyPreference(container, appearanceManager)
.apply(builder)
.also { addPreference(it) }
}