WindowManager Uzantıları

Jetpack WindowManager kitaplığı, uygulama geliştiricilerin yeni cihaz form faktörlerini ve çok pencereli ortamları desteklemesini sağlar.

WindowManager Extensions (Uzantılar), çeşitli Jetpack WindowManager özelliklerini etkinleştiren, etkinleştirilmesi gereken bir Android platform modülüdür. Modül, frameworks/base/libs/WindowManager/Jetpack bölgesindeki AOSP'de uygulanır ve WindowManager özelliklerini destekleyen cihazlarda gönderilir.

Uzantı modülü dağıtımı

Uzantılar bir .jar kitaplığında derlenir ve cihaz oluşturma dosyasında uzantılar etkinleştirilmişse cihazdaki system_ext bölümüne yerleştirilir.

Bir cihazda uzantıları etkinleştirmek için ürün cihaz makefile'ine aşağıdakileri ekleyin:

$(call inherit-product, $(SRC_TARGET_DIR)/product/window_extensions.mk)

Bu işlem, cihazda androidx.window.extensions ve androidx.window.sidecar paketlerini etkinleştirir ve persist.wm.extensions.enabled mülkünü ayarlar. Bu paketler makefile'e dahil edildiğinde, beyanlar etc/permissions/ içine yerleştirilir ve uygulama süreçlerine sunulur. Normalde modüller, Jetpack WindowManager kitaplığı tarafından kullanıldığında çalışma zamanında uygulama sürecinin bir parçası olarak yüklenir ve yürütülür. Bu da işleyişini aşağıdaki şekilde gösterildiği gibi istemci tarafı çerçeve koduna benzer hale getirir:

androidx.window.extensions modülü, aktif olarak geliştirilmekte olan mevcut Uzantılar modülüdür. androidx.window.sidecar modülü, Jetpack WindowManager'ın en eski sürümleriyle uyumluluk için dahil edilen eski bir modüldür, ancak yardımcı dosya artık aktif olarak korunmamaktadır.

Aşağıdaki şekilde, androidx.window.extensions veya androidx.window.sidecar kullanımının belirlenmesiyle ilgili mantık gösterilmektedir.

Uzantı modülleri

Uzantılar, katlanabilir geniş ekranlı cihazlar ve harici ekranlarda pencereleme özelliğini destekleyen cihazlar için pencereleme özellikleri sağlar. Özellik alanları şunlardır:

• Etkinlik yerleştirme
• Pencere düzeni bilgileri
• Pencere alanı

