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'la programatik olarak arayüz oluşturmanıza olanak tanıyan temel yöntemleri tanımlar. Bu araç sayesinde widget güncellendiğinde, etkinleştirildiğinde, devre dışı bırakıldığında veya silindiğinde yayınları 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. bir 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. Diğer ayrıntılar için Widget'ın varsayılan yapılandırmasını kullanma ve Kullanıcıların yerleştirilmiş widget'ları yeniden yapılandırmalarına izin verme bölümlerine göz atın.
• Android 11 (API düzeyi 30) veya önceki 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. Tek bir <appwidget-provider> öğesi kullanarak XML kaynak dosyasında AppWidgetProviderInfo nesnesini tanımlayın ve projenin res/xml/ klasörüne kaydedin.

Bu, 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ı tanımlı bir yüksekliğe ve genişliğe sahip hücre ızgarasına göre kendi penceresinde konumlar. Ç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 dosyasında widget beyan etme

Öncelikle, uygulamanızın AndroidManifest.xml dosyasında aşağıdaki örnekte gösterildiği gibi AppWidgetProvider sınıfını 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 öğesinin ACTION_APPWIDGET_UPDATE yayını kabul ettiğini belirtir. Açıkça belirtmeniz gereken tek yayın budur. AppWidgetManager, gerektiğinde diğer tüm widget yayınlarını otomatik olarak AppWidgetProvider cihazına 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ı yönetmek için kolaylık sınıfı olarak BroadcastReceiver öğesini genişletir. Yalnızca widget'la alakalı etkinlik yayınlarını alır (ör. widget güncellendiğinde, silindiğinde, etkinleştirildiğinde ve devre dışı bırakıldığında). 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, widget ilk yerleştirildiğinde ve widget 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ğırma işlevini kullanın. getAppWidgetOptions() işlevini çağırarak boyut aralıklarını ve Android 12'den itibaren bir widget örneğinin alabileceği olası boyutların listesini alabilirsiniz. Bu işlem, aşağıdaki bilgileri içeren bir Bundle değeri 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 sunuldu.

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 gerçekleştirmeniz gerekiyorsa bunu yapmak için uygun bir yerdir.

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ı olarak beyan etmeniz gerekir. Daha fazla bilgi için bu sayfadaki Manifestte widget bildirme konusuna 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 bu geri çağırma işlevinde etkinlik işleyicileri kaydedin. Widget'ınız geçici dosyalar veya veritabanları oluşturmuyor ya da temizleme işlemi gerektiren başka işlemler yapmıyorsa tanımlamanız gereken tek geri çağırma yöntemi onUpdate() olabilir.

Örneğin, dokunulduğunda bir etkinlik başlatan düğmenin yer aldığı bir widget istiyorsanız aşağıdaki AppWidgetProvider uygulamasını 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. appWidgetIds ürünündeki her girişte yinelenen bir döngü içerir. Bu döngü, bu sağlayıcının oluşturduğu her widget'ı tanımlayan bir kimlik dizisidir. 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. İkisi de saatte bir değil, iki saatte bir güncellenir.

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

Widget yayın amaçları al

AppWidgetProvider, kolaylık sınıfıdır. Widget yayınlarını doğrudan almak istiyorsanız kendi BroadcastReceiver'inizi 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 bilgili 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 düzgün bir şekilde hizalanması 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'taki 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 dp küçü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 aşağıdaki örnek XML dosyalarında gösterildiği gibi Android 12 için bunları geçersiz kılmak üzere özel bir tema kullanmanızı öneririz:

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