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 olarak adlandırılır ve bir uygulama widget'ı sağlayıcısı (veya widget sağlayıcısı) ile bir görünüm yayınlayabilirsiniz. Diğer widget'ları barındıran bir uygulama bileşenine, uygulama widget'ı ana makinesi (veya widget ana makinesi) adı verilir. Şekil 1'de örnek bir müzik widget'ı gösterilmektedir:

Bu dokümanda, widget'ın bir widget sağlayıcısı kullanılarak 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ı bilgiyi Widget ana makinesi oluşturma bölümünde bulabilirsiniz.

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'la ilgili meta verileri (ör. widget'ın düzeni, güncelleme sıklığı ve AppWidgetProvider sınıfı) açıklar. AppWidgetProviderInfo, bu belgede açıklandığı gibi XML olarak tanımlanmıştır.

AppWidgetProvider sınıf

Widget'la programlı bir şekilde 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. Manifestte AppWidgetProvider olduğunu beyan eder ve ardından bu belgede açıklandığı gibi uygularsınız.

Düzeni görüntüle

Widget'ın ilk düzenini tanımlar. Düzen, bu belgede açıklandığı gibi XML'de tanımlanır.

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

Widget'ınız için 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) başlayarak, varsayılan bir yapılandırma sağlayabilir ve kullanıcıların widget'ı daha sonra yeniden yapılandırmasına izin verebilirsiniz. Daha fazla ayrıntı 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 şu iyileştirmeleri de öneririz: esnek widget düzenleri, çeşitli geliştirmeler, gelişmiş widget'lar, koleksiyon widget'ları ve Widget ana makinesi oluşturma.

AppWidgetProviderInfo XML'i bildirme

AppWidgetProviderInfo nesnesi, bir 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 boyutları almasına izin verir. Örneğin, yatay olarak iki hücre ve dikey olarak üç hücre.

Widget boyutlandırma özellikleri, widget'ınız için varsayılan bir boyut belirtmenizi sağlar ve widget'ın boyutunun alt ve üst sınırlarını sağlar. Bu bağlamda, bir widget'ın varsayılan boyutu, widget'ın ana ekrana ilk kez eklendiğinde alacağı boyuttur.

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

Örnek

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

• Bir ızgara 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 veya 4x3'e 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, 2x1 olacak şekilde veya tam ekrana kadar yeniden boyutlandırılabilir.

Ek widget özellikleri

Aşağıdaki tabloda, widget boyutlandırma 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ı işler ve widget yaşam döngüsü etkinliklerine yanıt olarak widget'ı günceller. Aşağıdaki bölümlerde, manifest dosyasında AppWidgetProvider özelliğinin nasıl bildirileceği ve ardından 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 özelliğini belirten android:name özelliğini gerektirir. AppWidgetProvider cihazınıza ayrı bir işlemin yayınlanması gerekmedikçe, genellikle böyle bir durum söz konusu değilse bileşen dışa aktarılmamalıdır.

