Widget ana makinesi oluşturma

Android destekli çoğu cihazda bulunan Android ana ekranı, kullanıcının içeriğe hızlı erişim için uygulama widget'larını (veya widget'ları) yerleştirmesine olanak tanır. Ana ekran değişimi veya benzer bir uygulama oluşturuyorsanız AppWidgetHost uygulayarak kullanıcının widget'ları yerleştirmesine de izin verebilirsiniz. Bu, çoğu uygulamanın yapması gereken bir şey değildir. Ancak kendi ana makinenizi oluşturuyorsanız barındırıcının sözleşmeden doğan yükümlülüklerini doğrudan kabul etmesi önemlidir.

Bu sayfada, özel AppWidgetHost uygulamasının uygulanmasıyla ilgili sorumluluklara odaklanılmaktadır. AppWidgetHost öğesinin nasıl uygulanacağına dair belirli bir örnek için Android ana ekranının LauncherAppWidgetHost kaynak koduna bakın.

Aşağıda, özel bir AppWidgetHost kullanımıyla ilgili temel sınıflar ve kavramlara genel bir bakış verilmiştir:

• Uygulama widget'ı ana makinesi: AppWidgetHost, kullanıcı arayüzüne widget yerleştiren uygulamalar için AppWidget hizmetiyle etkileşimi sağlar. AppWidgetHost, ana makinenin kendi paketinde benzersiz bir kimliğe sahip olmalıdır. Bu kimlik, ana makinenin tüm kullanımlarında kalıcı olur. 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. bindAppWidgetIdIfAllowed() konusuna ve daha ayrıntılı bilgi için aşağıdaki Widget'ları bağlama bölümüne bakın. Ana makine, benzersiz kimliği allocateAppWidgetId() kullanarak alır. Bu kimlik, ana makineden silinene kadar widget'ın ömrü boyunca kalır. Widget'ın boyutu ve konumu gibi ana makineye özgü durumlar, barındırma paketi tarafından korunmalı ve uygulama widget'ı kimliğiyle ilişkilendirilmelidir.

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

  • Varsayılan olarak, sistem bir AppWidgetHostView oluşturur ancak ana makine bu özelliği genişleterek kendi AppWidgetHostView alt sınıfını oluşturabilir.
  • AppWidgetHostView, Android 12'den (API düzeyi 31) başlayarak dinamik olarak aşırı yüklenen renklerin işlenmesi için setColorResources() ve resetColorResources() yöntemlerini kullanıma sundu. Bu yöntemlere renklerin sağlanmasından sunucu sorumludur.

• Seçenekler paketi: AppWidgetHost, AppWidgetProvider'e widget'ın nasıl gösterileceği (ör. boyut aralıkları listesi) ve widget'ın kilit ekranında mı yoksa ana ekranda mı bulunduğuyla ilgili bilgileri iletmek için seçenekler paketini kullanır. Bu bilgiler sayesinde AppWidgetProvider, widget'ın içeriğini ve görünümünü nasıl ve nerede görüntülendiğine bağlı olarak uyarlayabilir. Widget paketini değiştirmek için updateAppWidgetOptions() ve updateAppWidgetSize() tuşlarını kullanabilirsiniz. Bu yöntemlerin her ikisi de AppWidgetProvider için onAppWidgetOptionsChanged() geri çağırmasını tetikler.

Widget'ları bağlama

Kullanıcı, ana makineye bir widget eklediğinde bağlama adı verilen bir işlem gerçekleşir. Bağlama, belirli bir uygulamanın widget kimliğini belirli bir ana makine ve belirli bir AppWidgetProvider ile ilişkilendirmeyi 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 işlemi kullanmak için uygulamanızın ana makinenin manifest dosyasında BIND_APPWIDGET iznini beyan etmesi gerekir:

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

Ancak bu sadece başlangıç. Çalışma zamanında, kullanıcı uygulamanızın ana makineye bir widget eklemesine izin vermek için uygulamanıza açıkça izin vermelidir. Uygulamanızın widget'ı ekleme izni olup olmadığını test etmek için bindAppWidgetIdIfAllowed() yöntemini kullanın. bindAppWidgetIdIfAllowed() işlevi false değerini döndürürse uygulamanız, kullanıcıdan izin vermesini isteyen bir iletişim kutusu görüntülemelidir: mevcut widget eklemesi için "izin ver" veya gelecekteki tüm widget eklemelerini kapsaması için "her zaman izin ver".

Bu snippet, iletişim kutusunun nasıl gösterileceğine dair bir örnek sunar:

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

Barındırıcı, bir kullanıcının eklediği widget'ın yapılandırılmasına ihtiyaç olup olmadığını kontrol etmelidir. Daha fazla bilgi için Kullanıcıların uygulama widget'larını yapılandırmasına izin verme konusuna bakın.

Ev sahibi olma 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 açıklanan bu yapılandırma seçeneklerini, bir widget sağlayıcıyla ilişkilendirilmiş AppWidgetProviderInfo nesnesinden alabilirsiniz.

Hedeflediğiniz Android sürümüne bakılmaksızın, tüm ana makineler aşağıdaki sorumluluklara sahiptir:

• Widget eklerken, widget kimliğini daha önce açıklandığı şekilde atayın. Bir widget ana makineden kaldırıldığında widget kimliğini ayırmak için deleteAppWidgetId() çağrısı yapın.

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

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

  Widget'ın en az bu kadar dps ile yerleştirildiğinden emin olun. Örneğin, birçok ana makine, simgeleri ve widget'ları bir ızgarada hizalar. Bu senaryoda ana makine, varsayılan olarak minWidth ve minHeight kısıtlamalarına uyan minimum hücre sayısını kullanarak bir widget ekler.

Önceki bölümde listelenen gereksinimlere ek olarak, belirli platform sürümleri, ana makineye yeni sorumluluklar veren özellikler sunar.

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

Android 12

Android 12 (API düzeyi 31), bir widget örneğinin seçenekler paketinde alabileceği olası boyutların listesini dps cinsinden içeren ekstra bir List<SizeF> içerir. Sağlanan boyutların sayısı, ana makine uygulamasına bağlıdır. Ana makineler genellikle telefonlar için iki boyut (dikey ve yatay) ve katlanabilir cihazlar için dört boyut sağlar.

AppWidgetProvider öğesinin RemoteViews ile sağlayabileceği farklı RemoteViews sayısı MAX_INIT_VIEW_COUNT (16) ile sınırlıdır. AppWidgetProvider nesneleri, bir RemoteViews nesnesini List<SizeF> içindeki her boyutla eşlediğinden en fazla MAX_INIT_VIEW_COUNT boyut sağlayın.

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

Ek kaynaklar

• Glance referans belgelerini inceleyin.