Basit bir widget oluşturma

Uygulama widget'ları, ana ekran gibi diğer uygulamalara yerleştirebileceğiniz ve düzenli olarak güncelleme alabileceğiniz küçük uygulama görünümleridir. Bu görünümler, kullanıcı arayüzünde widget olarak adlandırılır ve bir uygulama widget sağlayıcısı (veya widget sağlayıcı) ile yayınlayabilirsiniz. Diğer widget'ları barındıran uygulama bileşenlerine uygulama widget'ı ana makinesi (veya widget ana makinesi) denir. Şekil 1'de örnek bir müzik widget'ı gösterilmektedir:

Şekil 1. Müzik widget'ı örneği.

Bu belgede, widget sağlayıcı kullanarak widget'ın nasıl yayınlanacağı açıklanmaktadır. Uygulama widget'larını barındırmak için kendi AppWidgetHost'ınızı oluşturma hakkında ayrıntılı bilgi için Widget ana makinesi oluşturma başlıklı makaleyi inceleyin.

Widget'ınızı nasıl tasarlayacağınız hakkında bilgi edinmek için Uygulama widget'larına genel bakış başlıklı makaleyi inceleyin.

Widget bileşenleri

Widget oluşturmak için aşağıdaki temel bileşenlere ihtiyacınız vardır:

AppWidgetProviderInfo nesnesi

Bir widget'ın meta verilerini (ör. widget'ın düzeni, güncelleme sıklığı ve AppWidgetProvider sınıfı) açıklar. AppWidgetProviderInfo, bu dokümanda açıklandığı gibi XML'de tanımlanır.

AppWidgetProvider sınıf

Widget ile programatik olarak arayüz oluşturmanıza olanak tanıyan temel yöntemleri tanımlar. Widget güncellendiğinde, etkinleştirildiğinde, devre dışı bırakıldığında veya silindiğinde bu kanal üzerinden yayın alırsınız. AppWidgetProvider'yi manifest dosyasında beyan eder ve ardından bu dokümanda açıklandığı gibi uygulayabilirsiniz.

Düzeni görüntüleme

Widget'ın ilk düzenini tanımlar. Bu dokümanda açıklandığı gibi, düzen XML biçiminde tanımlanır.

Şekil 2'de bu bileşenlerin genel uygulama widget'ı işleme akışına nasıl uyduğu gösterilmektedir.

Şekil 2. Uygulama widget'ı işleme akışı.

Not: Android Studio, AppWidgetProviderInfo, AppWidgetProvider dosyalarını otomatik olarak oluşturabilir ve görüntüleyebilir. Yeni > Widget > Uygulama Widget'ı'nı seçin.

