Os widgets de apps podem ser configuráveis. Por exemplo, um widget de relógio pode permitir que os usuários configure qual fuso horário será exibido.
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
Declarar a atividade de configuração como uma atividade normal no manifesto do Android
. O host do widget de app o inicia com o
ACTION_APPWIDGET_CONFIGURE
portanto, a atividade precisa aceitar essa 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
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, 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, e a
a atividade precisa sempre retornar um resultado. O resultado precisa incluir o widget de app
ID transmitido pela intent que iniciou a atividade (salvo na intent)
extras como
EXTRA_APPWIDGET_ID
- O sistema não envia o erro
ACTION_APPWIDGET_UPDATE
é transmitida quando uma atividade de configuração é iniciada, o que significa que ela não chame o métodoonUpdate()
quando o widget for criado. É responsabilidade da atividade de configuração solicitar uma atualização do oAppWidgetManager
ao criar o widget pela primeira vez. No entanto,onUpdate()
é chamado para atualizações subsequentes. Ele é ignorado apenas nas pela 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,
atividade para 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:
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 o sistema notifica o host do widget de app que a configuração foi cancelada e o host não adiciona 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
ao chamargetInstance(Context)
:Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context)
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
Atualize o widget com uma 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 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
ListWidgetConfigureActivity.kt
no GitHub.
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, imediatamente após o usuário adicionar o widget à tela inicial. No entanto, especificar opções que permitem aos usuários reconfigurar widgets ou widgets existentes pular 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 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 em & segurando o widget e tocando o botão Reconfigure, com o rótulo 1 na Figura 1.
![O botão aparece no canto inferior direito](https://developer.android.google.cn/static/images/appwidgets/widget-reconfigure-button.png?authuser=19&hl=pt)
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 os valores-chave
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
antes, o usuário ainda pode reconfigurar o widget
depois. Por exemplo, um widget de relógio pode ignorar a configuração inicial e
mostram o fuso horário do dispositivo por padrão.
Confira um exemplo de como marcar a atividade de configuração como ambas reconfiguráveis e opcionais:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>