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 configurem as configuraçõ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 depois, 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 inicia a atividade com a ação
ACTION_APPWIDGET_CONFIGURE
, então ela 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 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. Isso significa que ele não chama o métodoonUpdate()
quando o widget é criado. É responsabilidade da atividade de configuração solicitar uma atualização doAppWidgetManager
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 ver 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. É possível fazer isso
solicitando uma atualização diretamente do
AppWidgetManager
.
Confira um resumo do procedimento para atualizar adequadamente o widget e fechar a atividade de configuração:
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); }
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);
Configure o widget de acordo com as preferências do usuário.
Quando a configuração for concluída, adquira uma instância do
AppWidgetManager
chamandogetInstance(Context)
:Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context)
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
Atualize o widget com um layout
RemoteViews
chamandoupdateAppWidget(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);
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 ver um exemplo.
Opções de configuração de widgets
Por padrão, o host do widget de app inicia a atividade de configuração apenas uma vez, imediatamente após o usuário adicionar o widget à tela inicial. No entanto, é possível especificar opções que permitem aos usuários reconfigurar widgets atuais ou pular 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 flag
reconfigurable
no atributo
widgetFeatures
de appwidget-provider
. Consulte o guia para declarar o arquivo
AppWidgetProviderInfo.xml
para mais
informações. Exemplo:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable">
</appwidget-provider>
Para reconfigurar o widget, os usuários podem tocar e manter pressionado o widget e tocar no botão Reconfigurar, que está marcado como 1 na figura 1.

Usar a configuração padrão do widget
Você pode oferecer uma experiência de widget mais integrada permitindo 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 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 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>