Widget'ınızın kullanıcı yapılandırması gerekiyorsa uygulama widget'ı yapılandırma etkinliğini uygulayın. Bu etkinlik, kullanıcıların widget ayarlarını (ör. saat widget'ının saat dilimi) değiştirmesine olanak tanır.

• Android 12'den (API düzeyi 31) itibaren varsayılan bir yapılandırma sağlayabilir ve kullanıcıların daha sonra widget'ı yeniden yapılandırmasına izin verebilirsiniz. Daha fazla bilgi için Widget'ın varsayılan yapılandırmasını kullanma ve Kullanıcıların yerleştirilen widget'ları yeniden yapılandırmasını etkinleştirme başlıklı makaleleri inceleyin.
• Android 11 (API düzeyi 30) veya daha eski sürümlerde bu etkinlik, kullanıcı widget'ı ana ekranına her eklediğinde başlatılır.

Ayrıca aşağıdaki iyileştirmeleri de öneririz: Esnek widget düzenleri, çeşitli geliştirmeler, gelişmiş widget'lar, koleksiyon widget'ları ve widget barındırıcı oluşturma.

AppWidgetProviderInfo XML'ini tanımlama

AppWidgetProviderInfo nesnesi, widget'ın temel özelliklerini tanımlar. AppWidgetProviderInfo nesnesini, tek bir <appwidget-provider> öğesi kullanarak bir XML kaynak dosyasında tanımlayın ve projenin res/xml/ klasörüne kaydedin.

Bu durum aşağıdaki örnekte gösterilmektedir:

<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>

Widget boyutlandırma özellikleri

Varsayılan ana ekran, widget'ları penceresinde belirli bir yükseklik ve genişliğe sahip bir hücre ızgarasına göre konumlandırır. Çoğu ana ekran, widget'ların yalnızca ızgara hücrelerinin tam sayı katları olan boyutlara sahip olmasına izin verir (ör. yatay olarak iki hücre, dikey olarak üç hücre).

Widget boyutlandırma özellikleri, widget'ınız için varsayılan bir boyut belirtmenize ve widget'ın boyutu için alt ve üst sınırlar sağlamanıza olanak tanır. Bu bağlamda, bir widget'ın varsayılan boyutu, widget'ın ana ekrana ilk eklendiğinde aldığı boyuttur.

Aşağıdaki tabloda, widget boyutlandırmasıyla ilgili <appwidget-provider> özellikleri açıklanmaktadır:

Özellikler ve açıklama
targetCellWidth ve targetCellHeight (Android 12), minWidth ve minHeight	Android 12'den itibaren targetCellWidth ve targetCellHeight özellikleri, widget'ın varsayılan boyutunu grid hücreleri Bu özellikler Android 11 ve önceki sürümlerde yoksayılır ve ana ekran ızgaraya dayalı bir düzeni desteklemiyorsa yoksayılabilir. minWidth ve minHeight özellikleri, widget'ın varsayılan boyutunu dp cinsinden belirtir. Bir widget'ın minimum genişlik veya yükseklik değerleri, hücrelerin boyutlarıyla eşleşmiyorsa değerler en yakın hücre boyutuna yuvarlanır. Kullanıcının cihazı targetCellWidth ve targetCellHeight özelliklerini desteklemiyorsa uygulamanızın minWidth ve minHeight özelliklerini kullanabilmesi için her iki özellik grubunu da (targetCellWidth ve targetCellHeight ile minWidth ve minHeight) belirtmenizi öneririz. Destekleniyorsa targetCellWidth ve targetCellHeight özellikleri, minWidth ve minHeight özelliklerine göre öncelikli olur.
minResizeWidth ve minResizeHeight	Widget'ın mutlak minimum boyutunu belirtin. Bu değerler, widget'ın okunaklı olmadığı veya başka bir şekilde kullanılamadığı boyutu belirtir. Bu özelliklerin kullanılması, kullanıcının widget'ı varsayılan widget boyutundan daha küçük bir boyuta yeniden boyutlandırmasına olanak tanır. minResizeWidth özelliği, minWidth değerinden büyükse veya yatay yeniden boyutlandırma etkin değilse yoksayılır. resizeMode adresine göz atın. Benzer şekilde, minResizeHeight özelliği minHeight değerinden büyükse veya dikey yeniden boyutlandırma etkin değilse yoksayılır.
maxResizeWidth ve maxResizeHeight	Widget'ın önerilen maksimum boyutunu belirtin. Değerler, grid hücre boyutlarının katı değilse en yakın hücre boyutuna yuvarlanır. maxResizeWidth özelliği, minWidth değerinden küçükse veya yatay yeniden boyutlandırma etkin değilse yoksayılır. resizeMode adresine göz atın. Benzer şekilde, maxResizeHeight özelliği minHeight değerinden büyükse veya dikey yeniden boyutlandırma etkin değilse yoksayılır. Android 12'de kullanıma sunulmuştur.
resizeMode	Bir widget'ın yeniden boyutlandırılabileceği kuralları belirtir. Ana ekran widget'larını yatay, dikey veya her iki eksende de yeniden boyutlandırılabilir hale getirmek için bu özelliği kullanabilirsiniz. Kullanıcılar, yeniden boyutlandırma tutamaklarını göstermek için bir widget'a dokunup basılı tutar, ardından düzen ızgarasında boyutunu değiştirmek için yatay veya dikey tutamaklarla widget'ı sürükler. resizeMode özelliğinin değerleri şunlardır: horizontal, vertical ve none. Bir widget'ı yatay ve dikey olarak yeniden boyutlandırılabilir olarak tanımlamak için horizontal|vertical öğesini kullanın.

Örnek

Önceki tablodaki özelliklerin widget boyutunu nasıl etkilediğini göstermek için aşağıdaki özellikleri varsayalım:

• Izgara hücresi 30 dp genişliğinde ve 50 dp yüksekliğindedir.
• Aşağıdaki özellik spesifikasyonu sağlanmıştır:

<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" />

Android 12'den itibaren:

Widget'ın varsayılan boyutu olarak targetCellWidth ve targetCellHeight özelliklerini kullanın.

Widget'ın boyutu varsayılan olarak 2x2'dir. Widget'ı 2x1'e kadar küçültebilir veya 4x3'e kadar büyütebilirsiniz.

Android 11 ve önceki sürümler:

Widget'ın varsayılan boyutunu hesaplamak için minWidth ve minHeight özelliklerini kullanın.

Varsayılan genişlik = Math.ceil(80 / 30) = 3

Varsayılan yükseklik = Math.ceil(80 / 50) = 2

Widget'ın boyutu varsayılan olarak 3x2'dir. Widget'ı 2x1'e kadar küçültebilir veya tam ekrana kadar büyütebilirsiniz.

Not: Gerçek widget boyutu hesaplaması, widget kenar boşluklarını ve ızgara hücreleri arasındaki boşlukları da içerdiğinden önceki formülden daha karmaşıktır.

Ek widget özellikleri

Aşağıdaki tabloda, widget boyutlandırması dışındaki niteliklerle ilgili <appwidget-provider> özellikleri açıklanmaktadır.

Özellikler ve açıklama
updatePeriodMillis	Widget çerçevesinin, onUpdate() geri çağırma yöntemini çağırarak AppWidgetProvider'ten ne sıklıkta güncelleme isteğinde bulunacağını tanımlar. Gerçek güncellemenin bu değerle tam olarak aynı zamanda gerçekleşmesi garanti edilmez. Ayrıca, pili korumak için mümkün olduğunca seyrek şekilde (en fazla saatte bir) güncelleme yapmanızı öneririz. Uygun bir güncelleme dönemi seçerken dikkate alınacak hususların tam listesi için Widget içeriğini güncellemeyle ilgili optimizasyonlar başlıklı makaleyi inceleyin.
initialLayout	Widget düzenini tanımlayan düzen kaynağını gösterir.
configure	Kullanıcı widget'ı eklediğinde başlatılan etkinliği tanımlar ve kullanıcının widget özelliklerini yapılandırmasına olanak tanır. Kullanıcıların widget'ları yapılandırmasına izin verme başlıklı makaleyi inceleyin. Android 12'den itibaren uygulamanız ilk yapılandırmayı atlayabilir. Ayrıntılar için Widget'ın varsayılan yapılandırmasını kullanma başlıklı makaleyi inceleyin.
description	Widget seçicinin widget'ınız için göstereceği açıklamayı belirtir. Android 12'de kullanıma sunulmuştur.
previewLayout (Android 12) ve previewImage (Android 11 ve önceki sürümler)	Android 12'den itibaren previewLayout özelliği, widget'ın varsayılan boyutuna ayarlanmış bir XML düzeni olarak sağladığınız ölçeklenebilir bir önizleme belirtir. İdeal olarak, bu özellik olarak belirtilen düzen XML'si, gerçek widget ile gerçekçi varsayılan değerlere sahip aynı düzen XML'si olmalıdır. Android 11 veya önceki sürümlerde previewImage özelliği, widget'ın yapılandırıldıktan sonraki görünümünün önizlemesini belirtir. Bu önizleme, kullanıcının uygulama widget'ını seçerken gördüğü önizlemedir. Aksi takdirde kullanıcıya uygulamanızın başlatıcı simgesi gösterilir. Bu alan, AndroidManifest.xml dosyasında <receiver> öğesindeki android:previewImage özelliğine karşılık gelir. Not: Kullanıcının cihazı previewLayout'i desteklemiyorsa uygulamanızın previewImage'i kullanabilmesi için hem previewImage hem de previewLayout özelliklerini belirtmenizi öneririz. Ayrıntılı bilgi için Yükseltilebilir widget önizlemeleriyle geriye dönük uyumluluk başlıklı makaleyi inceleyin.
autoAdvanceViewId	Widget'ın ana makinesi tarafından otomatik olarak ilerletilen widget alt görüntüsünün görüntü kimliğini belirtir.
widgetCategory	Widget'ınızın ana ekranda (home_screen), kilit ekranında (keyguard) veya her ikisinde de gösterilip gösterilemeyeceğini belirtir. Android 5.0 ve sonraki sürümlerde yalnızca home_screen geçerlidir.
widgetFeatures	Widget'ın desteklediği özellikleri belirtir. Örneğin, widget'ınızın bir kullanıcı tarafından eklendiğinde varsayılan yapılandırmasını kullanmasını istiyorsanız hem configuration_optional hem de reconfigurable işaretlerini belirtin. Bu işlem, kullanıcı widget'ı ekledikten sonra yapılandırma etkinliğinin başlatılmasını atlar. Kullanıcı, daha sonra widget'ı yeniden yapılandırabilir.

Widget yayınlarını işlemek için AppWidgetProvider sınıfını kullanma

AppWidgetProvider sınıfı, widget yayınlarını yönetir ve widget yaşam döngüsü etkinliklerine yanıt olarak widget'ı günceller. Aşağıdaki bölümlerde, AppWidgetProvider öğesinin manifest dosyasında nasıl tanımlanacağı ve ardından nasıl uygulanacağı açıklanmaktadır.

Manifest'te widget beyan etme

Öncelikle, uygulamanızın AndroidManifest.xml dosyasında AppWidgetProvider sınıfını aşağıdaki örnekte gösterildiği gibi beyan edin:

<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>

<receiver> öğesi, widget'ın kullandığı AppWidgetProvider öğesini belirten android:name özelliğini gerektirir. AppWidgetProvider'ünüze ayrı bir işlemin yayınlanması gerekmediği sürece bileşen dışa aktarılmamalıdır. Bu durum genellikle geçerli değildir.

<intent-filter> öğesi, android:name özelliğine sahip bir <action> öğesi içermelidir. Bu özellik, AppWidgetProvider'in ACTION_APPWIDGET_UPDATE yayınını kabul ettiğini belirtir. Açıkça belirtmeniz gereken tek yayın budur. AppWidgetManager, diğer tüm widget yayınlarını gerektiğinde otomatik olarak AppWidgetProvider'a gönderir.

<meta-data> öğesi, AppWidgetProviderInfo kaynağını belirtir ve aşağıdaki özellikleri gerektirir:

• android:name: Meta veri adını belirtir. Verileri AppWidgetProviderInfo tanımlayıcısı olarak tanımlamak için android.appwidget.provider öğesini kullanın.
• android:resource: AppWidgetProviderInfo kaynak konumunu belirtir.

AppWidgetProvider sınıfını uygulama

AppWidgetProvider sınıfı, widget yayınlarını işlemek için kolaylık sınıfı olarak BroadcastReceiver'yi genişletir. Yalnızca widget'la alakalı etkinlik yayınlarını (ör. widget güncellendiğinde, silindiğinde, etkinleştirildiğinde ve devre dışı bırakıldığında) alır. Bu yayın etkinlikleri gerçekleştiğinde aşağıdaki AppWidgetProvider yöntemleri çağrılır:

onUpdate()

Bu işlev, widget'ı AppWidgetProviderInfo içindeki updatePeriodMillis özelliğiyle tanımlanan aralıklarla güncellemek için çağrılır. Daha fazla bilgi için bu sayfadaki ek widget özelliklerini açıklayan tabloya bakın.

Bu yöntem, kullanıcı widget'ı eklediğinde de çağrılır. Bu nedenle, View nesneleri için etkinlik işleyicileri tanımlama veya widget'ta görüntülenecek verileri yüklemek için iş başlatma gibi temel kurulumu gerçekleştirir. Ancak, bir yapılandırma etkinliğini configuration_optional işareti olmadan bildirirseniz kullanıcı widget'ı eklediğinde bu yöntem çağrılmaz ancak sonraki güncellemeler için çağrılır. Yapılandırma tamamlandığında ilk güncellemeyi gerçekleştirme sorumluluğu yapılandırma etkinliğinindir. Daha fazla bilgi için Kullanıcıların uygulama widget'larını yapılandırmasına izin verme başlıklı makaleyi inceleyin.

En önemli geri çağırma işlevi onUpdate()'dir. Daha fazla bilgi için bu sayfadaki onUpdate() sınıfıyla etkinlikleri işleme bölümüne bakın.

onAppWidgetOptionsChanged()

Bu işlev, widget ilk yerleştirildiğinde ve widget yeniden boyutlandırıldığında çağrılır. Widget'ın boyut aralıklarına göre içeriği göstermek veya gizlemek için bu geri çağırma işlevini kullanın. getAppWidgetOptions() çağrısını yaparak boyut aralıklarını (ve Android 12'den itibaren, bir widget örneğinin alabileceği olası boyutların listesini) alın. Bu çağrı, aşağıdakileri içeren bir Bundle döndürür:

