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ı (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şmeyle ilgili yükümlülüklerini anlamanız önemlidir.

Bu sayfada, özel AppWidgetHost uygulamayla ilgili 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 paketi içinde 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 getirilmeli 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, öğesini genişleterek kendi AppWidgetHostView alt sınıfını oluşturabilir.
  • Android 12'den (API düzeyi 31) 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 sağlamakla ana makine sorumludur.

• 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 bilgisayara 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.provider)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)
Host.kt

Düzenleyen, 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.

Tüm ev sahipleri 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() çağrısı yapılır.

• Widget eklerken yapılandırma etkinliğinin başlatılması gerekip gerekmediğini kontrol edin. Genellikle, varsa ve hem configuration_optional hem de reconfigurable işaretleri belirtilerek isteğe bağlı olarak işaretlenmemişse 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 dps'de 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ı bir ızgara şeklinde düzenler. Bu senaryoda, düzenleyen kişi varsayılan olarak minWidth ve minHeight kısıtlamalarını karşılayan minimum hücre sayısını kullanarak bir widget ekler.

Yaklaşımınızla ilgili ipuçları

Önceki bölümde listelenen koşullara ek olarak aşağıdaki ipuçlarını da göz önünde bulundurun:

Seçenek paketi, bir widget örneğinin alabileceği olası boyutların listesini içeren bir List<SizeF> içerebilir. Sağlanan boyut sayısı, ana makine uygulamasına bağlıdır. Genellikle, telefonlar için iki boyut (dikey ve yatay), katlanabilir cihazlar için ise dört boyut sağlanır.

AppWidgetProvider'ın RemoteViews için sağlayabileceği farklı RemoteViews sayısı MAX_INIT_VIEW_COUNT (16) ile sınırlıdır. AppWidgetProvider nesneleri, List<SizeF> içindeki her boyuta bir RemoteViews nesnesiyle eşlediğinden MAX_INIT_VIEW_COUNT'ten fazla boyut sağlamayın.

Widget'lar, dps'de maxResizeWidth ve maxResizeHeight özelliklerini belirttiğinde, bu özelliklerden en az birini kullanan bir widget'ın, özellikler tarafından belirtilen boyutu aşmamasını öneririz.

Ek kaynaklar

• Glance referans belgelerini inceleyin.