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 os usuários configurem qual fuso horário mostrar.

Se quiser permitir que os usuários definam as configurações do seu widget, crie um widget configuração Activity. Esta atividade é iniciado automaticamente pelo host do widget de app, quando o widget é criado ou posteriores, dependendo das opções de configuração que você especificar.

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 o ACTION_APPWIDGET_CONFIGURE portanto, a atividade precisa aceitar a 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 android:configure. Veja mais informações sobre 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 o inicializador se refere a ele de fora do escopo do pacote.

Isso é tudo o 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 que precisam ser lembrados ao implementar a atividade:

• O host do widget de app chama a atividade de configuração, e a a atividade precisa sempre 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 transmissão ACTION_APPWIDGET_UPDATE quando uma atividade de configuração é iniciada, o que significa que ela não chama o método onUpdate() quando o widget é criado. É responsabilidade da atividade de configuração solicitar uma atualização do o 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 obter um exemplo de como retornar uma 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 dela atualizar o widget quando a configuração for concluída. Você pode fazer isso solicitando uma atualização diretamente do AppWidgetManager

Veja aqui um resumo do procedimento para atualizar corretamente o widget e fechar o 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 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 uma 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 finalize 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.

Opções de configuração de widgets

Por padrão, o host do widget do app só inicia a atividade de configuração uma vez, imediatamente após o usuário adicionar o widget à tela inicial. No entanto, especificar opções que permitem aos usuários reconfigurar widgets existentes ou pular a configuração inicial do widget fornecendo uma configuração de widget padrão.

Observação: essas opções só estão disponíveis no Android 12 (nível 31 da API) e versões mais recentes. Você pode especificá-los para versões anteriores do Android, mas o sistema os ignora e segue o comportamento padrão.

Permitir aos usuários reconfigurar widgets colocados

Para permitir que os usuários reconfigurem widgets existentes, especifique o reconfigurable na widgetFeatures de appwidget-provider. Consulte o guia para declarar a arquivo AppWidgetProviderInfo.xml para mais informações imprecisas ou inadequadas. Exemplo:

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

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

Figura 1. Botão Reconfigurar do widget.

Observação: a flag reconfigurable foi introduzida no Android 9 (nível 28 da API), mas não havia ampla compatibilidade até o Android 12.

Usar a configuração padrão do widget

Você pode fornecer uma experiência de widgets mais integrada, permitindo que os usuários ignorem a etapa de configuração inicial. Para fazer isso, especifique as flags 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. Conforme 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>