<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. Bu, açıkça belirtmeniz gereken tek yayındır. 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 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ı (örneğin, widget'ın güncellenmesi, silinmesi, etkinleştirilmesi ve devre dışı bırakılması) alır. Bu yayın etkinlikleri gerçekleştiğinde aşağıdaki AppWidgetProvider yöntemleri çağrılır:

onUpdate()

Bu, widget'ın AppWidgetProviderInfo içindeki updatePeriodMillis özelliği tarafından tanımlanan aralıklarla güncellenmesi için çağrılır. Daha fazla bilgi için bu sayfadaki ek widget özelliklerinin açıklandığı 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österilecek verileri yükleme işlerini başlatma gibi önemli ayarları gerçekleştirir. Bununla birlikte, configuration_optional işareti olmadan bir yapılandırma etkinliği bildirirseniz bu yöntem, kullanıcı widget'ı eklediğinde çağrılmaz, ancak sonraki güncellemeler için çağrılır. Yapılandırma tamamlandığında ilk güncellemeyi gerçekleştirmek 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 izin verme başlıklı makaleye bakın.

En önemli geri arama onUpdate(). Daha fazla bilgi için bu sayfadaki onUpdate() sınıfıyla etkinlik işleme bölümüne göz atı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ğırmayı kullanın. getAppWidgetOptions() çağrısı yaparak boyut aralıklarını ve Android 12'den itibaren bir widget örneğinin alabileceği olası boyutların listesini edinebilirsiniz. Bu çağrı, aşağıdaki bilgileri içeren bir Bundle değeri döndürür:

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

onDeleted(Context, int[])

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

onEnabled(Context)

Bu, 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 yalnızca ilk defa ç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 çağrı, widget'ınızın son örneği widget ana makinesinden silindiğinde çağrılır. Bu işlemle onEnabled(Context) üzerinde yapılan tüm işleri temizleyin (ör. geçici bir veritabanını silmek).

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ı filtreler ve önceki yöntemleri uygun şekilde çağırır. Bu nedenle, 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.

Etkinlikleri onUpdate() sınıfıyla yönetme

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ıldığı için en önemli AppWidgetProvider geri çağırması onUpdate() şeklindedir. Widget'ınız herhangi bir kullanıcı etkileşimi etkinliğini kabul ediyorsa etkinlik işleyicilerini bu geri çağırmaya kaydedin. Widget'ınız geçici dosyalar veya veritabanları oluşturmuyorsa 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üğme içeren bir widget istiyorsanız şu 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 ve bir Activity başlatan ve setOnClickPendingIntent(int, PendingIntent) ile widget'ın düğmesine ekleyen bir PendingIntent oluşturmak için bu yöntemi kullanı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 tümü 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 olacak şekilde tanımlanırsa ve widget'ın ikinci bir örneği ilkinden bir saat sonra eklenirse, her ikisi de ilkinin tanımladığı dönem üzerinde güncellenir, ikinci güncelleme dönemi ise 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ını inceleyin.

Widget yayın amaçları al

AppWidgetProvider, kolaylık sınıfıdır. Widget yayınlarını doğrudan almak isterseniz kendi BroadcastReceiver'inizi uygulayabilir veya onReceive(Context,Intent) geri çağırmasını geçersiz kılabilirsiniz. Dikkat etmeniz gereken amaçlar ş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 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 bilgi sahibiyseniz widget düzenini oluşturmak basittir. Ancak widget düzenlerinin, her düzen veya görünüm widget'ını desteklemeyen RemoteViews temelli olduğunu unutmayın. RemoteViews tarafından desteklenen görünümlerin özel görünümlerini veya 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, sıfır boyutlu bir View olan ViewStub'ı da destekler.

Durum bilgili davranış desteği

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

• CheckBox

• Switch

• RadioButton

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

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 bölgesinde 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 hedefleyen cihazları hedefler.

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

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

• 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'taki herhangi bir görünümün köşe yarıçapı. Bu değer, 8 dp dolgu kullanırken güzel bir şekilde hizalamak için arka plan yarıçapından tam olarak 8 dp daha düşüktür.

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

1 Widget'ın köşesi.

2 Widget'taki görünümün köşesi.

Yuvarlak köşeler ile ilgili ö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, 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 ana hatlara göre kırpan bir arka plan tanımlıyorsa (android:clipToOutline true olarak ayarlanmış şekilde) başlatıcı otomatik olarak arka planı tanımlar ve köşeleri 16 dp'ye kadar yuvarlanmış bir dikdörtgen kullanarak widget'ı kırpar. Widget'ınızın Android 12 ile uyumlu olduğundan emin olma bölümüne bakın.

Android'in önceki sürümleriyle widget uyumluluğu için aşağıdaki örnek XML dosyalarında gösterildiği gibi özel özellikler tanımlamanızı ve Android 12'de bunları geçersiz kılacak ö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" />