I widget delle app sono visualizzazioni in miniatura delle app che puoi incorporare in altre app, ad esempio nella schermata Home, e ricevere aggiornamenti periodici. Queste visualizzazioni sono chiamate widget nell'interfaccia utente e puoi pubblicarne una con un fornitore di widget per app (o fornitore di widget). Un componente dell'app che contiene altri widget è chiamato host di widget dell'app (o host di widget). La figura 1 mostra un esempio di widget musicale:
Questo documento descrive come pubblicare un widget utilizzando un fornitore di widget. Per maggiori dettagli sulla creazione di un tuo AppWidgetHost per ospitare i widget delle app, consulta Creare un host di widget.
Per informazioni su come progettare il widget, consulta la Panoramica dei widget per app.
Componenti dei widget
Per creare un widget, sono necessari i seguenti componenti di base:
- Oggetto
AppWidgetProviderInfo - Descrivi i metadati di un widget, ad esempio il layout, la frequenza di aggiornamento e la classe
AppWidgetProvider.AppWidgetProviderInfoè definito in XML, come descritto in questo documento. - Corso
AppWidgetProvider - Definisce i metodi di base che ti consentono di interagire tramite programmazione con il widget. Tramite questo canale, ricevi le trasmissioni quando il widget viene aggiornato, attivato, disattivato o eliminato. Dichiari
AppWidgetProvidernel manifest e poi lo implementi, come descritto in questo documento. - Visualizza il layout
- Definisce il layout iniziale del widget. Il layout è definito in XML, come descritto in questo documento.
La Figura 2 mostra come questi componenti si inseriscono nel flusso di elaborazione complessivo dei widget dell'app.
Se il widget richiede la configurazione da parte dell'utente, implementa l'attività di configurazione del widget dell'app. Questa attività consente agli utenti di modificare le impostazioni dei widget, ad esempio il fuso orario di un widget orologio.
- A partire da Android 12 (livello API 31), puoi fornire una configurazione predefinita e consentire agli utenti di riconfigurare il widget in un secondo momento. Per maggiori dettagli, vedi Utilizzare la configurazione predefinita del widget e Consentire agli utenti di riconfigurare i widget posizionati.
- In Android 11 (livello API 30) o versioni precedenti, questa attività viene avviata ogni volta che l'utente aggiunge il widget alla schermata Home.
Consigliamo inoltre i seguenti miglioramenti: layout dei widget flessibili, miglioramenti vari, widget avanzati, widget delle raccolte e creazione di un host di widget.
Dichiara il file XML AppWidgetProviderInfo
L'oggetto AppWidgetProviderInfo definisce le qualità essenziali di un widget.
Definisci l'oggetto AppWidgetProviderInfo in un file di risorse XML utilizzando un singolo elemento <appwidget-provider> e salvalo nella cartella res/xml/ del progetto.
Ciò è mostrato nell'esempio seguente:
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
android:minWidth="40dp"
android:minHeight="40dp"
android:targetCellWidth="1"
android:targetCellHeight="1"
android:maxResizeWidth="250dp"
android:maxResizeHeight="120dp"
android:updatePeriodMillis="86400000"
android:description="@string/example_appwidget_description"
android:previewLayout="@layout/example_appwidget_preview"
android:initialLayout="@layout/example_loading_appwidget"
android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
android:resizeMode="horizontal|vertical"
android:widgetCategory="home_screen"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>
Attributi di dimensionamento dei widget
La schermata Home predefinita posiziona i widget nella finestra in base a una griglia di celle con altezza e larghezza definite. La maggior parte delle schermate Home consente ai widget di assumere solo dimensioni che sono multipli interi delle celle della griglia, ad esempio due celle orizzontali per tre celle verticali.
Gli attributi di dimensionamento dei widget ti consentono di specificare una dimensione predefinita per il widget e di fornire limiti inferiori e superiori per le dimensioni del widget. In questo contesto, le dimensioni predefinite di un widget sono quelle che assume quando viene aggiunto per la prima volta alla schermata Home.
La tabella seguente descrive gli attributi <appwidget-provider> relativi alle dimensioni dei widget:
| Attributi e descrizione | |
|---|---|
targetCellWidth e
targetCellHeight (Android 12),
minWidth e minHeight |
targetCellWidth e targetCellHeight e minWidth e minHeight, in modo che la tua app possa utilizzare come alternativa minWidth e minHeight se il dispositivo dell'utente non supporta targetCellWidth e targetCellHeight. Se supportati, gli attributi targetCellWidth e targetCellHeight hanno la precedenza sugli attributi minWidth e minHeight.
|
minResizeWidth e
minResizeHeight |
Specifica le dimensioni minime assolute del widget. Questi valori specificano le dimensioni al di sotto delle quali il widget non è leggibile o non è utilizzabile. L'utilizzo
di questi attributi consente all'utente di ridimensionare il widget in modo che sia più piccolo
rispetto alle dimensioni predefinite. L'attributo minResizeWidth viene ignorato se è maggiore di minWidth o se la modifica delle dimensioni orizzontali non è abilitata. Consulta
resizeMode. Analogamente, l'attributo
minResizeHeight viene ignorato se è maggiore di
minHeight o se la modifica delle dimensioni verticali non è abilitata. |
maxResizeWidth e
maxResizeHeight |
Specifica le dimensioni massime consigliate del widget. Se i valori non sono
un multiplo delle dimensioni delle celle della griglia, vengono arrotondati per eccesso al valore
della dimensione della cella più vicina. L'attributo maxResizeWidth viene ignorato se è inferiore a minWidth o se la modifica delle dimensioni orizzontali non è abilitata. Consulta resizeMode. Analogamente,
l'attributo maxResizeHeight viene ignorato se è maggiore
di minHeight o se la modifica delle dimensioni verticali non è abilitata.
Introdotta in Android 12. |
resizeMode |
Specifica le regole in base alle quali è possibile ridimensionare un widget. Puoi utilizzare questo
attributo per rendere i widget della schermata Home ridimensionabili orizzontalmente, verticalmente
o su entrambi gli assi. Gli utenti toccano e tengono premuto un widget per visualizzare i relativi maniglie di ridimensionamento,
quindi trascinano i maniglie orizzontali o verticali per modificarne le dimensioni sulla
griglia del layout. I valori per l'attributo resizeMode includono
horizontal, vertical e none. Per
dichiarare un widget ridimensionabile orizzontalmente e verticalmente, utilizza
horizontal|vertical. |
Esempio
Per illustrare in che modo gli attributi nella tabella precedente influiscono sulle dimensioni dei widget, assumere le seguenti specifiche:
- Una cella della griglia è larga 30 dp e alta 50 dp.
- Viene fornita la seguente specifica dell'attributo:
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
android:minWidth="80dp"
android:minHeight="80dp"
android:targetCellWidth="2"
android:targetCellHeight="2"
android:minResizeWidth="40dp"
android:minResizeHeight="40dp"
android:maxResizeWidth="120dp"
android:maxResizeHeight="120dp"
android:resizeMode="horizontal|vertical" />
A partire da Android 12:
Utilizza gli attributi targetCellWidth e targetCellHeight come dimensioni predefinite del widget.
Le dimensioni del widget sono 2 x 2 per impostazione predefinita. Il widget può essere ridimensionato fino a 2 x 1 o fino a 4 x 3.
Android 11 e versioni precedenti:
Utilizza gli attributi minWidth e minHeight per calcolare le dimensioni predefinite del widget.
La larghezza predefinita = Math.ceil(80 / 30) = 3
L'altezza predefinita = Math.ceil(80 / 50) = 2
Le dimensioni del widget sono 3 x 2 per impostazione predefinita. Le dimensioni del widget possono essere ridotte fino a 2 x 1 o aumentate fino a schermo intero.
Attributi aggiuntivi dei widget
La tabella seguente descrive gli attributi <appwidget-provider> relativi a qualità diverse dalle dimensioni dei widget.
| Attributi e descrizione | |
|---|---|
updatePeriodMillis |
Definisce la frequenza con cui il framework dei widget richiede un aggiornamento da AppWidgetProvider chiamando il metodo di callback onUpdate(). Non è garantito che l'aggiornamento effettivo avvenga esattamente con questo valore e ti consigliamo di aggiornare il più raramente possibile, non più di una volta all'ora, per risparmiare batteria.
Per l'elenco completo delle considerazioni per scegliere un periodo di aggiornamento appropriato, consulta Ottimizzazioni per l'aggiornamento dei contenuti dei widget. |
initialLayout |
Indica la risorsa di layout che definisce il layout del widget. |
configure |
Definisce l'attività che viene avviata quando l'utente aggiunge il widget, consentendole di configurare le proprietà del widget. Consulta Consenti agli utenti di configurare i widget. A partire da Android 12, la tua app può saltare la configurazione iniziale. Per maggiori dettagli, consulta Utilizzare la configurazione predefinita del widget. |
description |
Specifica la descrizione da visualizzare nel selettore di widget per il tuo widget. Introdotta in Android 12. |
previewLayout (Android 12)
e previewImage (Android 11 e versioni precedenti) |
previewImage
sia previewLayout in modo che la tua app possa ricorrere
all'utilizzo di previewImage se il dispositivo dell'utente non supporta
previewLayout. Per maggiori dettagli, vedi
Compatibilità con le anteprime dei widget scalabili.
|
autoAdvanceViewId |
Specifica l'ID della visualizzazione della visualizzazione secondaria del widget che viene avanzata automaticamente dall'host del widget. |
widgetCategory |
Dichiara se il widget può essere visualizzato nella schermata Home
(home_screen), nella schermata di blocco (keyguard) o
in entrambe. Per Android 5.0 e versioni successive, è valido solo home_screen.
|
widgetFeatures |
Dichiara le funzionalità supportate dal widget. Ad esempio, se vuoi
che il widget utilizzi la configurazione predefinita quando un utente lo aggiunge, specifica
sia i flag
configuration_optional
sia
reconfigurable. In questo modo, viene ignorato il lancio dell'attività di configurazione dopo che un utente
aggiunge il widget. L'utente può comunque
riconfigurare il widget
in un secondo momento. |
Utilizzare la classe AppWidgetProvider per gestire le trasmissioni dei widget
La classe AppWidgetProvider gestisce le trasmissioni dei widget e aggiorna il widget
in risposta agli eventi del ciclo di vita del widget. Le sezioni seguenti descrivono come dichiarare AppWidgetProvider nel manifest e poi implementarlo.
Dichiarare un widget nel file manifest
Innanzitutto, dichiara la classe AppWidgetProvider nel file AndroidManifest.xml
della tua app, come mostrato nell'esempio seguente:
<receiver android:name="ExampleAppWidgetProvider"
android:exported="false">
<intent-filter>
<action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
</intent-filter>
<meta-data android:name="android.appwidget.provider"
android:resource="@xml/example_appwidget_info" />
</receiver>
L'elemento <receiver> richiede l'attributo android:name, che specifica il AppWidgetProvider utilizzato dal widget. Il componente non deve essere esportato
se non è necessario che un processo separato trasmetta al tuo AppWidgetProvider, cosa che solitamente non accade.
L'elemento <intent-filter> deve includere un elemento <action> con l'attributo
android:name. Questo attributo specifica che AppWidgetProvider
accetta la trasmissione di
ACTION_APPWIDGET_UPDATE. Questa è l'unica trasmissione che devi dichiarare esplicitamente. AppWidgetManager invia automaticamente tutte le altre trasmissioni dei widget a AppWidgetProvider, se necessario.
L'elemento <meta-data> specifica la risorsa AppWidgetProviderInfo e richiede i seguenti attributi:
android:name: specifica il nome dei metadati. Utilizzaandroid.appwidget.providerper identificare i dati come descrittoreAppWidgetProviderInfo.android:resource: specifica la posizione della risorsaAppWidgetProviderInfo.
Implementare la classe AppWidgetProvider
La classe AppWidgetProvider estende
BroadcastReceiver come
classe di utilità per gestire le trasmissioni dei widget. Riceve solo le trasmissioni di eventi pertinenti al widget, ad esempio quando il widget viene aggiornato, eliminato, attivato e disattivato. Quando si verificano questi eventi di trasmissione, vengono chiamati i seguenti metodiAppWidgetProvider:
onUpdate()- Questo metodo viene chiamato per aggiornare il widget a intervalli definiti dall'attributo
updatePeriodMillisinAppWidgetProviderInfo. Per ulteriori informazioni, consulta la tabella che descrive gli attributi aggiuntivi dei widget in questa pagina. - Questo metodo viene chiamato anche quando l'utente aggiunge il widget, quindi esegue la configurazione di base, ad esempio la definizione di gestori eventi per gli oggetti
Viewo l'avvio di job per caricare i dati da visualizzare nel widget. Tuttavia, se dichiari un'attività di configurazione senza il flagconfiguration_optional, questo metodo non viene chiamato quando l'utente aggiunge il widget, ma viene chiamato per gli aggiornamenti successivi. È responsabilità dell'attività di configurazione eseguire il primo aggiornamento al termine della configurazione. Per ulteriori informazioni, consulta Consentire agli utenti di configurare i widget delle app. - Il callback più importante è
onUpdate(). Per ulteriori informazioni, consulta la sezione Gestire gli eventi con la classeonUpdate()in questa pagina. onAppWidgetOptionsChanged()Viene chiamato quando il widget viene posizionato per la prima volta e ogni volta che viene ridimensionato. Utilizza questo callback per mostrare o nascondere i contenuti in base agli intervalli di dimensioni del widget. Per ottenere gli intervalli di dimensioni e, a partire da Android 12, l'elenco delle dimensioni possibili che un'istanza di widget può assumere, chiama
getAppWidgetOptions(), che restituisce unBundleche include quanto segue:OPTION_APPWIDGET_MIN_WIDTH: contiene il limite inferiore della larghezza, in unità dp, di un'istanza del widget.OPTION_APPWIDGET_MIN_HEIGHT: contiene il limite inferiore dell'altezza, in unità dp, di un'istanza del widget.OPTION_APPWIDGET_MAX_WIDTH: contiene il limite superiore della larghezza, in unità dp, di un'istanza del widget.OPTION_APPWIDGET_MAX_HEIGHT: contiene il limite superiore dell'altezza, in unità dp, di un'istanza del widget.OPTION_APPWIDGET_SIZES: contiene l'elenco delle dimensioni possibili (List<SizeF>), in unità dp, che un'istanza del widget può assumere. Introdotta in Android 12.
onDeleted(Context, int[])Viene richiamata ogni volta che un widget viene eliminato dall'host del widget.
onEnabled(Context)Viene chiamato quando viene creata un'istanza del widget per la prima volta. Ad esempio, se l'utente aggiunge due istanze del widget, questo viene chiamato solo la prima volta. Se devi aprire un nuovo database o eseguire un'altra configurazione che deve essere eseguita solo una volta per tutte le istanze del widget, questo è un buon punto di partenza.
onDisabled(Context)Viene chiamato quando l'ultima istanza del widget viene eliminata dall'host del widget. Qui puoi ripulire il lavoro svolto in
onEnabled(Context), come l'eliminazione di un database temporaneo.onReceive(Context, Intent)Viene chiamato per ogni trasmissione e prima di ciascuno dei metodi callback precedenti. In genere non è necessario implementare questo metodo, perché l'implementazione predefinita
AppWidgetProviderfiltra tutte le trasmissioni dei widget e chiama i metodi precedenti in base alle esigenze.
Devi dichiarare l'implementazione della classe AppWidgetProvider come ricevitore di trasmissione utilizzando l'elemento <receiver> in AndroidManifest. Per ulteriori informazioni, consulta la sezione Dichiarare un
widget nel file manifest in questa pagina.
Gestire gli eventi con la classe onUpdate()
Il callback AppWidgetProvider più importante è onUpdate(), perché viene chiamato quando ogni widget viene aggiunto a un host, a meno che non utilizzi un'attività di configurazione senza il flag configuration_optional. Se il widget accetta eventi di interazione con l'utente, registra i gestori di eventi in questo callback. Se il tuo widget non crea file o database temporanei o non esegue altri lavori che richiedono la pulizia, onUpdate() potrebbe essere l'unico metodo di callback da definire.
Ad esempio, se vuoi un widget con un pulsante che avvii un'attività quando viene toccato, puoi utilizzare la seguente implementazione di AppWidgetProvider:
Kotlin
class ExampleAppWidgetProvider : AppWidgetProvider() {
override fun onUpdate(
context: Context,
appWidgetManager: AppWidgetManager,
appWidgetIds: IntArray
) {
// Perform this loop procedure for each widget that belongs to this
// provider.
appWidgetIds.forEach { appWidgetId ->
// Create an Intent to launch ExampleActivity.
val pendingIntent: PendingIntent = PendingIntent.getActivity(
/* context = */ context,
/* requestCode = */ 0,
/* intent = */ Intent(context, ExampleActivity::class.java),
/* flags = */ PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
)
// Get the layout for the widget and attach an onClick listener to
// the button.
val views: RemoteViews = RemoteViews(
context.packageName,
R.layout.appwidget_provider_layout
).apply {
setOnClickPendingIntent(R.id.button, pendingIntent)
}
// Tell the AppWidgetManager to perform an update on the current
// widget.
appWidgetManager.updateAppWidget(appWidgetId, views)
}
}
}
Java
public class ExampleAppWidgetProvider extends AppWidgetProvider {
public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
// Perform this loop procedure for each widget that belongs to this
// provider.
for (int i=0; i < appWidgetIds.length; i++) {
int appWidgetId = appWidgetIds[i];
// Create an Intent to launch ExampleActivity
Intent intent = new Intent(context, ExampleActivity.class);
PendingIntent pendingIntent = PendingIntent.getActivity(
/* context = */ context,
/* requestCode = */ 0,
/* intent = */ intent,
/* flags = */ PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
);
// Get the layout for the widget and attach an onClick listener to
// the button.
RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget_layout);
views.setOnClickPendingIntent(R.id.button, pendingIntent);
// Tell the AppWidgetManager to perform an update on the current app
// widget.
appWidgetManager.updateAppWidget(appWidgetId, views);
}
}
}
Questo AppWidgetProvider definisce solo il metodo onUpdate(), che viene utilizzato per creare un PendingIntent che avvia un Activity e lo collega al pulsante del widget utilizzando setOnClickPendingIntent(int,
PendingIntent). Include un ciclo che esegue l'iterazione di ogni voce in appWidgetIds, che è un array di ID che identificano ogni widget creato da questo provider. Se l'utente crea più di un'istanza del widget, tutte vengono aggiornate contemporaneamente. Tuttavia, viene gestita solo una pianificazione updatePeriodMillis per tutte le istanze del widget. Ad esempio, se la pianificazione dell'aggiornamento è definita ogni due ore e viene aggiunta una seconda istanza del widget un'ora dopo la prima, entrambe vengono aggiornate nel periodo definito dalla prima e il secondo periodo di aggiornamento viene ignorato. Entrambi vengono aggiornati ogni due ore, non ogni ora.
Per ulteriori dettagli, consulta la classe di esempio
ExampleAppWidgetProvider.java.
Ricevere intent di trasmissione dei widget
AppWidgetProvider è una classe di convenienza. Se vuoi ricevere direttamente le trasmissioni del widget, puoi implementare il tuo BroadcastReceiver o eseguire l'override del callback onReceive(Context,Intent). Gli intent di cui devi tenere conto sono i seguenti:
ACTION_APPWIDGET_UPDATEACTION_APPWIDGET_DELETEDACTION_APPWIDGET_ENABLEDACTION_APPWIDGET_DISABLEDACTION_APPWIDGET_OPTIONS_CHANGED
Crea il layout del widget
Devi definire un layout iniziale per il widget in XML e salvarlo nella directory res/layout/ del progetto. Per maggiori dettagli, consulta le linee guida sul design.
La creazione del layout del widget è semplice se hai dimestichezza con i
layout. Tuttavia, tieni presente che i layout dei widget si basano su RemoteViews, che non supporta tutti i tipi di layout o widget di visualizzazione. Non puoi utilizzare viste personalizzate o sottoclassi delle viste supportate da RemoteViews.
RemoteViews supporta anche ViewStub,
che è un View invisibile e di dimensioni pari a zero che puoi utilizzare per gonfiare in modo lazy le risorse di layout
in fase di esecuzione.
Supporto per il comportamento stateful
Android 12 aggiunge il supporto del comportamento con stato utilizzando i seguenti componenti esistenti:
Il widget è ancora senza stato. L'app deve memorizzare lo stato e registrarsi per gli eventi di modifica dello stato.
Il seguente esempio di codice mostra come implementare questi componenti.
Kotlin
// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)
// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)
// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
R.id.my_checkbox,
RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)
Java
// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true);
// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2);
// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
R.id.my_checkbox,
RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent));
Fornisci due layout: uno destinato ai dispositivi con Android 12 o versioni successive in res/layout-v31 e l'altro destinato alle versioni precedenti di Android 11 o versioni precedenti nella cartella res/layout predefinita.
Implementa gli angoli arrotondati
Android 12 introduce i seguenti parametri di sistema per impostare i raggi dei bordi arrotondati del widget:
system_app_widget_background_radius: il raggio dell'angolo dello sfondo del widget, che non è mai superiore a 28 dp.system_app_widget_inner_radius: il raggio dell'angolo di qualsiasi visualizzazione all'interno del widget. Questo valore è esattamente 8 dp meno del raggio dello sfondo, per allinearsi bene quando si utilizza un padding di 8 dp.
L'esempio seguente mostra un widget che utilizza system_app_widget_background_radius per l'angolo del widget e system_app_widget_inner_radius per le visualizzazioni all'interno del widget.
1 Angolo del widget.
2 Angolo di una visualizzazione all'interno del widget.
Considerazioni importanti per gli angoli arrotondati
- I lanci di terze parti e i produttori di dispositivi possono ignorare il parametro
system_app_widget_background_radiusper impostarlo su un valore inferiore a 28 dp. Il parametrosystem_app_widget_inner_radiusè sempre inferiore di 8 dp rispetto al valore disystem_app_widget_background_radius. - Se il widget non utilizza
@android:id/backgroundo non definisce uno sfondo che ne ritaglia i contenuti in base al contorno, conandroid:clipToOutlineimpostato sutrue, Avvio identifica automaticamente lo sfondo e ritaglia il widget utilizzando un rettangolo con angoli arrotondati fino a 16 dp. Consulta l'articolo Verificare la compatibilità del widget con Android 12.
Per la compatibilità dei widget con le versioni precedenti di Android, ti consigliamo di definire attributi personalizzati e di utilizzare un tema personalizzato per sostituirli per Android 12, come mostrato nei seguenti file XML di esempio:
/values/attrs.xml
<resources>
<attr name="backgroundRadius" format="dimension" />
</resources>
/values/styles.xml
<resources>
<style name="MyWidgetTheme">
<item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
</style>
</resources>
/values-31/styles.xml
<resources>
<style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
<item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
</style>
</resources>
/drawable/my_widget_background.xml
<shape xmlns:android="http://schemas.android.com/apk/res/android"
android:shape="rectangle">
<corners android:radius="?attr/backgroundRadius" />
...
</shape>
/layout/my_widget_layout.xml
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
...
android:background="@drawable/my_widget_background" />