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 isteğe bağlı bir Android platform modülüdür. Modül, AOSP'de frameworks/base/libs/WindowManager/Jetpack içinde uygulanır ve WindowManager özelliklerini destekleyen cihazlarda gönderilir.

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

Uzantılar, cihaz makefile'ında etkinleştirilmişse .jar kitaplığında derlenir ve cihazdaki system_ext bölümüne yerleştirilir.

Bir cihazda uzantıları etkinleştirmek için ürün cihazı makefile'ına 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 özelliğini ayarlar. Bu paketleri makefile dosyasına eklemek, bildirimleri etc/permissions/ içine de yerleştirerek uygulama süreçlerinde kullanılabilir hale getirir. Normalde, Jetpack WindowManager kitaplığı tarafından kullanıldığında modüller ç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, çalışmasını istemci tarafı çerçeve koduna benzer hale getirir:

androidx.window.extensions modülü, şu anda etkin geliştirme aşamasında olan mevcut Uzantılar modülüdür. androidx.window.sidecar modülü, Jetpack WindowManager'ın en eski sürümleriyle uyumluluk için eklenmiş eski bir modüldür. Ancak sidecar artık aktif olarak desteklenmemektedir.

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

Uzantı modülleri

Uzantılar, katlanabilir büyük ekranlı cihazlar ve harici ekranlarda pencereli görüntülemeyi destekleyen cihazlar için pencereli görüntüleme özellikleri sunar. Özellik alanları şunlardır:

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

Cihaz donanımı ilgili özellikleri desteklemiyorsa, özellik Uyumluluk Tanımlama Belgesi'nde (CDD) 7.1.1.1 özellikle istenmediği sürece, Uzantıların OEM uygulamaları WindowExtensions arayüzündeki yöntemlerin varsayılan veya kaba kod uygulamalarını içeren bileşenler ya da boş bileşenler sağlayabilir.

Uzantılar ve Jetpack API'leri

WindowManager Extensions 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 zamanında buna 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ılmak üzere tasarlanmıştır. Uzantılar API'lerinin doğrudan uygulama geliştiriciler tarafından çağrılması amaçlanmamıştır. Doğru işlevsellik için uzantılar kitaplığı, Gradle derleme dosyasındaki bir uygulamaya bağımlılık 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ılar sınıflarının 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 eklenmek üzere tasarlanmıştır ve WindowManager Uzantıları özellikleri de 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 daha düşük düzeydeki uzantı API'lerini daha yüksek düzeydeki soyutlamalara ve daha odaklanmış arayüzlere sarar. WindowManager Jetpack API'leri, modern Android uygulama geliştirme standartlarına uygundur ve diğer AndroidX kitaplıklarını kullanan kod tabanlarıyla iyi entegre olarak kolay birlikte çalışabilirlik sağlamayı amaçlar.

Uzantı sürümleri ve güncellemeleri

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

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

Mevcut kararlı API yüzeyine (sağ sütun) her ekleme yapıldığında Uzantılar API düzeyi (orta sütun) artırılır.

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, bildirilen Extensions API düzeyini kontrol eder ve bildirilen düzeye göre özelliklere erişim sağlar.

WindowManager, bir uygulamanın çalışma zamanında kilitlenmesini önlemek için bildirilen Extensions API düzeyine göre kullanılabilir Extensions API'lerin çalışma zamanı Java yansıtma kontrolünü 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ılamaz olarak bildirebilir.

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

Uyum, sürümlerin son hâlini aldığı ilgili üç aylık veya yıllık Android platform sürümünden önceki, uzantıların yayın öncesi sürümlerinde korunmayabilir. Extensions API'lerinin tam geçmişini window:extensions:extensions API metin dosyaları sürüm dalında bulabilirsiniz.