Cihaz donanımı ilgili özellikleri desteklemiyorsa uzantıların OEM uygulamaları, WindowExtensions arayüzündeki yöntemlerin varsayılan veya saplama uygulamalarıyla boş bileşen ya da bileşenler sağlayabilir (özellik, Uyumluluk Tanımlama Belgesi (CDD) 7.1.1.1'de özel olarak istenmediği sürece.

Uzantılar ve Jetpack API'leri

WindowManager Uzantıları modülü, herkese açık platform API'lerine ek olarak kendi API yüzeyini sağlar. Uzantılar modülü, geliştirici olmayan bir androidx.window.extensions Jetpack kitaplığında herkese açık olarak geliştirilir. Böylece Jetpack WindowManager (androidx.window) derleme sırasında buna bağlantı verebilir. Uzantılar API yüzeyi genellikle daha düşük düzeyli API'ler sağlar.

Uzantıların sağladığı API'ler yalnızca Jetpack WindowManager kitaplığı tarafından kullanılmalıdır. Extensions API'leri doğrudan uygulama geliştiriciler tarafından çağrılmaz. Uzantı kitaplığı, doğru işlevin sağlanması için Gradle derleme dosyasına bir bağımlılık olarak eklenmemelidir. Uzantı kitaplığını doğrudan bir uygulamada önceden derlemekten kaçının. Bunun yerine, önceden derlenmiş ve çalışma zamanında sağlanan Uzantı sınıflarının bir karışımının yüklenmesini önlemek için çalışma zamanı yüklemesini kullanın.

Jetpack WindowManager (androidx.window), uygulama bağımlılığı olarak eklenmelidir ve WindowManager Uzantıları özellikleri de dahil olmak üzere herkese açık, geliştiricilere yönelik API'ler sağlar. WindowManager kitaplığı, Uzantıları uygulama işlemine otomatik olarak yükler ve alt düzey Extensions API'lerini daha üst düzey soyutlamalar ve daha odaklanmış arayüzler halinde sarmalar. WindowManager Jetpack API'leri, modern Android uygulaması geliştirme standartlarını uygular ve diğer AndroidX kitaplıklarını kullanan kod tabanlarıyla iyi bir şekilde entegre olarak kullanışlı bir birlikte çalışabilirlik sağlar.

Uzantı sürümleri ve güncellemeleri

Uzantılar modülü, Android platformunun yıllık veya üç aylık güncellemeleriyle birlikte güncellenebilir. Üç aylık güncellemeler, Android platform API güncellemeleri arasında Uzantıları API düzeyinin yükseltilmesini sağlar. Bu sayede daha hızlı iterasyonlar yapılabilir ve OEM'ler, donanım lansmanlarına yakın bir zamanda yeni özelliklere resmi API erişimi ekleme fırsatı elde eder.

Aşağıdaki tabloda çeşitli Android sürümleri için androidx.window.extensions API sürümleri listelenmiştir.

Mevcut kararlı API yüzeyine (sağ sütun) her ekleme yapıldığında Extensions API düzeyi (orta sütun) artar.

Geri ve ileri uyumluluk

Jetpack WindowManager; sık sık API düzeyi güncellemeleri, hızlı API gelişimi ve geriye dönük uyumlulukla başa çıkmanın karmaşıklığını halleder. Kitaplık kodu, uygulama sürecinde yürütüldüğünde kitaplık, beyan edilen Extensions API düzeyini kontrol eder ve beyan edilen düzeye göre özelliklere erişim sağlar.

WindowManager, bir uygulamanın çalışma zamanında kilitlenmesini önlemek için, beyan edilen Extensions API düzeyine göre mevcut Extensions API'leri için çalışma zamanında Java yansıma kontrolü de gerçekleştirir. Uyuşmazlık varsa WindowManager Uzantıların kullanımını (kısmen veya tamamen) devre dışı bırakabilir ve ilgili özellikleri uygulamada kullanılamıyor olarak bildirebilir.

WindowManager Uzantıları, Extensions özelliklerinin uygulanmasında WindowManager Core'a (DeviceStateManager) ve diğer sistem hizmetlerine çağrı yapmak için özel platform API'lerini kullanan bir system_ext modülü olarak uygulanır.

Uzantıların yayın öncesi sürümleriyle uyumluluk, ilgili sürümlerin son halini veren ilgili üç aylık veya yıllık Android platformu sürümünden önce sağlanamayabilir. Extensions API'lerin tam geçmişini window:extensions:extensions API metin dosyaları sürüm dalında bulabilirsiniz.

Uzantıların yeni sürümleri, ileriye dönük uyumluluğu korumak için uygulamalara derlenmiş WindowManager'ın eski sürümleriyle çalışmaya devam etmelidir. Bu nedenle, Uzantılar API'sinin yeni sürümleri yalnızca yeni API'ler ekler ve eski API'leri kaldırmaz. Sonuç olarak, eski WindowManager sürümlerine sahip uygulamalar, uygulamaların derlendiği eski Uzantı API'lerini kullanmaya devam edebilir.

CTS doğrulaması, cihazda beyan edilen Uzantıları API'lerinin herhangi bir sürümünde, bu sürüm ve önceki sürümlere ait tüm API'lerin mevcut ve çalışır durumda olmasını sağlar.

Performans

Uzantılar modülü, Android 14'ten (API düzeyi 34) itibaren varsayılan olarak önyükleme sınıf yolu olmayan sistem sınıf yükleyicilerinde önbelleğe alınır. Bu nedenle, uygulama başlatılırken modülün belleğe yüklenmesi nedeniyle performans üzerinde herhangi bir etki olmaz. İstemci ile sunucu arasında ek IPC çağrıları yapıldığında, bağımsız modül özelliklerinin kullanılması uygulamaların performans özelliklerini biraz etkileyebilir.

Modüller

Etkinlik yerleştirme

Etkinlik yerleştirme bileşeni, uygulamaların etkinlik penceresi sunumunu üst uygulamanın sınırları içinde düzenleyebilmesini sağlayan bir dizi özellik sunar. Buna, iki etkinliğin çok bölmeli bir düzende aynı anda yan yana gösterilmesi ve eski uygulamalar için büyük ekran optimizasyonunun sağlanması dahildir.

Etkinlik yerleştirme bileşeni, sw600 dp veya daha büyük boyutta yerleşik ekrana sahip tüm cihazlarda kullanılabilir olmalıdır. Çalışma zamanında harici ekranlar bağlandığında uygulama daha büyük bir boyutta gösterilebileceği için, etkinlik yerleştirme harici ekran bağlantılarını destekleyen cihazlarda da etkinleştirilmelidir.

Cihaz yapılandırması

Uzantı modülü dağıtımı bölümünde açıklandığı gibi Uzantılar modülünü etkinleştirmek dışında özel bir cihaz yapılandırması gerekmez. Çoklu pencere modunu destekleyen tüm cihazlarda uzantıları etkinleştirmek mantıklı bir seçimdir. Gelecekteki Android sürümlerinde, yaygın el tipi ve büyük ekranlı cihaz yapılandırmalarında uzantıların kullanılması zorunlu kılınabilir.

Pencere düzeni bilgileri

Pencere düzeni bilgi bileşeni, menteşe bir uygulama penceresini geçtiğinde katlanabilir cihazdaki menteşenin konumunu ve durumunu tanımlar. Pencere düzeni bilgileri, uygulamaların katlanabilir cihazlarda masaüstü modunda optimize edilmiş düzenlere yanıt vermesini ve bu düzenleri göstermesini sağlar. Kullanım ayrıntıları için Uygulamanızı ekran farkına varma bölümüne bakın.

Ayrı veya kesintisiz ekran paneli alanlarını bağlayan bir menteşesi olan katlanabilir Android cihazlarda menteşeyle ilgili bilgiler, WindowLayoutComponent üzerinden uygulamalara menteşeyle ilgili bilgi vermelidir.

Menteşe konumu ve sınırları, API'ye iletilen bir Context ile tanımlanan uygulama penceresine göre bildirilmelidir. Uygulama penceresi sınırları, menteşe sınırlarıyla kesişmiyorsa menteşe DisplayFeature bildirilmemelidir. Ayrıca, konumları güvenilir bir şekilde raporlanamayan ekran özelliklerinin (ör. çoklu pencere modunda veya uyumluluk sinemaskop modunda bir uygulama penceresi kullanıcı tarafından serbestçe taşınabilirken) raporlanmaması da kabul edilir.

Katlama özellikleri için menteşe konumu kararlı durumlar arasında değiştiğinde durum güncellemeleri bildirilmelidir. Varsayılan olarak düz görüntüleme durumunda API'nin FoldingFeature.State.FLAT değerini bildirmesi gerekir. Cihaz donanımı yarı katlanmış modda, sabit bir durumda bırakılabiliyorsa API, FoldingFeature.State.HALF_OPENED değerini bildirmelidir. Bu durumda uygulama penceresi görünmeyeceği veya menteşe sınırlarını aşmayacağı için API'de kapalı durum yoktur.

Cihaz yapılandırması

OEM'lerin katlama özelliğinin uygulanmasını desteklemek için şunları yapması gerekir:

• device_state_configuration.xml'teki cihaz durumlarını DeviceStateManagerService tarafından kullanılacak şekilde yapılandırın. Referans için DeviceStateProviderImpl.java sayfasını inceleyin.

  DeviceStateProvider veya DeviceStatePolicy varsayılan uygulamaları cihaz için uygun değilse özel bir uygulama kullanılabilir.

• Uzantılar modülünü Uzantılar modülü dağıtımı bölümünde açıklandığı şekilde etkinleştirin.

• com.android.internal.R.string.config_display_features dizesinde görüntüleme özelliklerinin konumunu belirtin (genellikle cihaz yer paylaşımındaki frameworks/base/core/res/res/values/config.xml içinde).

  Dizinin beklenen biçimi şudur:

  <type>-[<left>,<top>,<right>,<bottom>]

  type, fold veya hinge olabilir. left, top, right ve bottom değerleri, doğal ekran yönelimindeki ekran koordinat alanındaki tam sayı piksel koordinatlarıdır. Yapılandırma dizesi, noktalı virgülle ayrılmış birden çok görüntüleme özelliği içerebilir.

  Örnek:

  <!-- Jetpack WindowManager display features -->
  <string name="config_display_features" translatable="false">fold-[1000,0,1000,2000]</string>
  

• DeviceStateManager'te kullanılan dahili cihaz durumu tanımlayıcıları ile com.android.internal.R.array.config_device_state_postures'te geliştiricilere gönderilen herkese açık durum sabitleri arasındaki eşlemeyi tanımlayın.

  Her giriş için beklenen biçim şu şekildedir:

  <device_specific_state_identifier>:<Jetpack WindowManager state identifier>

  Desteklenen durum tanımlayıcıları şunlardır:

  • COMMON_STATE_NO_FOLDING_FEATURES = 1: Eyalette bildirilecek katlama özelliği yok. Örneğin, ana ekran iç tarafta olan tipik katlanabilir cihazın kapalı durumu olabilir.
  • COMMON_STATE_HALF_OPENED = 2: Katlama özelliği yarım açık.
  • COMMON_STATE_FLAT = 3: Katlama özelliği düz. Örneğin, ana ekran iç tarafta olan, katlanabilir cihazların açık durumu olabilir.
  • COMMON_STATE_USE_BASE_STATE = 1000: Android 14'te, CommonFoldingFeature.java bölümünde tanımlandığı gibi, menteşe durumunun temel durum kullanılarak türetildiği taklit edilen durumlar için kullanılabilecek bir değer

  Daha fazla bilgi için bkz. DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int).

  Örnek:

  <!-- Map of System DeviceState supplied by DeviceStateManager to WindowManager posture.-->
  <string-array name="config_device_state_postures" translatable="false">
      <item>0:1</item>    <!-- CLOSED       : COMMON_STATE_NO_FOLDING_FEATURES -->
      <item>1:2</item>    <!-- HALF_OPENED  : COMMON_STATE_HALF_OPENED -->
      <item>2:3</item>    <!-- OPENED       : COMMON_STATE_FLAT -->
      <item>3:1</item>    <!-- REAR_DISPLAY : COMMON_STATE_NO_FOLDING_FEATURES -->
      <item>4:1000</item> <!-- CONCURRENT   : COMMON_STATE_USE_BASE_STATE -->
  </string-array>
  

