ComposePreferences
Compose Preferences is a library which makes it easy to add preference functionality to your Compose app.
It provides an easy to use PreferenceScreen Composable, which displays a list of PreferenceItems and PreferenceGroups. The Preferences are saved in a DataStore and managed by a DataStoreManager, which makes it easy to access the preferences on the preference screen or from anywhere else (other screens, viewModels, services, ...).
Supported Preference Items
- Preference Group: A container for multiple PreferenceItems
- TextPreference: A basic PreferenceItem that only displays text.
- SwitchPreference: A PreferenceItem that provides a two-state toggleable option.
- ListPreference: A PreferenceItem that displays a list of entries as a dialog. Only one entry can be selected at any given time.
- MultiSelectListPreference: A PreferenceItem that displays a list of entries as a dialog. Multiple entries can be selected at the same time.
- SeekBarPreference: A PreferenceItem that displays a seekBar and the currently selected value.
- DropDownPreference: A PreferenceItem that displays a list of entries as a dropdown menu. Only one entry can be selected at any given time.
Usage
To use ComposePreferences, create a DataStore and simply add a PreferenceScreen to your App:
val Context.dataStore: DataStore<Preferences> by preferencesDataStore(name = "settings")
setContent {
MaterialTheme {
PreferenceScreen(
items = listOf(
// PreferenceItems and PreferenceGroups
),
dataStore = this.dataStore,
statusBarPadding = true // When going edgeToEdge
)
}
}
You can also directly supply a DataStoreManager instead of the DataStore to the PreferenceScreen Composable.
When creating the PreferenceItems you have to supply a PreferenceRequest object. A PreferenceRequest wrapps a DataStore PreferenceKey and a default value and makes it easy to querry the selection the user made outside of the PreferenceScreen.
val waterRequest = PreferenceRequest<Boolean>(
key = booleanPreferencesKey("pref_switch"),
defaultValue = true
)
// PreferenceScreen
PreferenceItem.SwitchPreference(
request = ,
title = "Switch Preference",
summary = "A preference with a switch.",
singleLineTitle = true,
icon = {
Icon(
imageVector = Icons.Outlined.Delete,
contentDescription = null,
modifier = Modifier.padding(8.dp)
)
},
)
// Some service
lifecycleScope.launch {
dataStoreManager.getPreferenceFlow(waterRequest).collect { waterEnabled ->
// Do something when the value changes
delay(100)
dataStoreManager.editPreference(waterRequest.key, !waterEnabled)
}
}
Read & Edit Preferences
Reading and editing Preferences on the PreferenceScreen is managed by ComposePreferences automatically. To access Preferences outside of the PreferenceScreen, you can query the DataStore you supplied to the PreferenceScreen Composable directly or use the DataStoreManager provided by ComposePreferences:
Read a preference
You can read a preference by using DataStoreManager's getPreference() and getPreferenceFlow() methods. Both methods require a PreferenceRequest parameter and either return the value for the key defined in the request or the default value, if the key is not present.
val dataStoreManager = DataStoreManager(this.dataStore)
val waterEnabledRequest: PreferenceRequest<Boolean> = PreferenceRequest(
key = booleanPreferencesKey("water_enabled"),
defaultValue = true,
)
// Synchronously (suspending)
val waterEnabled: Boolean = dataStoreManager.getPreference(waterEnabledRequest)
// Asynchronously
val waterEnabledFlow: Flow<Boolean> = dataStoreManager.getPreferenceFlow(waterEnabledRequest)
Edit a preference
You can edit a preference using DataStoreManager's editPreference() method. It is suspending and takes a preferenceKey and a newValue parameter and updates the DataStore with the newValue.
dataStoreManager.editPreference(waterEnabledRequest.key, false)
Download
repositories {
maven { url = uri("https://jitpack.io") }
}
dependencies {
implementation("com.github.Sh4dowSoul.ComposePreferences:compose-preferences:<version>")
// Optional - Easy access to preferences from modules without compose dependency
implementation("com.github.Sh4dowSoul.ComposePreferences:datastore-manager:<version>")
}
54 Jan 5, 2023
59 Dec 14, 2022
6 Oct 11, 2022
0 Jan 12, 2022
38 Sep 25, 2022
186 Jan 1, 2023
382 Jan 5, 2023
3 Dec 31, 2022
1 Aug 11, 2022
180 Jan 2, 2023
5 Apr 5, 2022
3 Dec 15, 2022
5 Dec 29, 2022
10 Nov 23, 2022
548 Jan 7, 2023
176 Nov 22, 2022
4 May 1, 2022
1 Mar 8, 2022