• OPTION_APPWIDGET_MIN_WIDTH: Bir widget örneğinin genişliğinin alt sınırını dp birimlerinde içerir.
• OPTION_APPWIDGET_MIN_HEIGHT: Bir widget örneğinin yüksekliğinin alt sınırını dp cinsinden içerir.
• OPTION_APPWIDGET_MAX_WIDTH: Bir widget örneğinin genişliğinin üst sınırını dp birimlerinde içerir.
• OPTION_APPWIDGET_MAX_HEIGHT: Bir widget örneğinin yüksekliğinin üst sınırını dp birimlerinde içerir.
• OPTION_APPWIDGET_SIZES: Bir widget örneğinin alabileceği olası boyutların (List<SizeF>) dp birimlerindeki listesini içerir. Android 12'de kullanıma sunulmuştur.

onDeleted(Context, int[])

Bu işlev, widget barındırıcıdan her widget silindiğinde çağrılır.

onEnabled(Context)

Bu işlev, widget'ın bir örneği ilk kez oluşturulduğunda çağrılır. Örneğin, kullanıcı widget'ınızın iki örneğini eklerse bu işlev yalnızca ilk kez çağrılır. Yeni bir veritabanı açmanız veya tüm widget örnekleri için yalnızca bir kez yapılması gereken başka bir kurulum yapmanız gerekiyorsa bunu yapmak için bu sayfayı kullanabilirsiniz.