Uzantıların daha yeni sürümleri, ileriye dönük uyumluluğu korumak için uygulamalara derlenen WindowManager'ın eski sürümleriyle çalışmaya devam etmelidir. Bunu sağlamak için Extensions API'nin yeni sürümlerinde yalnızca yeni API'ler eklenir ve eski API'ler kaldırılmaz. Sonuç olarak, eski WindowManager sürümlerine sahip uygulamalar, derlendikleri eski Uzantılar API'lerini kullanmaya devam edebilir.

CTS doğrulaması, cihazdaki Extensions API'lerinin beyan edilen herhangi bir sürümü için bu ve önceki sürümlere ait tüm API'lerin mevcut ve işlevsel 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 dışındaki sistem sınıfı yükleyicilerinde önbelleğe alınır. Bu nedenle, modülün uygulama başlatılırken belleğe yüklenmesi performans üzerinde herhangi bir etki yaratmaz. Ayrı modül özelliklerinin kullanılması, istemci ile sunucu arasında ek IPC çağrıları yapıldığında uygulamaların performans özellikleri üzerinde hafif bir etkiye sahip olabilir.

Modüller

Etkinlik yerleştirme

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

Etkinlik yerleştirme bileşeni, yerleşik ekranı sw600dp veya daha büyük olan tüm cihazlarda kullanılabilmelidir. Harici ekran bağlantılarını destekleyen cihazlarda da etkinlik yerleştirme etkinleştirilmelidir. Aksi takdirde, harici ekranlar çalışma zamanında bağlandığında uygulama daha büyük bir boyutta gösterilebilir.

Cihaz yapılandırması

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

Pencere düzeni bilgileri

Pencere düzeni bilgileri bileşeni, katlanabilir bir cihazda menteşe bir uygulama penceresini geçtiğinde 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 bunları göstermesini sağlar. Kullanımla ilgili ayrıntılar için Uygulamanızı katlanabilir cihazlara uygun hale getirme konusuna bakın.

Ayrı veya sürekli ekran paneli alanlarını bağlayan bir menteşe içeren katlanabilir Android cihazlar, menteşe hakkındaki 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 raporlanmamalıdır. Ayrıca, konumları güvenilir bir şekilde bildirilmeyebileceği durumlarda (ör. uygulama penceresi, çoklu pencere modunda veya uyumluluk için mektup kutusu modunda kullanıcı tarafından serbestçe taşınabildiğinde) görüntüleme özelliklerinin bildirilmemesi de kabul edilebilir.

Katlanabilir özellikler için menteşe konumu sabit durumlar arasında değiştiğinde durum güncellemeleri bildirilmelidir. API, varsayılan olarak düz bir görüntüleme durumunda FoldingFeature.State.FLAT değerini bildirmelidir. Cihaz donanımı, yarı katlanmış modda sabit bir şekilde bırakılabiliyorsa API, FoldingFeature.State.HALF_OPENED değerini bildirmelidir. Uygulama penceresi bu durumda görünür olmayacağı veya menteşe sınırlarını aşmayacağı için API'de kapalı durum yoktur.

Cihaz yapılandırması

Katlama özelliği uygulamasını desteklemek için OEM'lerin aşağıdakileri yapması gerekir:

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

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

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

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

  Dize için beklenen biçim:

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

  type, fold veya hinge olabilir. left, top, right ve bottom değerleri, doğal ekran yönündeki ekran koordinat alanında bulunan 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.

  Örneğin:

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

• DeviceStateManager içinde kullanılan dahili cihaz durumu tanımlayıcıları ile com.android.internal.R.array.config_device_state_postures içinde 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: Durumda raporlanacak katlama özellikleri yok. Örneğin, ana ekranı iç tarafta olan, katlanarak kapanan tipik bir cihazın kapalı durumu olabilir.
  • COMMON_STATE_HALF_OPENED = 2: Katlama özelliği yarı açık.
  • COMMON_STATE_FLAT = 3: Katlama özelliği düzdür. Örneğin, ana ekranı iç tarafta olan, içe katlanan tipik bir cihazın açık durumu olabilir.
  • COMMON_STATE_USE_BASE_STATE = 1000: Android 14'te, menteşe durumunun CommonFoldingFeature.java içinde tanımlandığı şekilde temel durum kullanılarak elde edildiği, emüle edilmiş durumlar için kullanılabilen bir değer.

  Daha fazla bilgi için DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int) sayfasını inceleyin.

  Örneğin:

  <!-- 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, uygulamalara bazı katlanabilir ve çok ekranlı cihazlarda ek ekranlara ve ekran alanlarına erişim sağlayan bir dizi özellik sunar.