Pencere alanı

Pencere alanı bileşeni, uygulamaların bazı katlanabilir ve çoklu ekranlı cihazlardaki ek ekranlara ve görüntü alanlarına erişmesini sağlayan bir dizi özellik sunar.

Arka ekran modu, uygulamaların katlanabilir cihazların kapak ekranında kamera önizleme kullanıcı arayüzünü göstererek selfie'ler ve videolar için ana cihaz kamerasının kullanılmasına olanak tanır. Arka cihaz kameralarıyla uyumlu Android uyumlu (Android CDD tarafından boyut, yoğunluk ve mevcut gezinme özellikleri gibi özellikler açısından tanımlanan) bir kapak ekranına sahip cihazlar, arka ekran moduna erişim sağlamalıdır.

Android 14'te çift ekran modu, katlanabilir cihazların iç ekranında çalışan uygulamaların kapak ekranında diğer kullanıcılara bakacak şekilde ek içerikler göstermesini sağlar. Örneğin, kapak ekranı, fotoğrafı çekilen veya kaydedilen kişiye kamera önizlemesini gösterebilir.

Cihaz yapılandırması

OEM'lerin katlama özelliğinin uygulanmasını desteklemek için şunları yapması gerekir:

• device_state_configuration.xml'teki cihaz durumlarını DeviceStateManagerService tarafından kullanılacak şekilde yapılandırın. Daha fazla bilgi için DeviceStateProviderImpl.java sayfasını inceleyin.

  Varsayılan DeviceStateProvider veya DeviceStatePolicy uygulaması cihaz için uygun değilse özel bir uygulama kullanılabilir.

