GlanceTemplateAppWidget
abstract class GlanceTemplateAppWidget : GlanceAppWidget
| kotlin.Any | ||
| ↳ | androidx.glance.appwidget.GlanceAppWidget | |
| ↳ | androidx.glance.template.GlanceTemplateAppWidget | |
A GlanceAppWidget that provides template local values.
Summary
Public constructors |
|---|
Public functions |
|
|---|---|
abstract Unit |
|
final suspend Nothing |
provideGlance(context: Context, id: GlanceId)Override this function to provide the Glance Composable. |
Public properties |
|
|---|---|
open SizeMode |
Default widget size mode is |
open GlanceStateDefinition<*>? |
Default widget state definition is |
Inherited functions |
||||||
|---|---|---|---|---|---|---|
|
Public constructors
Public functions
TemplateContent
@Composable
@GlanceComposable
abstract fun TemplateContent(): Unit
provideGlance
final suspend fun provideGlance(context: Context, id: GlanceId): Nothing
Override this function to provide the Glance Composable.
This is a good place to load any data needed to render the Composable. Use provideContent to provide the Composable once the data is ready.
provideGlance is run in the background as a androidx.work.CoroutineWorker in response to calls to update and updateAll, as well as requests from the Launcher. Before provideContent is called, provideGlance is subject to the typical androidx.work.WorkManager time limit (currently ten minutes). After provideContent is called, the composition continues to run and recompose for about 45 seconds. When UI interactions or update requests are received, additional time is added to process these requests.
Note: update and updateAll do not restart provideGlance if it is already running. As a result, you should load initial data before calling provideContent, and then observe your sources of data within the composition (e.g. androidx.compose.runtime.collectAsState). This ensures that your widget will continue to update while the composition is active. When you update your data source from elsewhere in the app, make sure to call update in case a Worker for this widget is not currently running.
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.rememberCoroutineScope
import androidx.datastore.core.DataStore
import androidx.datastore.preferences.core.Preferences
import androidx.datastore.preferences.core.stringPreferencesKey
import androidx.datastore.preferences.preferencesDataStore
import androidx.glance.GlanceId
import androidx.glance.GlanceModifier
import androidx.glance.action.clickable
import androidx.glance.appwidget.GlanceAppWidget
import androidx.glance.appwidget.provideContent
import androidx.glance.appwidget.updateAll
import androidx.glance.text.Text
class MyWidget : GlanceAppWidget() {
val Context.myWidgetStore by preferencesDataStore("MyWidget")
val Name = stringPreferencesKey("name")
override suspend fun provideGlance(context: Context, id: GlanceId) {
// Load initial data needed to render the AppWidget here. Prefer doing heavy work before
// provideContent, as the provideGlance function will timeout shortly after
// provideContent is called.
val store = context.myWidgetStore
val initial = store.data.first()
provideContent {
// Observe your sources of data, and declare your @Composable layout.
val data by store.data.collectAsState(initial)
val scope = rememberCoroutineScope()
Text(
text = "Hello ${data[Name]}",
modifier = GlanceModifier.clickable("changeName") {
scope.launch {
store.updateData {
it.toMutablePreferences().apply { set(Name, "Changed") }
}
}
}
)
}
}
// Updating the widget from elsewhere in the app:
suspend fun changeWidgetName(context: Context, newName: String) {
context.myWidgetStore.updateData {
it.toMutablePreferences().apply { set(Name, newName) }
}
// Call update/updateAll in case a Worker for the widget is not currently running. This
// is not necessary when updating data from inside of the composition using lambdas,
// since a Worker will be started to run lambda actions.
MyWidget().updateAll(context)
}
}
import androidx.compose.runtime.collectAsState
import androidx.datastore.core.DataStore
import androidx.datastore.preferences.core.Preferences
import androidx.datastore.preferences.core.intPreferencesKey
import androidx.datastore.preferences.preferencesDataStore
import androidx.glance.GlanceId
import androidx.glance.appwidget.GlanceAppWidget
import androidx.glance.appwidget.provideContent
import androidx.glance.appwidget.updateAll
import androidx.glance.text.Text
import androidx.work.CoroutineWorker
import androidx.work.ExistingPeriodicWorkPolicy
import androidx.work.PeriodicWorkRequest
import androidx.work.WorkManager
import androidx.work.WorkerParameters
class WeatherWidget : GlanceAppWidget() {
val Context.weatherWidgetStore by preferencesDataStore("WeatherWidget")
val CurrentDegrees = intPreferencesKey("currentDegrees")
suspend fun DataStore<Preferences>.loadWeather() {
updateData { prefs ->
prefs.toMutablePreferences().apply {
this[CurrentDegrees] = Random.Default.nextInt()
}
}
}
override suspend fun provideGlance(context: Context, id: GlanceId) {
coroutineScope {
val store = context.weatherWidgetStore
val currentDegrees = store.data
.map { prefs -> prefs[CurrentDegrees] }
.stateIn(this@coroutineScope)
// Load the current weather if there is not a current value present.
if (currentDegrees.value == null) store.loadWeather()
// Create unique periodic work to keep this widget updated at a regular interval.
WorkManager.getInstance(context).enqueueUniquePeriodicWork(
"weatherWidgetWorker",
ExistingPeriodicWorkPolicy.KEEP,
PeriodicWorkRequest.Builder(
WeatherWidgetWorker::class.java,
15.minutes.toJavaDuration()
).setInitialDelay(15.minutes.toJavaDuration()).build()
)
// Note: you can also set `android:updatePeriodMillis` to control how often the
// launcher requests an update, but this does not support periods less than
// 30 minutes.
provideContent {
val degrees by currentDegrees.collectAsState()
Text("Current weather: $degrees °F")
}
}
}
}
class WeatherWidgetWorker(
appContext: Context,
params: WorkerParameters
) : CoroutineWorker(appContext, params) {
override suspend fun doWork(): Result {
WeatherWidget().apply {
applicationContext.weatherWidgetStore.loadWeather()
// Call update/updateAll in case a Worker for the widget is not currently running.
updateAll(applicationContext)
}
return Result.success()
}
}
Public properties
stateDefinition
open val stateDefinition: GlanceStateDefinition<*>?
Default widget state definition is PreferencesGlanceStateDefinition