onDisabled(Context)

Bu yöntem, widget'ınızın son örneği widget ana makinesinden silindiğinde çağrılır. Burada, onEnabled(Context)'te yapılan tüm çalışmaları (ör. geçici bir veritabanını silme) temizleyebilirsiniz.

onReceive(Context, Intent)

Bu yöntem her yayın için ve önceki geri çağırma yöntemlerinin her biri için çağrılır. Varsayılan AppWidgetProvider uygulaması tüm widget yayınlarını filtrelediği ve önceki yöntemleri uygun şekilde çağırdığı için normalde bu yöntemi uygulamanız gerekmez.

AppWidgetProvider sınıf uygulamanızı, AndroidManifest içindeki <receiver> öğesini kullanarak yayın alıcısı olarak beyan etmeniz gerekir. Daha fazla bilgi için bu sayfadaki Manifest dosyasında widget beyan etme bölümüne bakın.

onUpdate() sınıfıyla etkinlikleri işleme

configuration_optional işareti olmayan bir yapılandırma etkinliği kullanmadığınız sürece her widget bir ana makineye eklendiğinde çağrıldığı için en önemli AppWidgetProvider geri çağırma işlevi onUpdate()'dur. Widget'ınız kullanıcı etkileşimi etkinliklerini kabul ediyorsa etkinlik işleyicileri bu geri çağırma işlevine kaydedin. Widget'ınız geçici dosya veya veritabanı oluşturmuyorsa ya da temizlenmesi gereken başka bir işlem yapmıyorsa tanımlamanız gereken tek geri çağırma yöntemi onUpdate() olabilir.

