Releases · patrickgold/jetpref

This release is a major overhaul of the underlying model implementation and also improves the public API. See the migration guide below for adapting the usage.
Rework JetPref model declaration and implementation (Jetpref v3) by @patrickgold in #22
Change local time entry declaration from time(...) to localTime(...)
Change local time serialized format from JSON-formatted object to ISO 8601 Time standard

Full Changelog: v0.2.0...v0.3.0-beta01

Migration guide

Dependency declaration

Check out the updated dependency declaration documentation for 0.3.0-beta01 and newer.

Important

Ensure that KSP is applied as a plugin for codegen, and that the model processor is applied as a KSP dependency.

Model declaration

Change declaration from:

fun examplePreferenceModel() = JetPref.getOrCreatePreferenceModel(AppPrefs::class, ::AppPrefs)

class AppPrefs : PreferenceModel("example-app-preferences") {
// ... entries ...
}

to:

val AppPrefsStore = jetprefDataStoreOf(AppPrefsModel::class)

@Preferences
abstract class AppPrefsModel : PreferenceModel() {
// ... entries ...
}

Important

Without the @Preferences annotation, codegen will not be triggered for the model and you will receive a PreferenceModelNotFoundException exception!

Model initialization in Application class

Change initialization from:

class ExampleApplication : Application() {
    private val prefs by examplePreferenceModel()

    override fun onCreate() {
        super.onCreate()

        // Optionally initialize global JetPref configs. This must be done before
        // any preference datastore is initialized!
        JetPref.configure(
            saveIntervalMs = 500,
            encodeDefaultValues = true,
        )

        // Initialize your datastore here (required)
        prefs.initializeBlocking(this)
    }
}

to:

class ExampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Initialize your datastore here (required)
        runBlocking { // not recommended, better is to use a separately launched scope
            AppPrefsStore.initAndroid(
                context = this@ExampleApplication,
                datastoreName = "example-app-preferences",
            )
        }
    }
}

Important

Ensure that the datastoreName passed is the same as the one previously passed to the PreferenceModel constructor. It is used to locate and load the datastore file from disk!

Model usage

Change usage from:

// Get a reference to the preference model
val prefs by examplePreferenceModel()

// Read a preference value manually
prefs.preferenceName.get()

// Write a preference value manually
prefs.preferenceName.set(value)

// Resets a preference value back to default value (`null` internally)
prefs.preferenceName.reset()

// Observe a preference value which automatically removes observer if the lifecycle stops
prefs.preferenceName.observe(lifecycleOwner) { newValue ->
    // Do something with it
}

// Observe a preference value forever, requires manual removal of observer
prefs.preferenceName.observeForever { newValue ->
    // Do something with it
}

// Observe a preference value as a Jetpack Compose state with automatic disposal
val myPreference by prefs.preferenceName.observeAsState()

to:

// Get a reference to the preference model
val prefs by AppPrefsStore

// Read a preference value manually
prefs.preferenceName.get()

// Write a preference value manually
coroutineScope.launch {
    prefs.preferenceName.set(value)
}

// Resets a preference value back to default value (`null` internally)
coroutineScope.launch {
    prefs.preferenceName.reset()
}

// Get a Kotlin flow, which allows to observe state changes
prefs.preferenceName.asFlow()

// Observe a preference value as a Jetpack Compose state with automatic disposal
// (required datastore-ui module dependency)
val myPreference by prefs.preferenceName.observeAsState()

Contributors

patrickgold

Assets 2

27 Jul 00:00

patrickgold

v0.2.0

de70e69

v0.2.0 Latest

Latest

What's Changed

Update to material3 ui by @lm41 in #5
Fix ListPreference horizontal content padding (#6) by @patrickgold in #7
update ListPreference divider color and width by @lm41 in #8
Add TextFieldPreference & Rework existing implementations by @patrickgold in #9
Fix dialog button overflow by @patrickgold in #11
Upgrade Dependencies and Update slider pref by @patrickgold in #12
Upgrade to Kotlin 2.0 by @patrickgold in #13
Rework color picker and add 2 utility material3 composables by @patrickgold in #15
Add ColorPickerPreference to JetPref by @lm41 in #14
Fix color input from text-field not updating the color value by @lm41 in #16
Update to gradle 8.14.3 by @lm41 in #17
Add LocalTimePickerPreference by @lm41 in #18
Fix JetPrefDropdown field width by @lm41 in #21