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 sürümünde AOSP'ye uygulanır ve WindowManager özelliklerini destekleyen cihazlarda gönderilir.

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

Cihaz makefile'inde uzantılar etkinse uzantılar bir .jar kitaplığına derlenir ve cihazdaki system_ext bölüme 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, bildirimler 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 aşağıdaki şekilde gösterildiği gibi işleyişini istemci tarafı çerçeve koduna benzer hale getirir:

Şekil 1. Platform koduna benzer şekilde uygulama sürecine yüklenen WindowManager uzantıları.

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 edilmiş eski bir modüldür ancak artık aktif olarak desteklenmemektedir.

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

Şekil 2. androidx.window.extensions veya androidx.window.sidecar'e erişmeyle ilgili karar ağacı.

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ı, Uyumluluk Tanımlama Belgesi (CDD) 7.1.1.1'de özellik özel olarak istenmediği sürece, WindowExtensions arayüzündeki yöntemlerin varsayılan veya taslak uygulamalarını içeren null bileşenler ya da bileşenler sağlayabilir.

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ştiricilere yönelik olmayan bir androidx.window.extensions Jetpack kitaplığında herkese açık olarak geliştirilir. Böylece Jetpack WindowManager (androidx.window), derleme sırasında bu kitaplığa bağlanabilir. 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. Uzantı API'lerinin doğrudan uygulama geliştiricileri tarafından çağrılması amaçlanmamıştır. Doğru işlevsellik sağlamak için Uzantılar kitaplığı, Gradle derleme dosyasında bir uygulamanın bağımlılığı olarak eklenmemelidir. Uzantılar kitaplığını doğrudan bir uygulamaya ö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ı yükleme durumunu önlemek için çalışma zamanında yükleme yöntemini kullanın.

Jetpack WindowManager (androidx.window), uygulama bağımlılığı olarak eklenmek üzere tasarlanmıştır ve WindowManager uzantıları özellikleri için olanlar da dahil olmak üzere geliştiricilere yönelik herkese açık API'ler sağlar. WindowManager kitaplığı, uzantıları uygulama sürecine otomatik olarak yükler ve alt düzey uzantı API'lerini daha üst düzey soyutlamalara ve daha odaklanmış arayüzlere sarmalar. WindowManager Jetpack API'leri, modern Android uygulama geliştirme standartlarını takip eder ve diğer AndroidX kitaplıklarını kullanan kod tabanlarıyla iyi entegre olarak uygun birlikte çalışabilirlik sunmayı amaç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.

Android platform sürümü	WindowManager Extensions API düzeyi	androidx.window.extensions API sürümü
Android 15	6	1.5.0 (yakında)
Android 14 QPR3	5	1.4.0 (yakında)
Android 14 QPR1	4	1.3.0
Android 14	3	1.2.0
Android 13 QPR3	2	1.1.0
Android 13	1	1.0.0
Android 12L	1	1.0.0

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

Not: OEM'lerin QPR güncellemelerini desteklemesi gerekmez ancak platform sürümünü ve Extensions API düzeyini aşağıdaki gibi koordine etmelidir:

• OEM'ler tarafından gönderilen tüm temel platform yazılımı sürümlerinde, tabloda tanımlanan uzantı sürümünün en azından aynısı olmalıdır.
• Platformun eski bir sürümünü, uzantıların daha yeni bir sürümüyle birlikte gönderebilirsiniz ancak genellikle uygulamanın işlevi desteklemesi için WindowManager çekirdeğinde de kapsamlı değişiklikler yapılması gerekir.
• Eski bir platform sürümünü ve uzantıların daha yeni bir sürümünü içeren uygulamalar, daha yeni uzantılar için ilgili uyumluluk testi paketini (CTS) geçmelidir. Uygulama, ilgili eski platform sürümü için CTS testleri aracılığıyla otomatik doğrulama almıyor.

Geriye ve ileriye dönük uyumluluk

Jetpack WindowManager, sık API seviyesi güncellemeleri, hızlı API gelişimi ve geriye dönük uyumlulukla ilgili karmaşıklığı ele alır. 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'lerinin çalışma zamanında Java yansıma kontrolünü de gerçekleştirir. Eşleşme yoksa WindowManager, uzantıların kullanımını (kısmen veya tamamen) devre dışı bırakabilir ve ilgili özellikleri uygulamanın kullanamayacağı şekilde bildirebilir.

WindowManager uzantıları, uzantı özelliklerinin uygulanmasında WindowManager çekirdeğini, DeviceStateManager ve diğer sistem hizmetlerini çağırmak için özel platform API'lerini kullanan bir system_ext modülü olarak uygulanır.

Uzantıların, sürümlerin nihai hâle getirildiği ilgili üç aylık veya yıllık Android platform sürümünden önceki sürümleri ile uyumluluk sağlanmayabilir. Uzantı API'lerinin tam geçmişini, sürüm şubesi window:extensions:extensions API metin dosyaları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, derlendikleri eski uzantı API'lerini kullanmaya devam edebilir.

CTS doğrulaması, cihazdaki uzantı API'lerinin beyan edilen tüm sürümlerinde, ilgili 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, modül özelliklerinin tek tek kullanılması uygulamaların performans özelliklerini biraz etkileyebilir.

