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é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 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:
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 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);
Configure o widget de acordo com as preferências do usuário.
Quando a configuração estiver concluída, receba 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 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.
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>