Widget ana makinesi oluşturma

Android destekli cihazların çoğunda bulunan Android ana ekranı, kullanıcıların içeriğe hızlı erişim için uygulama widget'larını (veya widget'ları) yerleştirmesine olanak tanır. Ana ekran yerine yeni bir uygulama veya benzer bir uygulama oluşturuyorsanız AppWidgetHost öğesini uygulayarak kullanıcının widget'ları yerleştirmesine de izin verebilirsiniz. Çoğu uygulamanın böyle bir işlem yapması gerekmez ancak kendi ana makinenizi oluşturuyorsanız ana makinenin dolaylı olarak kabul ettiği sözleşme yükümlülüklerini anlamanız önemlidir.

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

Aşağıda, özel bir AppWidgetHost uygulanmasıyla ilgili önemli sınıflar ve kavramlarla ilgili genel bir bakış sunulmaktadır:

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

• Uygulama widget kimliği: Bağlama sırasında her widget örneğine benzersiz bir kimlik atanır. bindAppWidgetIdIfAllowed() ve daha fazla bilgi için aşağıdaki Bağlama widget'ları bölümüne bakın. Ana makine, benzersiz kimliği allocateAppWidgetId() kullanarak elde eder. Bu kimlik ana makineden silinene kadar widget'ın kullanım ömrü boyunca kalır. Widget'ın boyutu ve konumu gibi ana makineye özel tüm durumlar, barındırma paketi tarafından korunmalı ve uygulama widget kimliğiyle ilişkilendirilmelidir.

• Uygulama widget'ı ana makine görünümü: AppWidgetHostView'i, görüntülenmesi gerektiğinde widget'ın içine yerleştirildiği bir çerçeve olarak düşünebilirsiniz. Widget, ana makine tarafından her genişletildiğinde bir AppWidgetHostView ile ilişkilendirilir.

  • Varsayılan olarak, sistem bir AppWidgetHostView oluşturur ancak ana makine bunu genişleterek kendi AppWidgetHostView alt sınıfını oluşturabilir.
  • AppWidgetHostView, Android 12'den (API düzeyi 31) itibaren dinamik olarak aşırı yüklenen renkleri işlemek için setColorResources() ve resetColorResources() yöntemlerini kullanıma sunuyor. Ev sahibi, bu yöntemlere renk eklemekten sorumludur.

• Seçenekler paketi: AppWidgetHost, widget'ın görüntülenme şekli (örneğin, boyut aralıkları listesi) ve widget'ın kilit ekranında mı yoksa ana ekranda mı olduğuyla ilgili bilgileri AppWidgetProvider'e iletmek için seçenek paketini kullanır. Bu bilgiler, AppWidgetProvider tarafından widget'ın nasıl ve nerede görüntülendiğine göre widget'ın içeriğini ve görünümünü özelleştirmesini sağlar. Bir widget'ın paketini değiştirmek için updateAppWidgetOptions() ve updateAppWidgetSize() seçeneklerini kullanabilirsiniz. Bu yöntemlerin her ikisi de AppWidgetProvider öğesine geri çağırmayı (onAppWidgetOptionsChanged()) tetikler.

Widget bağlama

Bir kullanıcı ana makineye bir widget eklediğinde, bağlama adı verilen bir işlem gerçekleşir. Bağlama, belirli bir uygulama widget'ı kimliğinin belirli bir ana makine ve belirli bir AppWidgetProvider ile ilişkilendirilmesi anlamına gelir.

Bağlama API'leri, bir ana makinenin bağlama için özel bir kullanıcı arayüzü sağlamasına da imkan tanır. 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 daha başlangıç. Çalışma zamanında kullanıcı, uygulamanıza ana makineye widget eklemesine izin vermek için 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: geçerli widget ekleme için "izin ver" veya gelecekteki tüm widget eklemelerini kapsamak için "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);

Düzenleyen, kullanıcının eklediği widget'ın yapılandırılmasına gerek olup olmadığını kontrol etmelidir. Daha fazla bilgi için Kullanıcıların uygulama widget'larını yapılandırmasına izin verme bölümüne bakın.

Toplantı sahibinin 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şkilendirilmiş 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ığı gibi ayırın. Bir widget ana makineden kaldırıldığında, widget kimliğinin yerini belirlemek 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 varsa ve isteğe bağlı olarak işaretlenmemişse hem configuration_optional hem de reconfigurable işaretlerini belirterek ana makinenin, yapılandırma etkinliğini 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örüntülenebilmesi için gerekli bir adımdır.

• Widget'lar, AppWidgetProviderInfo meta verilerinde varsayılan bir genişlik ve yükseklik belirtir. Bu değerler hücrelerde tanımlanır (targetCellWidth ve targetCellHeight belirtilmişse Android 12'den başlayarak) veya yalnızca minWidth ve minHeight belirtilmişse dps. 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 ızgara üzerinde 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 belirtilen gereksinimlere ek olarak, belirli platform sürümleri ana makineye yeni sorumluluklar atayan ö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 ek bir List<SizeF> içerir. Sağlanan boyutların sayısı ana makine uygulamasına bağlıdır. Ana makineler telefonlar için genellikle iki boyut (dikey ve yatay) ve katlanabilir cihazlar için dört boyut sunar.

AppWidgetProvider öğesinin RemoteViews'e sağlayabileceği farklı RemoteViews sayısı için MAX_INIT_VIEW_COUNT (16) sınırı vardı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, dps biçiminde maxResizeWidth ve maxResizeHeight özelliklerini de kullanıma sunuyor. Bu özelliklerden en az birini kullanan bir widget'ın, özellikler tarafından belirtilen boyutu aşmamasını öneririz.

Ek kaynaklar

• Glance referans belgelerini inceleyin.