Widget ana makinesi oluşturma

Android ana ekranı, Android destekli çoğu cihazda bulunur ve kullanıcıların içeriğe hızlıca erişmek için uygulama widget'ları (veya widget'lar) yerleştirmesine olanak tanır. Ana ekranın yerini alacak veya benzer bir uygulama geliştiriyorsanız AppWidgetHost'i uygulayarak kullanıcının widget yerleştirmesine de izin verebilirsiniz. Bu, çoğu uygulamanın yapması gereken bir işlem değildir ancak kendi barındırıcınızı oluşturuyorsanız barındırıcının zımnen kabul ettiği sözleşmeden doğan yükümlülükleri anlamanız önemlidir.

Bu sayfada, özel AppWidgetHost uygulamayla ilgili sorumluluklar ele alınmaktadır. AppWidgetHost öğesinin nasıl uygulanacağına dair belirli bir örnek için Android ana ekranının LauncherAppWidgetHost kaynak koduna bakın.

Özel AppWidgetHost uygulamayla ilgili temel sınıflara ve kavramlara genel bir bakış aşağıda verilmiştir:

• Uygulama widget'ı ana makinesi: AppWidgetHost, kullanıcı arayüzüne widget yerleştiren uygulamalar için AppWidget hizmetiyle etkileşim sağlar. AppWidgetHost , barındırıcının kendi paketinde benzersiz bir kimliğe sahip olmalıdır. Bu kimlik, ana makinenin tüm kullanımlarında devam eder. Kimlik genellikle uygulamanızda atadığınız sabit kodlu bir değerdir.

• Uygulama widget'ı kimliği: Her widget örneğine, bağlama sırasında benzersiz bir kimlik atanır. Daha fazla bilgi için bindAppWidgetIdIfAllowed() bölümüne ve aşağıdaki Widget'ları bağlama bölümüne bakın. Barındırıcı, allocateAppWidgetId() kullanarak benzersiz kimliği alır. Bu kimlik, barındırıcıdan silinene kadar widget'ın kullanım süresi boyunca varlığını korur. Barındırıcıya özgü tüm durumlar (ör. widget'ın boyutu ve konumu) barındırma paketi tarafından devam ettirilmeli ve uygulama widget'ı kimliğiyle ilişkilendirilmelidir.

• Uygulama widget'ı ana makinesi görünümü: AppWidgetHostView, widget'ın gösterilmesi gerektiğinde içine yerleştirildiği bir çerçeve olarak düşünülebilir. Bir widget, barındırıcı tarafından her şişirildiğinde bir AppWidgetHostView ile ilişkilendirilir.

  • Sistem varsayılan olarak bir AppWidgetHostView oluşturur ancak ana makine, AppWidgetHostView'yi genişleterek kendi AppWidgetHostView alt sınıfını oluşturabilir.
  • Android 12 (API düzeyi 31) sürümünden itibaren AppWidgetHostView, dinamik olarak aşırı yüklenmiş renkleri işlemek için setColorResources() ve resetColorResources() yöntemlerini kullanıma sunar. Bu yöntemlere renkleri eklemek yayın sahibinin sorumluluğundadır.

• Seçenekler paketi: AppWidgetHost, widget'ın nasıl görüntülendiği (ör. boyut aralıkları listesi) ve widget'ın kilit ekranında mı yoksa ana ekranda mı bulunduğuyla ilgili bilgileri AppWidgetProvider'e iletmek için seçenekler paketini kullanır. Bu bilgiler, AppWidgetProvider'nin widget'ın içeriğini ve görünümünü nasıl ve nerede gösterildiğine göre özelleştirmesine olanak tanır. Bir widget'ın paketini değiştirmek için updateAppWidgetOptions() ve updateAppWidgetSize() öğelerini kullanabilirsiniz. Bu yöntemlerin her ikisi de AppWidgetProvider için onAppWidgetOptionsChanged() geri çağırma işlevini tetikler.

Bağlama widget'ları

Kullanıcı bir ana makineye widget eklediğinde bağlama adı verilen bir işlem gerçekleşir. Bağlama, belirli bir uygulama widget'ı kimliğinin belirli bir ana makineyle ve belirli bir AppWidgetProvider ile ilişkilendirilmesini ifade eder.

Bağlama API'leri, ana makinenin bağlama için özel bir kullanıcı arayüzü sağlamasına da olanak tanır. Bu süreci kullanmak için uygulamanızın, BIND_APPWIDGET iznini barındırıcının manifest dosyasında beyan etmesi gerekir:

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