Modüller

Etkinlik yerleştirme

Etkinlik yerleştirme bileşeni, uygulamaların kullanıcı arayüzlerini büyük ekranlı cihazlar ve harici ekranlar için optimize etmesine olanak tanır. Etkinlik yerleştirme, iki etkinliğin çok bölmeli bir düzende yan yana sunulmasını sağlar. Bu da eski uygulamalar için uyarlanabilir uygulama geliştirmeyi kolaylaştırır.

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

Not: Bazı OEM'ler uygulamaları sistem tanımlı etkinlik yerleştirmeye zorlar. Uygulamalar, uygulama manifest dosyasında PROPERTY_ACTIVITY_EMBEDDING_ALLOW_SYSTEM_OVERRIDE değerini ayarlayarak sistem tanımlı etkinlik yerleştirilmesini engelleyebilir. Bir uygulama özelliği false olarak ayarlarsa sistem, uygulamayı sistem tanımlı etkinlik yerleştirmeye zorlamamalıdır.

Cihaz yapılandırması

Uzantılar modülü dağıtımı bölümünde açıklandığı şekilde 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ümleri, yaygın el cihazı ve büyük ekranlı cihaz yapılandırmalarında uzantıların kullanılmasını zorunlu kılabilir.

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 vermesine ve bunları göstermesine olanak tanır. Kullanımla ilgili ayrıntılar için Uygulamanızı katlanabilir cihazlara uyumlu hale getirme başlıklı makaleyi inceleyin.

Ayrı veya sürekli ekran paneli alanlarını birbirine bağlayan bir menteşe içeren katlanabilir Android cihazlar, menteşeyle ilgili bilgileri WindowLayoutComponent aracılığıyla uygulamalara sunmalıdır.

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 raporlanamayacaksa (ör. uygulama penceresi çoklu pencere modunda veya uyumluluk sinemaskop modunda kullanıcı tarafından serbestçe taşınabiliyorsa) ekran özelliklerinin bildirilmemesi de kabul edilir.

Katlanabilir özellikler için menteşe konumu kararlı durumlar arasında değiştiğinde durum güncellemeleri raporlanmalıdır. Varsayılan olarak düz ekran durumunda API, FoldingFeature.State.FLAT değerini bildirmelidir. 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 bölümüne bakın.

  DeviceStateProvider veya DeviceStatePolicy özelliklerinin 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 dize kaynağında 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 fazla 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 şudur:

  <device_specific_state_identifier>:<Jetpack WindowManager state identifier>

  Desteklenen eyalet 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, katlanabilir cihazların kapalı durumu olabilir.
  • COMMON_STATE_HALF_OPENED = 2: Katlama özelliği yarı açıktır.
  • 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, menteşe durumunun CommonFoldingFeature.java bölümünde tanımlandığı gibi temel durum kullanılarak türetildiği taklit edilen durumlar için kullanılabilecek bir değer

  Daha fazla bilgi için DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int) bölümünü inceleyin.

  Ö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 çok ekranlı cihazlardaki ek ekranlara ve ekran alanlarına erişmesine olanak tanıyan bir dizi özellik sağlar.

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

Android 14'te çift ekran modu, katlanabilir cihazın iç ekranında çalışan uygulamaların diğer kullanıcılara bakan kapak ekranında ek içerik göstermesini sağlar. Örneğin, kapak ekranı kamera önizlemesini fotoğrafı çekilen veya videoya kaydedilen kişiye 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ına göz atın.

  DeviceStateProvider veya DeviceStatePolicy için varsayılan uygulama cihaz için uygun değilse özel 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 bölümünde ilgili durum tanımlayıcılarını listeleyin.

• Yarı katlanmış durumu destekleyen katlanabilir cihazlar için (menteşe, dizüstü bilgisayar gibi yarı açıktır) com.android.internal.R.array.config_halfFoldedDeviceStates bölümünde ilgili durumları listeleyin.

• Arka ekran modunu destekleyen cihazlar için:

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

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

  • com.android.internal.R.bool.config_supportsConcurrentInternalDisplays değerini true olarak ayarlayın.
  • com.android.internal.R.config_deviceStateConcurrentRearDisplay alanında arka ekranın fiziksel görüntüleme adresini belirtin.
  • Tanımlayıcının uygulamalara sunulması gerekiyorsa com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay bölümünde, uzantılar tarafından kullanılacak durum tanımlayıcısını belirtin.
  • Uygulamaların kullanabilmesi için com.android.internal.R.array.config_deviceStatesAvailableForAppRequests alanına eyaletin tanımlayıcısını ekleyin.

Doğrulama

OEM'ler, yaygın senaryolarda beklenen davranışı sağlamak için uygulamalarını doğrulamalıdır. CTS testleri ve Jetpack WindowManager'ı kullanan testler, OEM'ler tarafından uygulama testleri için kullanılabilir.

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ğinin etkin olduğu 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. Aşağıdaki 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ıklama özelliğinin 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öntemini, test sınıfını veya bir modüldeki tüm testleri çalıştırmak için yapılandırma oluşturabilirsiniz.

Kabuğun çıktısına bakarak sonuçlar 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.