Разрешить пользователям настраивать виджеты приложений

Виджеты приложений могут быть настраиваемыми. Например, виджет часов позволяет пользователям выбирать, какой часовой пояс отображать.

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

Объявите действие по настройке.

Объявите активность конфигурации как обычную активность в файле манифеста Android. Хост виджета приложения запускает её с помощью действия ACTION_APPWIDGET_CONFIGURE , поэтому активность должна принимать этот интент. Например:

<activity android:name=".ExampleAppWidgetConfigurationActi>vity&<quot;
    int>ent-filte<r
        action android:name="android.appwidget.action.APPWID>GET_C<ONFIGURE">/<
    /int>ent-filter
/activity

Объявите активность в файле AppWidgetProviderInfo.xml с помощью атрибута android:configure . Дополнительную информацию об объявлении этого файла см. здесь. Вот пример объявления активности конфигурации:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationAct>i<vity"
    ... >
/appwidget-provider

Активность объявляется с полным указанием пространства имен, поскольку средство запуска ссылается на нее извне области видимости вашего пакета.

Это всё, что вам нужно для начала процесса настройки. Далее вам необходимо выполнить сам процесс.

Выполните действия по настройке.

При проведении этого мероприятия следует помнить о двух важных моментах:

  • Хост виджета приложения вызывает действие конфигурации, и это действие всегда должно возвращать результат. Результат должен включать идентификатор виджета приложения, переданный интентом, запустившим действие, — он сохраняется в параметрах интента как EXTRA_APPWIDGET_ID .
  • Система не отправляет широковещательное сообщение ACTION_APPWIDGET_UPDATE при запуске действия конфигурации, а это значит, что она не вызывает метод onUpdate() при создании виджета. Запрос обновления у AppWidgetManager при первом создании виджета — это задача самого действия конфигурации. Однако onUpdate() вызывается для последующих обновлений — он пропускается только при первом создании.

В следующем разделе приведены фрагменты кода, демонстрирующие, как получить результат из конфигурации и обновить виджет.

Обновите виджет через окно конфигурации.

Когда виджет использует действие конфигурации, именно это действие отвечает за обновление виджета после завершения конфигурации. Это можно сделать, запросив обновление непосредственно у AppWidgetManager .

Ниже приведено краткое описание процедуры корректного обновления виджета и закрытия окна настройки:

  1. Получите идентификатор виджета приложения из интента, запустившего активность:

    Котлин 

    val appWidgetId = intent?.extras?.getInt(
        AppWidgetManager.EXTRA_APPWIDGET_ID,
        AppWidgetManager.INVALID_APPWIDGET_ID
) ?: AppWidgetManager.INVALID_APPWIDGET_ID

    Java 

    Intent intent = getIntent();
Bundle extras = intent.getExtras();
int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
if (extras != null) {
    appWidgetId = extras.getInt(
            AppWidgetManager.EXTRA_APPWIDGET_ID,
            AppWidgetManager.INVALID_APPWIDGET_ID);
}

  2. Установите результат действия в значение RESULT_CANCELED .

    Таким образом, если пользователь выходит из процесса до его завершения, система уведомляет хост виджета приложения о том, что конфигурация отменена, и хост не добавляет виджет:

    Котлин 

    val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
setResult(Activity.RESULT_CANCELED, resultValue)

    Java 

    int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
setResult(Activity.RESULT_CANCELED, resultValue);

  3. Настройте виджет в соответствии с предпочтениями пользователя.

  4. После завершения настройки получите экземпляр AppWidgetManager , вызвав getInstance(Context) :

    Котлин 

    val appWidgetManager = AppWidgetManager.getInstance(context)

    Java 

    AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

  5. Обновите виджет, добавив в него макет RemoteViews , вызвав updateAppWidget(int,RemoteViews) :

    Котлин 

    val views = RemoteViews(context.packageName, R.layout.example_appwidget)
appWidgetManager.updateAppWidget(appWidgetId, views)

    Java 

    RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
appWidgetManager.updateAppWidget(appWidgetId, views);

  6. Создайте Intent возврата, задайте в нем результат действия и завершите действие:

    Котлин 

    val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
setResult(Activity.RESULT_OK, resultValue)
finish()

    Java 

    Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
setResult(RESULT_OK, resultValue);
finish();

Пример можно посмотреть в файле ListWidgetConfigureActivity.kt на GitHub.

Параметры конфигурации виджета

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

Предоставьте пользователям возможность изменять конфигурацию размещенных виджетов.

Чтобы пользователи могли перенастраивать существующие виджеты, укажите флаг reconfigurable в атрибуте widgetFeatures объекта appwidget-provider . Дополнительную информацию см. в руководстве по объявлению файла AppWidgetProviderInfo.xml . Например: 

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures=">r<econfigurable">
/appwidget-provider

Пользователи могут изменить настройки своего виджета, коснувшись и удерживая виджет, а затем нажав кнопку « Изменить настройки» , обозначенную цифрой 1 на рисунке 1.

Кнопка находится в правом нижнем углу.
Рисунок 1. Кнопка « Перенастроить виджет».

Используйте конфигурацию виджета по умолчанию.

Вы можете обеспечить более удобную работу с виджетом, позволив пользователям пропустить этап первоначальной настройки. Для этого укажите флаги configuration_optional и reconfigurable в поле widgetFeatures . Это позволит избежать запуска процесса настройки после добавления виджета пользователем. Как упоминалось ранее, пользователь все равно сможет перенастроить виджет позже. Например, виджет часов может пропустить первоначальную настройку и по умолчанию отображать часовой пояс устройства.

Вот пример того, как можно пометить действия по настройке как перенастраиваемые и необязательные: 

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configur>a<tion_optional">
/appwidget-provider