preferences

Preferences^ktx

The Preferences Data Store in Android allows apps to store key-value pairs, such as booleans, integers, and strings, for user _preferences _and settings.

However, using the Preferences Data Store directly can be cumbersome due to the boilerplate code required for reading and writing data. The Preferences class simplifies this by acting as a wrapper, offering an easier API for interacting with the store.

The Preferences class provides methods for getting and setting values, handling default values, data migration, and type conversion. This abstraction reduces the complexity of managing user preferences, making the code cleaner and more maintainable.

In summary, the Preferences class enhances the functionality of the Preferences Data Store, streamlining the management of user settings in Android apps.

Usage

To obtain a reference to the Preferences class, you can use either the Preferences.get(context) method or create a new instance using the Preferences(context) constructor. ``Preferences.get(context)*** method creates a singleton reference, ensuring only one instance of the class throughout the app.

val prefs = Preferences(context, "my_preferences.db")

Tip

The Use Preferences(context) with Hilt or another DI tool to maintain a single instance.

Creating Keys

Because Preferences DataStore does not use a predefined schema, you must use the corresponding key type function to define a key for each value that you need to store Preferences instance. For example, to define a key for an int value, use intPreferencesKey(). Similarly others like stringPreferenceKey() etc. can be used to define other values.

Like other keys the intPreferencesKey takes 3 args Preference name, defaultValue and IntSaver.

// create a normal int key.
// note that this returns a null when no value is saved
val intKey = intPreferencesKey("your_normal_int_key")

// This creates an int Preference key that returns defaultValue value when no value is saved.
val intKey2 = intPreferencesKey("your_int _key_with_default_value", 1)

// key with transformer.
val intKey3 = intPreferenceKey(
    "your_key_3_name",
    false,
    saver = object : IntSaver<Boolean> {
        override fun restore(value: Int): Boolean {
            // convert boolean to 
            return value != 0
        }

        override fun save(value: Boolean): Int {
            return if (value) 1 else 0
        }
    }
)

Read/Write values.

To read write values to preference data store you simply need to call operator methods get and set.

Example

// the getter returns the flow 
// The returned flow depends on the type of key passed.
// it automatically handles the transformation if required.
val flow = prefs[intKey]

// to save a value you simply need to call 
// Note this method is not suspend. It internally uses 
// the coroutine you passed when creating the preference reference.
prefs[intKey] = 5

// To get a value with out flow 
// you can simply call 
val value = prefs.value(intKey)

// In compose you can use these methods
val value by prefs.observeAsState(key = "you_defined_key")

Setup

in your project level build.gradle

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

And then in you app level build.gradle

dependencies {
    //Preferences and other widgets
    def version = 'LATEST_VERSION'
    implementation("com.github.prime-zs.toolkit:preferences:$version")
}

Authors

• @ZakirSheikh