Basit bir widget oluşturma

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

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

Bu dokümanda, widget sağlayıcı kullanarak widget'ların nasıl yayınlanacağı açıklanmaktadır. Uygulama widget'larını barındırmak için kendi AppWidgetHost'inizi oluşturma hakkında ayrıntılı bilgi için Widget ana makinesi oluşturma bölümüne bakın.

Widget'ınızı nasıl tasarlayacağınızla ilgili bilgi 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 nesne
Bir widget'ın meta verilerini (ör. widget'ın düzeni, güncelleme sıklığı ve AppWidgetProvider sınıfı) açıklar. AppWidgetProviderInfo, bu belgede açıklandığı gibi XML'de tanımlanmıştır.
AppWidgetProvider sınıfı
Widget ile programlı arayüz oluşturmanızı sağlayan temel yöntemleri tanımlar. Bu widget üzerinden, widget güncellendiğinde, etkinleştirildiğinde, devre dışı bırakıldığında veya silindiğinde yayın alırsınız. Manifestte AppWidgetProvider beyan eder ve ardından bu belgede açıklandığı gibi uygularsınız.
Düzeni göster
Widget'ın ilk düzenini tanımlar. Düzen, bu dokümanda açıklandığı gibi XML'de tanımlanır.

Şekil 2'de bu bileşenlerin genel uygulama widget'ı işleme akışındaki rolü gösterilmektedir.

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

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

Ayrıca şu iyileştirmeleri de öneriyoruz: esnek widget düzenleri, çeşitli geliştirmeler, gelişmiş widget'lar, koleksiyon widget'ları ve widget ana makinesi oluşturma.

AppWidgetProviderInfo XML'sini bildirme

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

Bu, aşağıdaki örnekte gösterilmiştir:

<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, tanımlı bir yüksekliğe ve genişliğe sahip bir hücre ızgarasına göre widget'ları penceresine yerleştirir. Çoğu ana ekran yalnızca widget'ların, ızgara hücrelerinin tam sayı katları olan boyutları almasına izin verir. Örneğin, yatay olarak dikey olarak üç hücreyi bölen iki hücre.

Widget boyutlandırma özellikleri, widget'ınız için varsayılan bir boyut belirtmenize olanak tanır ve widget'ın boyutuyla ilgili alt ve üst sınırlar sağlar. Bu bağlamda, bir widget'ın varsayılan boyutu, widget ana ekrana ilk eklendiğinde alacağı 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 ızgara hücreleri cinsinden belirtir. Bu özellikler, Android 11 ve önceki sürümlerde yoksayılır ve ana ekran ızgara tabanlı bir düzeni desteklemiyorsa yoksayılabilir.
  • minWidth ve minHeight özellikleri, widget'ın varsayılan boyutunu dp cinsinden belirtir. Widget'ın minimum genişlik veya yüksekliğine ilişkin değerler, hücrelerin boyutlarıyla eşleşmiyorsa değerler en yakın hücre boyutuna yuvarlanır.
Hem targetCellWidth hem de targetCellHeight ile minWidth ile minHeight özellik gruplarının her ikisini de belirtmenizi öneririz. Böylece, kullanıcının cihazı targetCellWidth ve targetCellHeight'yi desteklemiyorsa uygulamanız minWidth ve minHeight kullanmaya devam edebilir. Destekleniyorsa targetCellWidth ve targetCellHeight özellikleri, minWidth ve minHeight özelliklerine göre önceliklidir.
minResizeWidth ve minResizeHeight Widget'ın mutlak minimum boyutunu belirtin. Bu değerler, widget'ın okunaksız veya başka bir şekilde kullanılamaz olduğu boyutu belirtir. Bu özelliklerin kullanılması, kullanıcının widget'ı varsayılan widget boyutundan daha küçük bir boyuta getirmek üzere yeniden boyutlandırmasını sağlar. minResizeWidth özelliği, minWidth değerinden büyükse veya yatay yeniden boyutlandırma etkin değilse yoksayılır. İlgili konu: resizeMode. 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 için önerilen maksimum boyutu belirtin. Değerler, ızgara 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. İlgili konu: resizeMode. Benzer şekilde, minHeight değerinden büyükse veya dikey yeniden boyutlandırma etkin değilse maxResizeHeight özelliği yoksayılır. Android 12'de kullanıma sunuldu.
resizeMode Widget'ların yeniden boyutlandırılabileceği kuralları belirtir. Ana ekran widget'larını yatay, dikey veya her iki eksende yeniden boyutlandırılabilir yapmak için bu özelliği kullanabilirsiniz. Kullanıcılar bir widget'ın yeniden boyutlandırma tutamaçlarını görüntülemek için dokunup basılı tutar, ardından düzen ızgarasındaki boyutunu değiştirmek için yatay veya dikey tutamaçları sürükleyin. resizeMode özelliğinin değerleri arasında horizontal, vertical ve none bulunur. Bir widget'ı yatay ve dikey olarak yeniden boyutlandırılabilir olarak tanımlamak için horizontal|vertical özelliğini kullanın.

