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 exibir.
Se quiser permitir que os usuários definam as configurações do seu 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 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 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 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, o que 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 só é ignorado 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 a partir da atividade de configuração
Quando um widget usa uma atividade de configuração, é responsabilidade da
atividade atualizá-lo quando a configuração for concluída. Para fazer isso,
solicite uma atualização diretamente no
AppWidgetManager
.
Confira um resumo do procedimento para atualizar corretamente o widget e fechar a atividade de configuração:
Consiga 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 do app de que a configuração foi cancelada e o host não 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, acesse 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 conferir um exemplo.
Opções de configuração do widget
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 permitam aos usuários reconfigurar widgets atuais ou ignorar a configuração inicial do widget fornecendo uma configuração de widget padrão.
Permitir aos usuários reconfigurar widgets colocados
Para permitir que os usuários reconfigurem os widgets atuais, especifique a flag
reconfigurable
no atributo
widgetFeatures
do appwidget-provider
. Consulte o guia sobre como declarar o
arquivo AppWidgetProviderInfo.xml
para mais
informações. Por exemplo:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable">
</appwidget-provider>
Os usuários podem reconfigurar o widget tocando nele, mantendo-o pressionado e tocando no botão Reconfigurar, identificado 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 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 sua atividade de configuração como reconfigurável e opcional:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>
Permitir que os usuários fixem um widget
Em dispositivos com o Android 8.0 (nível 26 da API) e versões mais recentes, as telas de início que permitem que os usuários criem atalhos fixados também possam fixar widgets na tela inicial. Assim como os atalhos fixados, esses widgets fixados oferecem aos usuários acesso a tarefas específicas no app e podem ser adicionados à tela inicial diretamente do app, conforme mostrado no vídeo abaixo.
No seu app, é possível criar uma solicitação para o sistema fixar um widget em uma tela de início compatível seguindo estas etapas:
Chame o método
requestPinAppWidget()
, conforme mostrado no snippet de código abaixo:
Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context) val myProvider = ComponentName(context, ExampleAppWidgetProvider::class.java) if (appWidgetManager.isRequestPinAppWidgetSupported()) { // Create the PendingIntent object only if your app needs to be notified // when the user chooses to pin the widget. Note that if the pinning // operation fails, your app isn't notified. This callback receives the ID // of the newly pinned widget (EXTRA_APPWIDGET_ID). val successCallback = PendingIntent.getBroadcast( /* context = */ context, /* requestCode = */ 0, /* intent = */ Intent(...), /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT) appWidgetManager.requestPinAppWidget(myProvider, null, successCallback) }
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context); ComponentName myProvider = new ComponentName(context, ExampleAppWidgetProvider.class); if (appWidgetManager.isRequestPinAppWidgetSupported()) { // Create the PendingIntent object only if your app needs to be notified // when the user chooses to pin the widget. Note that if the pinning // operation fails, your app isn't notified. This callback receives the ID // of the newly pinned widget (EXTRA_APPWIDGET_ID). PendingIntent successCallback = PendingIntent.getBroadcast( /* context = */ context, /* requestCode = */ 0, /* intent = */ new Intent(...), /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT); appWidgetManager.requestPinAppWidget(myProvider, null, successCallback); }