Arka ekran modu, bir uygulamanın katlanabilir cihazın kapak ekranında kamera önizleme kullanıcı arayüzünü göstermesini sağlar. Böylece, ana cihazın kamerasıyla selfie ve video çekilebilir. Android ile uyumlu (boyut, yoğunluk ve kullanılabilir gezinme olanakları gibi özellikler açısından Android CDD'de tanımlandığı şekilde) bir kapak ekranı olan ve arka cihaz kameralarıyla uyumlu 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 diğer kullanıcılara bakan kapak ekranında ek içerik göstermesini sağlar. Örneğin, kapak ekranında fotoğrafı çekilen veya kaydı alınan kişiye kamera önizlemesi gösterilebilir.

Cihaz yapılandırması

Katlama özelliği uygulamasını desteklemek için OEM'lerin aşağıdakileri yapması gerekir:

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

  DeviceStateProvider veya DeviceStatePolicy için varsayılan uygulama cihaza 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 bölümünde ilgili durum tanımlayıcılarını belirtin.

• Katlanmış durumları destekleyen içe katlanan cihazlar için ilgili durum tanımlayıcılarını com.android.internal.R.array.config_foldedDeviceStates bölümünde listeleyin.

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

• Arka ekran modunu destekleyen cihazlar için:

  • com.android.internal.R.array.config_rearDisplayDeviceStates için DeviceStateManager bölümünde ilgili eyaletleri listeleyin.
  • Arka ekranın fiziksel görüntüleme adresini com.android.internal.R.string.config_rearDisplayPhysicalAddress içinde belirtin.
  • Uzantılar tarafından kullanılacak com.android.internal.R.integer.config_deviceStateRearDisplay içindeki eyalet tanımlayıcısını belirtin.
  • Uygulamalarda kullanılabilmesi için durum tanımlayıcısını com.android.internal.R.array.config_deviceStatesAvailableForAppRequests içine ekleyin.

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

  • com.android.internal.R.bool.config_supportsConcurrentInternalDisplays değerini true olarak ayarlayın.
  • Arka ekranın fiziksel görüntüleme adresini com.android.internal.R.config_deviceStateConcurrentRearDisplay içinde belirtin.
  • Tanımlayıcının uygulamalarda kullanılabilmesi amaçlanıyorsa com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay uzantılar tarafından kullanılacak eyalet tanımlayıcısını belirtin.
  • Uygulamalarda kullanılabilmesi için durum tanımlayıcısını com.android.internal.R.array.config_deviceStatesAvailableForAppRequests içine ekleyin.

Doğrulama

OEM'ler, yaygın senaryolarda beklenen davranışın gerçekleşmesini sağlamak için uygulamalarını doğrulamalıdır. CTS testleri ve Jetpack WindowManager'ı kullanan testler, OEM'lerin uygulamaları test etmesi 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ında yer alır. Test modülünün adı CtsWindowManagerJetpackTestCases.

WindowManager testleri

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

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

1. Geliştirici seçenekleri ve USB üzerinden hata ayıklama etkin olan bir cihazı takın.
2. Bilgisayarın cihazda hata ayıklaması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 etkin olan bir cihazı takın.
3. Bilgisayarın cihazda hata ayıklamasına izin verin.
4. Pencere modülünün pencere kitaplığında 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 bir modüldeki tüm testleri çalıştırmak için 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.