Örneğin, dokunulduğunda bir etkinliği başlatan bir düğme içeren bir widget istiyorsanız AppWidgetProvider için aşağıdaki uygulamayı kullanabilirsiniz:

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);
        }
    }
}

Bu AppWidgetProvider, yalnızca onUpdate() yöntemini tanımlar. Bu yöntem, Activity başlatan ve setOnClickPendingIntent(int, PendingIntent) kullanarak widget'ın düğmesine ekleyen bir PendingIntent oluşturmak için kullanılır. Bu sağlayıcı tarafından oluşturulan her widget'ı tanımlayan bir kimlik dizisi olan appWidgetIds'deki her girişi iteratif olarak işleyen bir döngü içerir. Kullanıcı widget'ın birden fazla örneğini oluşturursa bunların tümü eşzamanlı olarak güncellenir. Ancak widget'ın tüm örnekleri için yalnızca bir updatePeriodMillis planı yönetilir. Örneğin, güncelleme programı iki saatte bir olarak tanımlanırsa ve widget'ın ikinci bir örneği ilkinden bir saat sonra eklenirse her ikisi de ilk widget tarafından tanımlanan dönemde güncellenir ve ikinci güncelleme dönemi yoksayılır. Her ikisi de her saat değil, iki saatte bir güncellenir.