Ancak bu sadece ilk adım. Çalışma zamanında, kullanıcının barındırıcıya widget eklemesine izin vermek için uygulamanıza açıkça izin vermesi gerekir. Uygulamanızın widget ekleme iznine sahip olup olmadığını test etmek için bindAppWidgetIdIfAllowed() yöntemini kullanın. bindAppWidgetIdIfAllowed() false döndürürse uygulamanız, kullanıcıdan izin vermesini isteyen bir iletişim kutusu göstermelidir: Mevcut widget ekleme işlemi için "izin ver" veya gelecekteki tüm widget ekleme işlemlerini kapsayacak şekilde "her zaman izin ver".

Bu snippet'te iletişim kutusunun nasıl gösterileceğine dair bir örnek verilmiştir:

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);
// This is the options bundle described in the preceding section.
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

Ana makine, kullanıcının eklediği widget'ın yapılandırılmaya ihtiyacı olup olmadığını kontrol etmelidir. Daha fazla bilgi için Kullanıcıların uygulama widget'larını yapılandırmasını etkinleştirme başlıklı makaleyi inceleyin.

Barındırıcının sorumlulukları

AppWidgetProviderInfo meta verilerini kullanarak widget'lar için çeşitli yapılandırma ayarları belirtebilirsiniz. Aşağıdaki bölümlerde daha ayrıntılı olarak ele alınan bu yapılandırma seçeneklerini, widget sağlayıcıyla ilişkili AppWidgetProviderInfo nesnesinden alabilirsiniz.

Hedeflediğiniz Android sürümünden bağımsız olarak tüm ana makinelerin aşağıdaki sorumlulukları vardır:

• Widget eklerken widget kimliğini daha önce açıklandığı şekilde ayırın. Bir widget ana makineden kaldırıldığında, widget kimliğinin ayrılmasını sağlamak için deleteAppWidgetId() işlevini çağırın.

• Widget eklerken yapılandırma etkinliğinin başlatılması gerekip gerekmediğini kontrol edin. Genellikle, ana makinenin, widget'ın yapılandırma etkinliğini (varsa ve isteğe bağlı olarak işaretlenmediyse) hem configuration_optional hem de reconfigurable işaretlerini belirterek başlatması gerekir. Ayrıntılar için Widget'ı yapılandırma etkinliğinden güncelleme başlıklı makaleyi inceleyin. Bu, birçok widget'ın görüntülenebilmesi için gerekli bir adımdır.

• Widget'lar, AppWidgetProviderInfometa verilerinde varsayılan bir genişlik ve yükseklik belirtir. Bu değerler, targetCellWidth ve targetCellHeight belirtilmişse Android 12'den itibaren hücrelerde veya yalnızca minWidth ve minHeight belirtilmişse dp olarak tanımlanır. Widget boyutlandırma özellikleri bölümüne bakın.

  Widget'ın en az bu sayıda dp ile düzenlendiğinden emin olun. Örneğin, birçok ana makine simgeleri ve widget'ları bir ızgara şeklinde düzenler. Bu senaryoda, ana makine varsayılan olarak minWidth ve minHeight kısıtlamalarını karşılayan minimum sayıda hücre kullanarak bir widget ekler.

Belirli platform sürümleri, önceki bölümde listelenen şartlara ek olarak barındırıcıya yeni sorumluluklar yükleyen özellikler sunar.

Hedeflenen Android sürümüne göre yaklaşımınızı belirleme

Android 12

Android 12 (API seviyesi 31), seçenekler paketinde bir widget örneğinin alabileceği olası boyutların listesini dpi cinsinden içeren ek bir List<SizeF> paketler. Sağlanan boyut sayısı, ana makine uygulamasına bağlıdır. Barındıranlar genellikle telefonlar için dikey ve yatay olmak üzere iki boyut, katlanabilir cihazlar için ise dört boyut sağlar.

Bir AppWidgetProvider'nin RemoteViews'a sağlayabileceği farklı RemoteViews sayısı MAX_INIT_VIEW_COUNT (16) ile sınırlıdır. AppWidgetProvider nesneleri, RemoteViews nesnesini List<SizeF> içindeki her boyutla eşleştirdiğinden MAX_INIT_VIEW_COUNT boyuttan fazla sağlamaz.

Android 12, dps cinsinden maxResizeWidth ve maxResizeHeight özelliklerini de kullanıma sunar. Bu özelliklerden en az birini kullanan widget'ların, özellikler tarafından belirtilen boyutu aşmamasını öneririz.

Ek kaynaklar

• Glance referans dokümanlarına bakın.