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:

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.

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:

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

Ek widget özellikleri

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

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:

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

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.

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.

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

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

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

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:

<resources>
  <attr name="backgroundRadius" format="dimension" />
</resources>

<resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
</resources>

<resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
</resources>

<shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  ...
</shape>

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  ...
  android:background="@drawable/my_widget_background" />