Glance ile uygulama widget'ı oluşturma

Aşağıdaki bölümlerde, Glance ile temel bir uygulama widget'ının nasıl oluşturulacağı açıklanmaktadır.

Manifest dosyasında AppWidget öğesini bildirin

Kurulum adımlarını tamamladıktan sonra uygulamanızda AppWidget ve meta verilerini bildirin.

1. AppWidget alıcısını GlanceAppWidgetReceiver cihazından uzatın:

   class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
       override val glanceAppWidget: GlanceAppWidget = TODO("Create GlanceAppWidget")
   }
   GlanceSnippets.kt

2. Uygulama widget'ının sağlayıcısını AndroidManifest.xml dosyanıza ve ilişkili meta veri dosyasına kaydedin:

       <receiver android:name=".glance.MyReceiver"
       android:exported="true">
       <intent-filter>
           <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
       </intent-filter>
       <meta-data
           android:name="android.appwidget.provider"
           android:resource="@xml/my_app_widget_info" />
   </receiver>
   AndroidManifest.xml
   

AppWidgetProviderInfo meta verilerini ekleyin.

Ardından, @xml/my_app_widget_info dosyasında uygulama widget'ı bilgilerini oluşturmak ve tanımlamak için Widget oluşturma kılavuzundaki adımları uygulayın.

Glance'teki tek fark, initialLayout XML olmamasıdır ancak bir tane tanımlamanız gerekir. Kitaplıkta sağlanan önceden tanımlanmış yükleme düzenini kullanabilirsiniz:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:initialLayout="@layout/glance_default_loading_layout">
</appwidget-provider>
my_app_widget_info.xml

AppWidgetProviderInfo XML'ini tanımlama

AppWidgetProviderInfo nesnesi, widget'ınızın temel özelliklerini tanımlar. XML meta veri kaynak dosyanızdaki AppWidgetProviderInfo öğesini <appwidget-provider> öğesi içinde tanımlayın: (res/xml/my_app_widget_info.xml)

<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/glance_default_loading_layout"
    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üksekliğe ve genişliğe sahip hücrelerden oluşan bir ızgaraya göre konumlandırır. Çoğu ana ekranda widget'lar yalnızca ızgara hücrelerinin tam sayı katları olan boyutları alabilir. Örneğin, yatayda iki hücreye, dikeyde üç hücreye denk gelen boyutlar.

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

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

Örnek

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

• Bir ızgara hücresi 30 dp genişliğinde ve 50 dp yüksekliğindedir.
• Aşağıdaki özellik spesifikasyonu sağlanı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:

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

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

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'ın boyutu 2x1'e kadar küçültülebilir veya tam ekrana kadar büyütülebilir.

Ek widget özellikleri

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

GlanceAppWidget sözcüğünü tanımla

1. GlanceAppWidget sınıfından türeyen ve provideGlance yöntemini geçersiz kılan yeni bir sınıf oluşturun. Bu yöntem, widget'ınızı oluşturmak için gereken verileri yükleyebileceğiniz yerdir:

   class MyAppWidget : GlanceAppWidget() {
   
       override suspend fun provideGlance(context: Context, id: GlanceId) {
   
           // In this method, load data needed to render the AppWidget.
           // Use `withContext` to switch to another thread for long running
           // operations.
   
           provideContent {
               // create your AppWidget here
               Text("Hello World")
           }
       }
   }
   GlanceSnippets.kt

2. GlanceAppWidgetReceiver cihazınızdaki glanceAppWidget içinde oluşturun:

   class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
   
       // Let MyAppWidgetReceiver know which GlanceAppWidget to use
       override val glanceAppWidget: GlanceAppWidget = MyAppWidget()
   }
   GlanceSnippets.kt

Glance'i kullanarak AppWidget yapılandırdınız.

Widget yayınlarını işlemek için GlanceAppWidgetReceiver sınıfını kullanın.

GlanceAppWidgetReceiverKoordinatlar widget'ı, temel AppWidgetProvider genişletilerek yayın ve platform durumu güncellemeleri yapar. Widget'ınız güncellendiğinde, silindiğinde, etkinleştirildiğinde veya devre dışı bırakıldığında platform etkinliklerini alır ve bunları Compose yaşam döngüsü isteklerine çevirir.

Manifest dosyasında widget bildirme

GlanceAppWidgetReceiver sınıf alt sınıfınızı AndroidManifest.xml dosyanızda yayın alıcısı olarak bildirin:

<receiver android:name="ExampleAppWidgetReceiver"
          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/my_app_widget_info" />
</receiver>

<receiver> öğesi, alıcı sınıfını belirten android:name özelliğini gerektirir. Alıcının ACTION_APPWIDGET_UPDATE yayın işlemini <intent-filter> içinde kabul etmesi gerekir.

<meta-data> öğesi adını android.appwidget.provider olarak tanımlamalı ve android:resource özelliği, AppWidgetProviderInfo XML meta veri kaynağınıza (@xml/my_app_widget_info) işaret etmelidir.

GlanceAppWidgetReceiver sınıfını uygulama

Glance'te GlanceAppWidgetReceiver yerine doğrudan AppWidgetProvider öğesini genişletirsiniz. Alıcınızı GlanceAppWidget örneğinize bağlayarak bunu uygulayın. GlanceAppWidgetReceiver içinde bulunan birincil geri çağırmalar şu şekilde çalışır:

• onUpdate(): Kompozisyon güncellemelerini yürütmek için Glance tarafından otomatik olarak geçersiz kılınır. onUpdate değerini manuel olarak geçersiz kılarsanız Glance'in kompozisyon iş parçacıklarını başarıyla başlatmasına izin vermek için super.onUpdate işlevini çağırmanız gerekir.
• onAppWidgetOptionsChanged(): Widget ilk yerleştirildiğinde veya yeniden boyutlandırıldığında çağrılır. Glance okuma seçenekleri, öğeleri arka planda paketler. Böylece düzeniniz, çalışma zamanı boyutlarına göre sorunsuz bir şekilde ayarlanır.
• onDeleted(Context, IntArray): Belirli bir widget örneği kullanıcı tarafından her silindiğinde çağrılır.
• onEnabled(Context): Widget'ınızın ilk örneği başarıyla oluşturulduğunda tetiklenir. Küresel taşımaları çalıştırmak için mükemmeldir.
• onDisabled(Context): Sağlayıcının son etkin örneği kaldırıldığında çağrılır.
• onReceive(Context, Intent): Belirli geri çağırma yöntemlerinden önce her platform yayınını yakalar. Yazdığınız özel alıcı mantığının super.onReceive(context, intent) işlevini çağırdığından emin olmanız gerekir ve Glance, işi otomatik olarak eşzamansız yönlendirdiğinden goAsync işlevini asla kendiniz çağırmamalısınız.

Widget yayın amaçlarını alma

GlanceAppWidgetReceiver, temel platform widget'ı yayın amaçlarını filtreler ve aşağıdaki gibi işler:

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

Kullanıcı arayüzü oluşturma

Aşağıdaki snippet'te kullanıcı arayüzünün nasıl oluşturulacağı gösterilmektedir:

/* Import Glance Composables
 In the event there is a name clash with the Compose classes of the same name,
 you may rename the imports per https://kotlinlang.org/docs/packages.html#imports
 using the `as` keyword.

import androidx.glance.Button
import androidx.glance.layout.Column
import androidx.glance.layout.Row
import androidx.glance.text.Text
*/
class MyAppWidget : GlanceAppWidget() {

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        // Load data needed to render the AppWidget.
        // Use `withContext` to switch to another thread for long running
        // operations.

        provideContent {
            // create your AppWidget here
            MyContent()
        }
    }

    @Composable
    private fun MyContent() {
        Column(
            modifier = GlanceModifier.fillMaxSize(),
            verticalAlignment = Alignment.Top,
            horizontalAlignment = Alignment.CenterHorizontally
        ) {
            Text(text = "Where to?", modifier = GlanceModifier.padding(12.dp))
            Row(horizontalAlignment = Alignment.CenterHorizontally) {
                Button(
                    text = "Home",
                    onClick = actionStartActivity<MyActivity>()
                )
                Button(
                    text = "Work",
                    onClick = actionStartActivity<MyActivity>()
                )
            }
        }
    }
}
GlanceSnippets.kt

Yukarıdaki kod örneği şunları yapar:

• En üst düzeyde Column öğeler dikey olarak birbirinin altına yerleştirilir.
• Column, GlanceModifier aracılığıyla kullanılabilir alana uyacak şekilde boyutunu genişletir, içeriğini üste (verticalAlignment) hizalar ve yatay olarak ortalar (horizontalAlignment).
• Column öğesinin içeriği lambda kullanılarak tanımlanır. Sıra önemlidir.
  • Column içindeki ilk öğe, 12.dp dolguya sahip bir Text bileşenidir.
  • İkinci öğe, öğelerin yatay olarak yerleştirildiği bir Row'dir. Yatay olarak ortalanmış iki Buttons (horizontalAlignment) bulunur. Son görüntü, mevcut alana bağlıdır. Aşağıdaki resimde, nasıl görünebileceğine dair bir örnek verilmiştir:

Hizalama değerlerini değiştirebilir veya bileşenlerin yerleşimini ve boyutunu değiştirmek için farklı değiştirici değerler (ör. dolgu) uygulayabilirsiniz. Her sınıf için bileşenlerin, parametrelerin ve kullanılabilir değiştiricilerin tam listesini görmek için referans belgelerine bakın.

Yuvarlak köşeleri uygulama

Android 12, uygulama widget'larınızın köşe yarıçaplarını dinamik olarak özelleştirmek için sistem parametrelerini kullanıma sunar:

• system_app_widget_background_radius: Widget arka plan container'ının köşe yarıçapını belirtir (28 dp'den büyük olamaz).
• İç yarıçap: İçeriğin kırpılmasını önlemek için sistem arka plan ana hattına göre iç içeriğiniz için orantılı bir yarıçap hesaplayın: systemRadiusValue - widgetPadding

Glance'te, GlanceModifier.cornerRadius(android.R.dimen.system_app_widget_background_radius) kullanarak kompozisyonda köşe yarıçapı boyutlandırma özelliklerini dinamik olarak uygulayabilirsiniz.

Android 11 (API düzeyi 30) veya daha eski sürümleri çalıştıran cihazlarda geriye dönük uyumluluk için özel özellikler ve özel tema kaynağı geri dönüşleri uygulayın:

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