Glance

XML-файл, описывающий конфигурацию виджета в Android. Он содержит метаданные, указывающие системе, как должен работать виджет.

<appwidget-provider
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:autoAdvanceViewId="@id/view_flipper"
    android:configure=".WidgetConfigActivity"
    android:description="@string/widget_description"
    android:initialLayout="@layout/widget_loading"
    android:initialKeyguardLayout="@layout/widget_loading"
    android:previewLayout="@layout/widget_preview"
    android:previewImage="@drawable/widget_preview"
    android:minWidth="120dp"
    android:minHeight="64dp"
    android:minResizeWidth="120dp"
    android:minResizeHeight="64dp"
    android:maxResizeWidth="480dp"
    android:maxResizeHeight="120dp"
    android:targetCellWidth="2"
    android:targetCellHeight="1"
    android:resizeMode="horizontal|vertical"
    android:updatePeriodMillis="1800000"
    android:widgetCategory="home_screen|keyguard"
    android:widgetFeatures="reconfigurable|configuration_optional|hide_from_picker" />

• autoAdvanceViewId используется для указания View, который будет автоматически анимироваться системой. Обычно это AdapterView, такой как StackView или ViewFlipper, который поддерживает автоматическое переключение содержимого.

• configure класс Activity, который будет использоваться для настройки виджета при его добавлении на экран. Это позволяет открыть экран настроек, где пользователь может выбрать параметры виджета перед его созданием.

• description текстовое описание виджета. Отображается пользователю в системном интерфейсе при выборе виджета на домашнем экране.

• initialLayout используется для отображения виджета сразу после его добавления на экран. Это первый макет, который пользователь видит до обновления виджета данными из приложения.

• initialKeyguardLayout используется для указания макета, который будет отображаться на экране блокировки (keyguard) сразу после добавления виджета. Это аналог параметра initialLayout, но для экрана блокировки.

• previewLayout отображается в интерфейсе выбора виджетов (widget picker). Это ресурс макета, показывающей пользователю, как будет выглядеть виджет на экране до его добавления.

• previewImage отображается в интерфейсе выбора виджетов (widget picker). Это статическая картинка, показывающая пользователю, как будет выглядеть виджет на экране до его добавления.

• minWidth минимальная ширина виджета в dp.

• minHeight минимальная высота виджета в dp.

• minResizeWidth минимальная ширина в dp, до которой можно уменьшить виджет при изменении его размера.

• minResizeHeight минимальная высота в dp, до которой можно уменьшить виджет.

• maxResizeWidth максимальная ширина в dp, до которой можно растянуть виджет.

• maxResizeHeight максимальная высота в dp, до которой можно растянуть виджет.

• targetCellWidth количество ячеек по ширине, которые должен занимать виджет (например, 2 клетки).

• targetCellHeight количество ячеек по высоте (например, 1 клетка).

• resizeMode указывает, можно ли изменять размер виджета, и если да, то в каком направлении. Этот параметр позволяет пользователю растягивать или уменьшать виджет после его добавления на экран.

• updatePeriodMillis интервал в миллисекундах, через который виджет будет автоматически обновляться системой. Минимальное значение — 30 минут (1800000 мс).

• widgetCategory указывает, где может отображаться виджет: на домашнем экране (home_screen), на экране блокировки (keyguard) или в обоих местах.

• widgetFeatures используется для указания специальных возможностей виджета, поддерживаемых хостом виджетов. Это позволяет системе понимать, какие функции можно использовать для улучшения взаимодействия с виджетом.

Базовый класс в Jetpack Glance, который используется для создания виджетов в Android. Вместо традиционного XML-макета, интерфейс виджета создаётся с помощью декларативного подхода, схожего с Jetpack Compose.

class MyGlanceWidget: GlanceAppWidget() {
    override suspend fun provideGlance(context: Context, id: GlanceId) {}
}

override suspend fun provideGlance(context: Context, id: GlanceId) {
    provideContent {
        GlanceTheme {
            Column(
                modifier = GlanceModifier.fillMaxSize().padding(16.dp),
                horizontalAlignment = Alignment.CenterHorizontally
            ) {
                Text(text = "Привет, мир!", style = TextStyle(fontSize = 18.sp))
                Button(text = "Обновить", onClick = actionRunCallback<UpdateCallback>())
            }
        }
    }
}

override val sizeMode: SizeMode
    get() = SizeMode.Single

override val sizeMode: SizeMode
    get() = SizeMode.Exact

override val sizeMode: SizeMode
    get() = SizeMode.Responsive(
        sizes = setOf(
            DpSize(120.dp, 56.dp),
            DpSize(480.dp, 120.dp)
        )
    )

override val stateDefinition: GlanceStateDefinition<*>
    get() = MyGlanceStateDefinition

override suspend fun onDelete(context: Context, glanceId: GlanceId) {
    super.onDelete(context, glanceId)
    Log.d("MyWidget", "Виджет удалён: $glanceId")
}

override fun onCompositionError(context: Context, glanceId: GlanceId, appWidgetId: Int, throwable: Throwable) {
    super.onCompositionError(context, glanceId, appWidgetId, throwable)
    Timber.e("Ошибка композиции виджета $glanceId: ${throwable.message}")
}

Интерфейс, определяющий, как сохраняется состояние виджета. Он позволяет задать механизм хранения данных для GlanceAppWidget, обеспечивая сохранение и восстановление состояния между обновлениями и перезагрузками устройства.

override val stateDefinition = PreferencesGlanceStateDefinition