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ı (veya widget'lar) yerleştirmesine olanak tanır. Ana ekranın yerini alacak bir uygulama veya benzer bir uygulama geliştiriyorsanız AppWidgetHost sınıfını uygulayarak kullanıcıların widget yerleştirmesine de izin verebilirsiniz. Çoğu uygulamanın bunu yapması gerekmez ancak kendi barındırıcınızı oluşturuyorsanız barındırıcının dolaylı olarak kabul ettiği sözleşme yükümlülüklerini anlamanız önemlidir.

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

Özel bir AppWidgetHost uygulamasında yer alan 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. AppWidgetHost, barındırıcının kendi paketi içinde benzersiz bir kimliğe sahip 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ünü ve daha fazla ayrıntı için aşağıdaki Widget'ları bağlama bölümünü inceleyin. Ana makine, benzersiz kimliği allocateAppWidgetId() kullanarak alır. Bu kimlik, ana makineden silinene kadar widget'ın kullanım ömrü boyunca kalıcı olur. Barındırıcıya özgü tüm durumlar (ör. widget'ın boyutu ve konumu), barındırma paketi tarafından kalıcı hale getirilmeli ve uygulama widget'ı kimliğiyle ilişkilendirilmelidir.

• Uygulama widget'ı barındırıcı görünümü: AppWidgetHostView, widget'ın gösterilmesi gerektiğinde sarmalandığı bir çerçeve olarak düşünülebilir. 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 sınıfını genişleterek kendi alt sınıfını oluşturabilir.
  • Android 12'den (API düzeyi 31) itibaren AppWidgetHostView, dinamik olarak aşırı yüklenen renkleri işlemek için setColorResources() ve resetColorResources() yöntemlerini kullanıma sunar. Bu yöntemlere renkleri sağlamak ana makinenin sorumluluğundadır.

• Seçenekler paketi: AppWidgetHost, widget'ın nasıl görüntülendiği (ör. boyut aralıklarının listesi) ve kilit ekranında mı yoksa ana ekranda mı olduğu hakkında bilgileri AppWidgetProvider ile paylaşmak için seçenekler paketini kullanır. Bu bilgiler, AppWidgetProvider uygulamasının 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() yöntemlerini kullanabilirsiniz. Bu yöntemlerin her ikisi de AppWidgetProvider için onAppWidgetOptionsChanged() geri çağırma işlevini tetikler.

Widget'ları bağlama

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şkilendirmeyi ifade eder.

Bağlama API'leri, barındırıcının bağlama için özel bir kullanıcı arayüzü sunmasını da mümkün kılar. 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 yalnızca 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ıdan izin 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, 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.provider)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)
Host.kt

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üzenleyenin 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 düzenleyicilerin aşağıdaki sorumlulukları vardır:

• Widget eklerken widget kimliğini daha önce açıklandığı şekilde tahsis edin. Bir widget, ana makineden kaldırıldığında widget kimliğinin ayırmasını kaldırmak için deleteAppWidgetId() yöntemini çağırın.

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

  Not: Yapılandırma etkinliğinin döndürülmediği veya hatalarla tamamlandığı düzensiz durumları ele alın.

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

  Widget'ın en az bu kadar dp ile düzenlendiğinden emin olun. Örneğin, birçok barındırıcı simgeleri ve widget'ları bir ızgarada 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.

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

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

Seçenekler paketi, bir widget örneğinin alabileceği olası boyutların dp cinsinden listesini içeren bir List<SizeF> içerebilir. Sağlanan boyut sayısı, ana makine uygulamasına bağlıdır. Barındırıcılar genellikle telefonlar için iki boyut (dikey ve yatay) ve katlanabilir cihazlar için dört boyut sunar.

Bir AppWidgetProvider tarafından RemoteViews'e sağlanabilecek farklı RemoteViews sayısı MAX_INIT_VIEW_COUNT (16) ile sınırlıdır. AppWidgetProvider nesneleri, List<SizeF> içindeki her boyut için bir RemoteViews nesnesi eşlediğinden MAX_INIT_VIEW_COUNT boyuttan fazlasını sağlamayın.

Widget'lar dp cinsinden 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.