Widget ana makinesi oluşturma

Çoğu Android destekli cihazda bulunan Android ana ekranı, kullanıcının içeriklere hızlı erişim için uygulama widget'larını (veya widget'ları) yerleştirmesine olanak tanır. Ana ekranı değiştiren veya benzer bir uygulama geliştiriyorsanız AppWidgetHost uygulayarak kullanıcının widget'ları 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 sözleşmeden doğan yükümlülüklerini anlamanız önemlidir.

Bu sayfada, özel bir AppWidgetHost uygularken üstlenilmesi gereken sorumluluklar ele alınmaktadır. AppWidgetHost öğesini nasıl uygulayacağınıza dair belirli bir örnek görmek için Android ana ekranının kaynak koduna bakın LauncherAppWidgetHost.

Özel AppWidgetHost uygulamayla ilgili temel sınıflara ve kavramlara genel bir bakış:

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

• Uygulama widget'ı ana makine 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, ana makine tarafından her şişirildiğinde bir AppWidgetHostView ile ilişkilendirilir.

  • Sistem varsayılan olarak bir AppWidgetHostView oluşturur ancak ana makine, AppWidgetHostView öğesini genişleterek kendi 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 sunuyor. Bu yöntemlere renkleri sağlamak ana makinenin sorumluluğundadır.

• Seçenek 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ı olduğu hakkında AppWidgetProvider ile bilgi paylaşmak için seçenek paketini kullanır. Bu bilgiler, AppWidgetProvider widget'ın içeriklerini ve görünümünü, nasıl ve nerede görüntülendiğine göre uyarlamasına olanak tanır. Bir widget'ın paketini değiştirmek için updateAppWidgetOptions() ve updateAppWidgetSize() kullanabilirsiniz. Bu yöntemlerin her ikisi de AppWidgetProvider'ye onAppWidgetOptionsChanged() geri çağırmasını 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ğini belirli bir ana makine ve belirli bir AppWidgetProvider ile ilişkilendirme anlamına gelir.

Bağlama API'leri, bir ana makinenin bağlama için özel bir kullanıcı arayüzü sağlamasını da mümkün kılar. Bu süreci 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 ilk adım. Çalışma zamanında, kullanıcının uygulamanıza ana makineye widget eklemesi için açıkça izin vermesi gerekir. Uygulamanızın widget ekleme izni olup olmadığını test etmek için bindAppWidgetIdIfAllowed() yöntemini kullanın. bindAppWidgetIdIfAllowed() false değerini döndürürse uygulamanız, kullanıcıya 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şlemleri için "her zaman izin ver".

Bu snippet, iletişim kutusunun nasıl görüntüleneceğine dair bir örnek verir:

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ılması gerekip gerekmediğini kontrol etmelidir. Daha fazla bilgi için Kullanıcıların uygulama widget'larını yapılandırmasına izin verme başlıklı makaleyi inceleyin.

Düzenleyicinin 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, bir widget sağlayıcıyla ilişkili AppWidgetProviderInfo nesnesinden alabilirsiniz.

Hedeflediğiniz Android sürümünden bağımsız olarak tüm ana makineler aşağıdaki sorumluluklara sahiptir:

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

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

• Widget'lar, AppWidgetProviderInfo meta verilerinde varsayılan genişlik ve yükseklik belirtir. Bu değerler, hücrelerde (Android 12'den itibaren targetCellWidth ve targetCellHeight belirtilmişse) veya yalnızca minWidth ve minHeight belirtilmişse dp'lerde tanımlanır. Widget boyutlandırma özelliklerine bakın.

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

Önceki bölümde listelenen şartlara ek olarak, belirli platform sürümleri, 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 dp cinsinden listesini içeren ek bir List<SizeF> paketiyle birlikte gelir. Sağlanan boyut sayısı, ana makine uygulamasına bağlıdır. Genellikle, ana makineler telefonlar için iki boyut (dikey ve yatay) ve katlanabilir cihazlar için dört boyut sağlar.

Bir AppWidgetProvider, RemoteViews için en fazla MAX_INIT_VIEW_COUNT (16) farklı RemoteViews sağlayabilir. AppWidgetProvider nesneleri, List<SizeF> içindeki her boyuta bir RemoteViews nesnesiyle eşlediğinden MAX_INIT_VIEW_COUNT'ten fazla boyut sağlamayın.

Android 12, dps'de maxResizeWidth ve maxResizeHeight özelliklerini de kullanıma sunar. Bu özelliklerden en az birini kullanan bir widget'ın, özelliklerde belirtilen boyutu aşmaması önerilir.

Ek kaynaklar

• Glance referans belgelerini inceleyin.