Örnek

Yukarıdaki tabloda yer alan özelliklerin widget boyutlandırmasını nasıl etkilediğini göstermek için aşağıdaki spesifikasyonları ele alın:

  • Bir ızgara hücresi 30 dp genişliğinde ve 50 dp uzunluğundadır.
  • 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 başlayarak:

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

Widget'ın boyutu varsayılan olarak 2x2'dir. Widget en fazla 2x1 veya 4x3 boyutuna kadar yeniden boyutlandırılabilir.

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, boyutu en fazla 2x1 olacak şekilde veya tam ekrana kadar yeniden boyutlandırılabilir.

Ek widget özellikleri

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

Özellikler ve açıklama
updatePeriodMillis Widget çerçevesinin ne sıklıkta onUpdate() geri çağırma yöntemini çağırarak AppWidgetProvider öğesinden güncelleme isteğinde bulunduğunu tanımlar. Gerçek güncellemenin bu değerle tam olarak zamanında gerçekleşeceği garanti edilmez. Ayrıca, pil tasarrufu yapmak için güncellemenin mümkün olduğunca sık (saatte bir defadan fazla değil) gerçekleştirilmesini öneririz. Uygun bir güncelleme dönemini seçmek için göz önünde bulundurulması gereken noktaların tam listesi için Widget içeriğini güncelleme optimizasyonları bölümüne bakın.
initialLayout Widget düzenini tanımlayan düzen kaynağına işaret eder.
configure Kullanıcı widget'ı eklediğinde başlatılan etkinliği tanımlayarak 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. Uygulamanız, Android 12 sürümünden itibaren ilk yapılandırmayı atlayabilir. Ayrıntılar için Widget'ın varsayılan yapılandırmasını kullanma bölümüne bakın.
description Widget'ınız için görüntülenecek widget seçici açıklamasını belirtir. Android 12'de kullanıma sunuldu.
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çi varsayılan değerlere sahip gerçek widget ile aynı düzen XML'idir.
  • Android 11 veya önceki sürümlerde previewImage özelliği, widget'ın yapılandırıldıktan sonra nasıl görüneceğine dair bir önizleme belirtir. Kullanıcı, uygulama widget'ını seçerken bunu görür. Sağlanmazsa kullanıcı bunun yerine uygulamanızın başlatıcı simgesini görür. Bu alan, AndroidManifest.xml dosyasındaki <receiver> öğesindeki android:previewImage özelliğine karşılık gelir.
Not: previewImage ve previewLayout özelliklerinin birlikte belirtilmesini öneririz. Böylece, kullanıcının cihazı previewLayout özelliğini desteklemiyorsa uygulamanız previewImage kullanmaya devam edebilir. Daha fazla bilgi için Ölçeklenebilir widget önizlemeleriyle geriye dönük uyumluluk bölümüne bakın.
autoAdvanceViewId Widget'ın ana makinesi tarafından otomatik olarak geliştirilen widget alt görünümünün görünüm kimliğini belirtir.
widgetCategory Widget'ınızın ana ekranda (home_screen), kilit ekranında (keyguard) veya her ikisinde görüntülenip görüntülenemeyeceğini tanımlar. Android 5.0 ve sonraki sürümler için yalnızca home_screen geçerlidir.
widgetFeatures Widget tarafından desteklenen özellikleri tanımlar. Örneğin, bir kullanıcı tarafından eklendiğinde widget'ınızın varsayılan yapılandırmasını kullanmasını istiyorsanız hem configuration_optional hem de reconfigurable işaretlerini belirtin. Bu ayar, 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ü olaylarına göre widget'ı günceller. Aşağıdaki bölümlerde, manifest dosyasında AppWidgetProvider öğesinin nasıl beyan edileceği ve sonrasında nasıl uygulanacağı açıklanmaktadır.

