WindowManager Extensions modülü

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, JAR kitaplığına derlenir ve cihaz makefile'ı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'ı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 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ü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:

Şekil 1. Uzantılar, uygulama sürecine yüklenir.

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 yardımcı dosyanın bakımı artık aktif olarak yapılmamaktadır.

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

Şekil 2. androidx.window.extensions veya androidx.window.sidecar'a erişim için karar ağacı.

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 (CDD) 7.1.1.1'de ö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 null 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. Extensions 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ı API'leri, uygulama geliştiriciler tarafından doğrudan çağrılmak üzere tasarlanmamıştır. Doğru işlevselliği sağlamak için Gradle derleme dosyasına bir uygulama için bağımlılık olarak uzantılar kitaplığı 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ı özellikleriyle ilgili 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 düşük seviyeli uzantı API'lerini daha yüksek seviyeli 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 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 daha 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. Bu nedenle, WindowManager'ın daha eski sürümlerini kullanan uygulamalar, derlendikleri eski uzantı 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 etkiye neden olmaz. 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

Etkinlik yerleştirme 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ştirmeniz önerilir. 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, 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 bunları göstermesini sağlar. Kullanım ayrıntıları için Uygulamanızı katlanabilir cihazlara uygun hale getirme başlıklı makaleyi inceleyin.

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 bildirilmeyebilecek durumlarda (ör. bir 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 cihazlardaki ö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'de 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 CDD'de (boyut, yoğunluk ve mevcut gezinme olanakları gibi özellikler açısından) tanımlandığı şekilde Android ile uyumlu bir kapak ekranı olan ve arka cihaz kameralarıyla aynı hizaya gelen cihazlar, arka ekran moduna erişim sağlamalıdır.

Android 14'te çift ekran modu, katlanabilir bir 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ı, fotoğrafı çekilen veya kaydı alınan kişiye kamera önizlemesini gösterebilir.

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ına bakın.

  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 öğesinde 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 eyalet 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 görüntüleme adresini com.android.internal.R.config_deviceStateConcurrentRearDisplay içinde belirtin.
  • Tanımlayıcının uygulamalarda kullanılmak üzere sunulması amaçlanıyorsa Uzantılar tarafından kullanılacak durum tanımlayıcısını com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay içinde belirtin.
  • Uygulamalarda kullanılabilmesi için eyalet 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'ı 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, window:window modülü altındaki 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. ./gradlew window:window:connectedAndroidTest komutunu çalıştırın.
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.