Permitir que os usuários configurem widgets de apps

Os widgets de apps podem ser configuráveis. Por exemplo, um widget de relógio pode permitir que o usuário configure qual fuso horário será exibido.

Se você quiser permitir que os usuários definam as configurações do widget, crie uma configuração de widget Activity. Essa atividade é iniciada automaticamente pelo host do widget de app durante a criação dele ou depois, 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 o inicia com a ação ACTION_APPWIDGET_CONFIGURE. Portanto, a atividade precisa aceitar essa intent. Por 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. Veja mais informações 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 faz referência a ela de fora do escopo do pacote.

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

Implementar a atividade de configuração

Há dois pontos importantes que precisam ser lembrados ao implementar a atividade:

  • O host do widget de app chama a atividade de configuração, que precisa sempre retornar um resultado. O resultado precisa incluir o ID do widget de app transmitido pela intent que iniciou a atividade, salvo nos extras da intent como EXTRA_APPWIDGET_ID.
  • O sistema não envia a transmissão ACTION_APPWIDGET_UPDATE quando uma atividade de configuração é iniciada, ou seja, ele não chama o método onUpdate() 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 é ignorado apenas 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 corretamente o widget e fechar a atividade de configuração:

  1. Receba o ID do widget de app da 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 sair 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 estiver 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 layout RemoteViews 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 a intent de retorno, defina-a com o resultado da atividade e termine 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 (link em inglês) no GitHub para ver um exemplo.

Opções de configuração de widgets

Por padrão, o host do widget de app só inicia a atividade de configuração uma vez, logo após o usuário adicionar o widget à tela inicial. No entanto, você pode especificar opções que permitem que os usuários reconfigurem widgets existentes ou pulem a configuração inicial de widgets fornecendo uma configuração de widget padrão.

Permitir aos usuários reconfigurar widgets colocados

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

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

Para reconfigurar o widget, o usuário pode tocar nele, mantê-lo pressionado e tocar no botão Reconfigurar, identificado 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

Você pode fornecer uma experiência de widget mais integrada, permitindo que os usuários pulem a etapa inicial de configuração. Para fazer isso, especifique as sinalizações configuration_optional e reconfigurable no campo widgetFeatures. 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 a atividade de configuração como reconfigurável e opcional:

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