WindowManager Uzantıları

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

WindowManager Uzantıları (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'a dahil etmek, bildirimleri etc/permissions/ içine de yerleştirerek uygulama süreçlerinde kullanılabilir hale getirir. Normalde modüller, Jetpack WindowManager kitaplığı tarafından kullanıldığında çalışma zamanında uygulama sürecine yüklenir ve bu sürecin bir parçası olarak yürütülür. Bu da modüllerin çalışmasını aşağıdaki şekilde gösterildiği gibi 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 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 pencerelemeyi destekleyen cihazlar için pencereleme özellikleri sunar. Özellik alanları şunlardır:

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

Cihaz donanımı ilgili özellikleri desteklemiyorsa, özellik Uyumluluk Tanımı Belgesi'nde (CDD) 7.1.1.1 özellikle istenmediği sürece, OEM'ler Uzantılar'ı uygularken WindowExtensions arayüzündeki yöntemlerin varsayılan veya taslak uygulamalarını içeren 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ü, Jetpack WindowManager'ın (androidx.window) derleme zamanında buna karşı bağlantı oluşturabilmesi için geliştiricilere yönelik olmayan bir androidx.window.extensions Jetpack kitaplığında herkese açık olarak geliştirilir. 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ına uygulama 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ı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ılar API'lerini daha yüksek düzeydeki soyutlamalar ve daha odaklanmış arayüzlerle sarmalar. 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 listelenmiştir.

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 mevcut Extensions API'lerinin çalışma zamanında 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ı, Uzantılar ö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.

Uyumluluk, 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 olmayan 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 etmesini 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ılabilir olmalıdır. Harici ekran bağlantılarını destekleyen cihazlarda etkinlik yerleştirme de 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 cihaz ve büyük ekranlı cihaz yapılandırmalarında Uzantılar'ın zorunlu olması muhtemeldir.

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 başlıklı makaleye 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 durumda 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 bölümünde 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ü 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: Eyalette raporlanacak katlama özellikleri yok. Örneğin, ana ekranı iç tarafta olan, katlanabilen tipik bir cihazın kapalı durumu olabilir.
  • COMMON_STATE_HALF_OPENED = 2: Katlama özelliği yarıya kadar açılmış.
  • COMMON_STATE_FLAT = 3: Katlama özelliği düzdür. Örneğin, ana ekranı iç tarafta olan, katlanabilen 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 türetildiği, emüle edilmiş durumlar için kullanılabilen bir değer.

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

  Ö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 mevcut gezinme olanakları gibi özellikler açısından Android CDD'de tanımlandığı şekilde) ve arka cihaz kameralarıyla uyumlu bir kapak ekranı olan 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 bölümünde 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 içinde 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 listesinde belirtin.

• Arka ekran modunu destekleyen cihazlar için:

  • DeviceStateManager için com.android.internal.R.array.config_rearDisplayDeviceStates içinde ilgili eyaletleri listeleyin.
  • Arka ekranın fiziksel ekran adresini com.android.internal.R.string.config_rearDisplayPhysicalAddress içinde belirtin.
  • Uzantılar tarafından kullanılacak com.android.internal.R.integer.config_deviceStateRearDisplay 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 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 ekran adresini com.android.internal.R.config_deviceStateConcurrentRearDisplay içinde belirtin.
  • Tanımlayıcının uygulamalarda kullanılmak üzere sunulması 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 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 kullanılarak yapılan testler, uygulamaları test etmek için OEM'lere sunulur.

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, window:window modülündeki pencere kitaplığında bulunur: 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, bir test yöntemi, test sınıfı veya bir modüldeki tüm testleri çalıştırmak için Android Studio'da 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.