Not: AppWidgetProvider, BroadcastReceiver'in bir uzantısı olduğundan, geri çağırma yöntemleri döndükten sonra işleminizin çalışmaya devam edeceği garanti edilmez. Yayın yaşam döngüsü hakkında bilgi edinmek için BroadcastReceiver bölümüne bakın. Widget kurulum işleminiz birkaç saniye sürebiliyorsa (ör. web istekleri gerçekleştirirken) ve işleminizin devam etmesini istiyorsanız onUpdate() yönteminde WorkManager kullanarak bir Task başlatabilirsiniz. Görev içinden, AppWidgetProvider'ün uygulama yanıt vermiyor (ANR) hatası nedeniyle kapanmasından endişe etmeden widget'ta kendi güncellemelerinizi yapabilirsiniz.

Daha fazla bilgi için ExampleAppWidgetProvider.java örnek sınıfına bakın.

Widget yayını intent'lerini alma

AppWidgetProvider, kolaylık sınıfıdır. Widget yayınlarını doğrudan almak istiyorsanız kendi BroadcastReceiver öğenizi uygulayabilir veya onReceive(Context,Intent) geri çağırma işlevini geçersiz kılabilirsiniz. Dikkat etmeniz gereken niyetler şunlardır:

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

Widget düzenini oluşturma

Widget'ınız için XML'de bir ilk düzen tanımlamanız ve bunu projenin res/layout/ dizinine kaydetmeniz gerekir. Ayrıntılar için Tasarım yönergelerine bakın.