• Açık veya düz modu destekleyen katlanabilir cihazlar için com.android.internal.R.array.config_openDeviceStates içinde ilgili durum tanımlayıcılarını belirtin.

• Katlanmış durumları destekleyen katlanabilir cihazlar için com.android.internal.R.array.config_foldedDeviceStates alanında ilgili durum tanımlayıcılarını listeleyin.

• Yarım katlanmış durumu (dizüstü bilgisayar gibi yarı açık) destekleyen katlanmış cihazlarda ilgili durumları com.android.internal.R.array.config_halfFoldedDeviceStates içinde listeleyin.

• Arka ekran modunu destekleyen cihazlar için:

  • DeviceStateManager için com.android.internal.R.array.config_rearDisplayDeviceStates içinde ilgili eyaletleri listeleyin.
  • com.android.internal.R.string.config_rearDisplayPhysicalAddress alanında arka ekranın fiziksel görüntüleme adresini belirtin.
  • Uzantılar tarafından kullanılacak com.android.internal.R.integer.config_deviceStateRearDisplay olan durum tanımlayıcısını belirtin.
  • Uygulamaların kullanabilmesi için com.android.internal.R.array.config_deviceStatesAvailableForAppRequests alanına eyalet tanımlayıcısını ekleyin.

• Android 14'te ikili (eş zamanlı) ekran modunu destekleyen cihazlar için:

  • com.android.internal.R.bool.config_supportsConcurrentInternalDisplays değerini true olarak ayarlayın.
  • Arka ekranın fiziksel görünen adresini com.android.internal.R.config_deviceStateConcurrentRearDisplay cinsinden belirtin.
  • Tanımlayıcının uygulamalar için sunulması gerekiyorsa Uzantılar tarafından kullanılacak durum tanımlayıcısını com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay dilinde belirtin.
  • Uygulamalarda kullanılabilir hale getirmek için com.android.internal.R.array.config_deviceStatesAvailableForAppRequests içine durum tanımlayıcısını ekleyin.

