Permitir que os usuários configurem widgets de apps

Projete o widget para que os usuários possam configurar características específicas. 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 configurem as definições do widget, crie uma configuração de widget 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 de widget de app inicia o widget com a ação ACTION_APPWIDGET_CONFIGURE. 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 o iniciador a referencia 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 a serem lembrados ao implementar a atividade:

• O host de widget de app chama a atividade de configuração, e ela precisa sempre retornar um resultado. O resultado precisa incluir o ID do widget de app transmitido pela intent que iniciou a atividade salva 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. Isso significa que ele não chama as atualizações do widget inicialmente quando o widget é criado. É responsabilidade da atividade de configuração solicitar uma atualização do GlanceAppWidget ao criar o widget pela primeira vez. No entanto, as atualizações são acionadas automaticamente para os ciclos subsequentes.

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

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, acione uma atualização manual diretamente da instância GlanceAppWidget.

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:

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

2. Defina o resultado da atividade como RESULT_CANCELED.

   Assim, 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:

   val resultValue = 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, por exemplo, gravando as seleções no DataStore persistente ou em um banco de dados local.

4. Quando a configuração for concluída, recupere o GlanceId correspondente ao ID do widget da plataforma:

   val glanceAppWidgetManager = GlanceAppWidgetManager(context)
   val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)
   

5. Atualize o conteúdo do widget chamando a função de suspensão update na instância GlanceAppWidget:

   // Update the GlanceAppWidget directly
   ExampleGlanceWidget().update(context, glanceId)
   

6. Crie a intent de retorno, defina-a com o resultado da atividade e encerre a atividade:

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

Opções de configuração de widgets

Por padrão, o host de widget de app só inicia a atividade de configuração uma vez, imediatamente depois que o usuário adiciona o widget à tela inicial. No entanto, é possível especificar opções que permitem ao usuário reconfigurar widgets atuais ou pular a configuração inicial fornecendo uma configuração padrão.

Observação: essas opções estão disponíveis apenas no Android 12 (nível 31 da API) e versões mais recentes. É possível 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 atuais, especifique a flag reconfigurable no atributo widgetFeatures de appwidget-provider. Exemplo:

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

Para reconfigurar o widget, toque e mantenha pressionado o widget e toque no botão Reconfigurar, que está marcado como 1 na figura 1.

Figura 1. Botão Reconfigurar do widget.

Usar a configuração padrão do widget

Para oferecer uma experiência mais integrada com o widget, permita que os usuários pulem a etapa de configuração inicial. Para fazer isso, especifique as flags configuration_optional e reconfigurable no campo widgetFeatures. Isso evita o lançamento da atividade de configuração depois que um usuário adiciona o widget. Conforme mencionado anteriormente, o usuário ainda poderá 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>