Manifest'te widget bildirme

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

<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 tarafından kullanılan AppWidgetProvider öğesini belirten android:name özelliğini gerektirir. Ayrı bir işlemin AppWidgetProvider cihazınıza yayın yapması gerekmediği sürece bileşen dışa aktarılmamalıdır. Bu durum genellikle yaşanmaz.

<intent-filter> öğesi, android:name özelliğine sahip bir <action> öğesi içermelidir. Bu özellik, AppWidgetProvider öğesinin ACTION_APPWIDGET_UPDATE yayınını kabul ettiğini belirtir. Açıkça beyan etmeniz gereken tek yayın budur. AppWidgetManager, diğer tüm widget yayınlarını gerektiği şekilde AppWidgetProvider aracına otomatik olarak 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 kodunu 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 bir kolaylık sınıfı olarak BroadcastReceiver kapsamını genişletir. Yalnızca widget'ın güncellenmesi, silinmesi, etkinleştirilmesi ve devre dışı bırakılması gibi widget'la alakalı etkinlik yayınlarını alır. Bu yayın etkinlikleri gerçekleştiğinde aşağıdaki AppWidgetProvider yöntemleri çağrılır:

onUpdate()
Bu işlem, AppWidgetProviderInfo öğesinde updatePeriodMillis özelliği tarafından tanımlanan aralıklarla widget'ı 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. Böylece View nesneleri için etkinlik işleyiciler tanımlama veya widget'ta görüntülenecek verileri yükleme işlerini başlatma gibi temel ayarları gerçekleştirir. Bununla birlikte, configuration_optional işareti olmadan bir yapılandırma etkinliği bildirirseniz kullanıcı widget'ı eklediğinde bu yöntem çağrılanmaz, ancak sonraki güncellemeler için çağrılanır. Yapılandırma tamamlandığında ilk güncellemeyi yapmak yapılandırma etkinliğinin sorumluluğundadır. Daha fazla bilgi için Kullanıcıların uygulama widget'larını yapılandırmasına olanak tanıma başlıklı makaleye göz atın.
En önemli geri arama onUpdate(). 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 her 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ğırmayı kullanın. Boyut aralıklarını (ve Android 12'den itibaren, bir widget örneğinin alabileceği olası boyutların listesini) almak için getAppWidgetOptions() yöntemini çağırın. Bu işlem, aşağıdakileri içeren bir Bundle döndürür:

onDeleted(Context, int[])

Bu, widget ana makinesinden bir widget her silindiğinde çağrılır.

onEnabled(Context)

Bu, bir widget örneği ilk kez oluşturulduğunda çağrılır. Örneğin, kullanıcı widget'ınızın iki örneğini eklerse buna yalnızca ilk kez çağrı yapı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 burası uygun bir yerdir.

onDisabled(Context)

Bu işlev, widget'ınızın son örneği widget ana makinesinden silindiğinde çağırılır. Bu, onEnabled(Context) üzerinde yapılan geçici veritabanını silme gibi işleri temizlediğiniz yerdir.

onReceive(Context, Intent)

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

AndroidManifest içindeki <receiver> öğesini kullanarak AppWidgetProvider sınıf uygulamanızı bir yayın alıcısı olarak tanımlamanız gerekir. Daha fazla bilgi için bu sayfadaki Manifest'te widget bildirme bölümüne bakın.

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

En önemli AppWidgetProvider geri çağırması onUpdate() olduğundan, configuration_optional işareti olmadan bir yapılandırma etkinliği kullanmadığınız sürece her widget bir ana makineye eklendiğinde çağrılır. Widget'ınız herhangi bir kullanıcı etkileşimi etkinliğini kabul ediyorsa bu geri çağırmaya etkinlik işleyicilerini kaydedin. Widget'ınız geçici dosyalar veya veritabanları oluşturmazsa ya da temizlik gerektiren başka işlemler gerçekleştirmezse tanımlamanız gereken tek geri çağırma yöntemi onUpdate() olabilir.

Örneğin, dokunulduğunda bir etkinliği başlatan düğme içeren bir widget isterseniz aşağıdaki AppWidgetProvider uygulamasını 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. Bunu, bir Activity başlatan ve setOnClickPendingIntent(int, PendingIntent) kullanarak widget'ın düğmesine ekleyen bir PendingIntent oluşturmak için kullanır. Bu sağlayıcı tarafından oluşturulan her widget'ı tanımlayan bir kimlik dizisi olan appWidgetIds içindeki her bir girişi yineleyen bir döngü içerir. Kullanıcı widget'ın birden fazla örneğini oluşturursa hepsi aynı anda güncellenir. Ancak widget'ın tüm örnekleri için yalnızca bir updatePeriodMillis programı yönetilir. Örneğin, güncelleme programı iki saatte bir yapılacak şekilde tanımlanırsa ve ilkinden bir saat sonra widget'ın ikinci bir örneği eklenirse her ikisi de birinci tarafından tanımlanan dönemde güncellenir ve ikinci güncelleme dönemi yoksayılır. Her ikisi de saatte bir değil, iki saatte bir güncellenir.

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

Widget yayın amaçlarını alma

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

Widget düzenini oluşturma

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

Düzenler hakkında bilginiz varsa widget düzenini kolayca oluşturabilirsiniz. Bununla birlikte, widget düzenlerinin her tür düzeni veya görünüm widget'ını desteklemeyen RemoteViews öğesini temel aldığını unutmayın. RemoteViews tarafından desteklenen özel görünümleri veya görünümlerin alt sınıflarını kullanamazsınız.

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

Durum bilgili davranış desteği

Android 12, aşağıdaki mevcut bileşenleri kullanarak durum bilgili davranış için destek sağlar:

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

Durum bilgili davranışı gösteren alışveriş listesi widget&#39;ı örneği
Şekil 3. Durum bilgili davranış örneği.

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 içinde Android 12 veya sonraki sürümleri çalıştıran, diğeri de varsayılan res/layout klasöründe Android 11 veya önceki sürümleri hedefleyen diğeri.

Yuvarlatılmış köşeler uygulayın

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

  • system_app_widget_background_radius: Widget arka planının köşe yarıçapı; hiçbir zaman 28 dp'den büyük değildir.

  • system_app_widget_inner_radius: Widget'ın içindeki herhangi bir görünümün köşe yarıçapı. Bu, 8 dp dolgu kullanırken güzel bir şekilde hizalamak için arka plan yarıçapından tam olarak 8 dp daha küçüktür.

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

Widget arka planının yarıçaplarını ve widget içindeki görünümleri gösteren widget
Şekil 4. Yuvarlatılmış köşeler.

1 Widget'ın köşesi.

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

Yuvarlatılmış köşeler için dikkat edilmesi gereken önemli noktalar

  • Üçüncü taraf başlatıcılar ve cihaz üreticileri, system_app_widget_background_radius parametresini geçersiz kılarak 28 dp'den küçük olabilir. system_app_widget_inner_radius parametresi, her zaman system_app_widget_background_radius değerinden 8 dp küçüktür.
  • Widget'ınız @android:id/background kullanmıyorsa veya içeriğini dış çizgiye göre kırpan (android:clipToOutline ayarı true değerine ayarlıyken) bir arka plan tanımlamazsa başlatıcı otomatik olarak arka planı tanımlar ve köşeleri 16 dp'ye kadar yuvarlatılmış bir dikdörtgen kullanarak widget'ı kırpar. Widget'ınızın Android 12 ile uyumlu olduğundan emin olma bölümüne göz atın.

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

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