Doğrulama

Ortak senaryolarda beklenen davranışın sağlanması için OEM'lerin uygulamalarını doğrulamaları gerekir. OEM'ler, uygulamalarını test etmek için CTS testlerini ve Jetpack WindowManager'ı kullanan testleri kullanabilir.

CTS testleri

CTS testlerini çalıştırmak için CTS testlerini çalıştırma başlıklı makaleyi inceleyin. Jetpack WindowManager ile ilgili CTS testleri cts/tests/framework/base/windowmanager/jetpack/ altındadır. Test modülü adı CtsWindowManagerJetpackTestCases.

WindowManager testleri

Jetpack WindowManager testlerini indirmek için Android Jetpack Talimatları'nı uygulayın. Testler, pencere kitaplığındaki window:window modülü altında bulunur: window/window/src/androidTest/.

window:window modülüne ait cihaz testlerini komut satırından çalıştırmak için aşağıdakileri yapın:

1. Geliştirici seçenekleri ve USB üzerinden hata ayıklama özelliği etkin olan bir cihazı takın.
2. Bilgisayarın cihazda hata ayıklama yapmasına izin verin.
3. androidx deposunun kök dizininde bir kabuk açın.
4. Dizini framework/support olarak değiştirin.
5. Şu komutu çalıştırın: ./gradlew window:window:connectedAndroidTest.
6. Sonuçları analiz edin.

Testleri Android Studio'dan çalıştırmak için aşağıdakileri yapın:

1. Android Studio'yu açın.
2. Geliştirici seçenekleri ve USB üzerinden hata ayıklamanın etkin olduğu bir cihaz takın.
3. Bilgisayarın cihazda hata ayıklama yapmasına izin verin.
4. Pencere modülünün pencere kitaplığındaki bir teste gidin.
5. Bir test sınıfı açın ve düzenleyicinin sağ tarafındaki yeşil okları kullanarak çalıştırın.

Alternatif olarak, Android Studio'da bir test yöntemi, test sınıfı veya modüldeki tüm testleri çalıştırmak üzere bir yapılandırma oluşturabilirsiniz.

Sonuçlar, kabuğun çıkışına bakılarak manuel olarak analiz edilebilir. Cihaz belirli varsayımları karşılamıyorsa bazı testler atlanır. Sonuçlar standart bir konuma kaydedilir ve analistler, sonuçların analizini otomatikleştirmek için bir komut dosyası yazabilir.