Permitir que os usuários configurem widgets de apps

Os widgets de app podem ser configuráveis. Por exemplo, um widget de relógio pode permitir que os usuários configurem qual fuso horário mostrar.

Se você quiser permitir que os usuários configurem as definições do widget, crie uma widget configuration Activity. Essa atividade é iniciada automaticamente pelo host do widget de app quando o widget é criado ou mais tarde, dependendo das opções de configuração especificadas.

Declarar a atividade de configuração

Declare a atividade de configuração como uma atividade normal no arquivo de manifesto do Android. O host do widget de app a inicia com a ACTION_APPWIDGET_CONFIGURE ação. Portanto, a atividade precisa aceitar esse intent. Exemplo:

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

Declare a atividade no arquivo AppWidgetProviderInfo.xml com o atributo android:configure. Saiba mais sobre como declarar esse arquivo. Confira um exemplo de como declarar a atividade de configuração:

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

A atividade é declarada com um namespace totalmente qualificado, porque a tela de início a referencia de fora do escopo do pacote.

Isso é tudo que você precisa para iniciar uma atividade de configuração. Em seguida, é necessário implementar a atividade real.

Implementar a atividade de configuração

Há dois pontos importantes a serem lembrados ao implementar a atividade:

  • O host do widget de app chama a atividade de configuração, e ela sempre precisa retornar um resultado. O resultado precisa incluir o ID do widget de app transmitido pelo intent que iniciou a atividade, salvo nos extras do intent como EXTRA_APPWIDGET_ID.
  • O sistema não envia a ACTION_APPWIDGET_UPDATE transmissão quando uma atividade de configuração é iniciada, o que significa que ele não chama o onUpdate() método quando o widget é criado. É responsabilidade da atividade de configuração solicitar uma atualização do AppWidgetManager ao criar o widget pela primeira vez. No entanto, onUpdate() é chamado para atualizações subsequentes. Ele só é ignorado na primeira vez.

Consulte os snippets de código na seção a seguir para conferir um exemplo de como retornar um resultado da configuração e atualizar o widget.

Atualizar o widget pela atividade de configuração

Quando um widget usa uma atividade de configuração, é responsabilidade da atividade atualizar o widget quando a configuração for concluída. Para isso, solicite uma atualização diretamente do AppWidgetManager.

Confira um resumo do procedimento para atualizar o widget corretamente e fechar a atividade de configuração:

  1. Adquira o ID do widget pelo intent que iniciou a atividade:

    Kotlin

    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. Defina o resultado da atividade como RESULT_CANCELED.

    Dessa forma, se o usuário desistir da atividade antes de chegar ao fim, o sistema vai notificar o host do widget de app de que a configuração foi cancelada, e o host não vai adicionar o widget:

    Kotlin

    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. Configure o widget de acordo com as preferências do usuário.

  4. Quando a configuração for concluída, receba uma instância do AppWidgetManager chamando getInstance(Context):

    Kotlin

    val appWidgetManager = AppWidgetManager.getInstance(context)

    Java

    AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

  5. Atualize o widget com um RemoteViews layout chamando updateAppWidget(int,RemoteViews):

    Kotlin

    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. Crie o intent de retorno, defina-o com o resultado da atividade e conclua a atividade:

    Kotlin

    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();

Consulte a classe de exemplo ListWidgetConfigureActivity.kt no GitHub para conferir um exemplo.

Opções de configuração de widget

Por padrão, o host do widget de app só inicia a atividade de configuração uma vez, imediatamente após o usuário adicionar o widget à tela inicial. No entanto, é possível especificar opções que permitem que os usuários reconfigurem widgets atuais ou ignorem a configuração inicial do widget fornecendo uma configuração padrão.

Permitir aos usuários reconfigurar widgets colocados

Para permitir que os usuários reconfigurem widgets atuais, especifique a reconfigurable flag no widgetFeatures atributo de appwidget-provider. Consulte o guia para declarar o AppWidgetProviderInfo.xml arquivo para mais informações. Exemplo:

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

Os usuários podem reconfigurar o widget tocando e mantendo pressionado o widget e tocando no Reconfigurar botão, que está marcado como 1 na Figura 1.

O botão aparece no canto inferior direito
Figura 1. Botão Reconfigurar do widget.

Usar a configuração padrão do widget

É possível oferecer uma experiência de widget mais integrada, permitindo que os usuários ignorem a etapa de configuração inicial. Para fazer isso, especifique as configuration_optional e reconfigurable flags no widgetFeatures campo. Isso fará com que a inicialização da atividade de configuração seja ignorada após o usuário adicionar o widget. Como mencionado anteriormente, o usuário ainda pode reconfigurar o widget depois. Por exemplo, um widget de relógio pode ignorar a configuração inicial e mostrar o fuso horário do dispositivo por padrão.

Confira um exemplo de como marcar sua atividade de configuração como reconfigurável e opcional:

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