Sayfa düzenleri hakkında bilginiz varsa widget düzenini oluşturmak kolaydır. Ancak widget düzenlerinin RemoteViews'a dayalı olduğunu unutmayın. RemoteViews her tür düzeni veya görüntüleme widget'ını desteklemez. RemoteViews tarafından desteklenen özel görünümleri veya görünümlerin alt sınıflarını kullanamazsınız.

RemoteViews, düzen kaynaklarını çalışma zamanında tembel bir şekilde şişirmek için kullanabileceğiniz görünmez, sıfır boyutlu bir View olan ViewStub'yi de destekler.

Durum bilgisine sahip davranış desteği

Android 12, aşağıdaki mevcut bileşenleri kullanarak durum bilgisine sahip davranış desteği ekler:

• CheckBox

• Switch

• RadioButton

Widget hâlâ durum bilgisine sahip değil. Uygulamanız durumu depolamalı ve durum değişikliği etkinliklerine kaydolmalıdır.

Şekil 3. Durum bilgisine sahip davranış örneği.

Not: RemoteViews.setCompoundButtonChecked kullanarak mevcut onay durumunu her zaman açıkça ayarlayın. Aksi takdirde, widget'ınız sürüklendiğinde veya yeniden boyutlandırıldığında beklenmedik sonuçlarla karşılaşabilirsiniz.

Aşağıdaki kod örneğinde bu bileşenlerin nasıl uygulanacağı gösterilmektedir.

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));

İki düzen sağlayın: Biri res/layout-v31 klasöründe Android 12 veya sonraki sürümleri çalıştıran cihazları, diğeri ise varsayılan res/layout klasöründe Android 11 veya önceki sürümleri çalıştıran cihazları hedeflemelidir.

Yuvarlatılmış köşeler uygulama

Android 12, widget'ınızın yuvarlatılmış köşelerinin yarıçapını ayarlamak için aşağıdaki sistem parametrelerini kullanıma sunar:

• system_app_widget_background_radius: widget arka planının köşe yarıçapı. Bu değer hiçbir zaman 28 dp'den büyük olamaz.

• system_app_widget_inner_radius: widget'ın içindeki herhangi bir görünümün köşe yarıçapı. Bu değer, 8 dp dolgu kullanıldığında güzelce hizalanabilmesi için arka plan yarıçapından tam olarak 8 dp daha azdır.

Aşağıdaki örnekte, widget'ın köşesi için system_app_widget_background_radius ve widget'ın içindeki görüntülemeler için system_app_widget_inner_radius kullanılan bir widget gösterilmektedir.

Şekil 4. Yuvarlak köşeler

1 Widget'ın köşesi.

2 Widget'ın içindeki bir görünümün köşesi.

Yuvarlatılmış köşelerle ilgili dikkat edilmesi gerekenler

• Üçüncü taraf başlatıcılar ve cihaz üreticileri, system_app_widget_background_radius parametresini 28 dp'den küçük olacak şekilde geçersiz kılabilir. system_app_widget_inner_radius parametresi, system_app_widget_background_radius değerinden her zaman 8 ondalık basamak daha düşüktür.
• Widget'ınız @android:id/background kullanmıyorsa veya içeriğini dış hatlara göre kırpacak bir arka plan tanımlamıyorsa (android:clipToOutline true olarak ayarlanmışsa) başlatıcı arka planı otomatik olarak tanımlar ve widget'ı 16 dp'ye kadar yuvarlatılmış köşeleri olan bir dikdörtgen kullanarak kırpar. Widget'ınızın Android 12 ile uyumlu olduğundan emin olma başlıklı makaleyi inceleyin.

Android'in önceki sürümleriyle widget uyumluluğu için özel özellikler tanımlamanızı ve Android 12 için bunları geçersiz kılmak üzere özel bir tema kullanmanızı öneririz. Aşağıdaki örnek XML dosyalarında gösterildiği gibi:

/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" />