Estensioni WindowManager

La libreria Jetpack WindowManager consente agli sviluppatori di applicazioni di supportare nuovi fattori di forma dei dispositivi e ambienti multi-finestra.

WindowManager Extensions (Estensioni) è un modulo della piattaforma Android con attivazione facoltativa che abilita una serie di funzionalità di Jetpack WindowManager. Il modulo è implementato in AOSP in frameworks/base/libs/WindowManager/Jetpack e viene fornito sui dispositivi che supportano le funzionalità di WindowManager.

Distribuzione del modulo delle estensioni

Le estensioni vengono compilate in una libreria .jar e inserite nella partizione system_ext di un dispositivo se le estensioni sono attivate nel makefile del dispositivo.

Per attivare le estensioni su un dispositivo, aggiungi quanto segue al makefile del dispositivo prodotto:

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

Vengono attivati i pacchetti androidx.window.extensions e androidx.window.sidecar sul dispositivo e viene impostata la proprietà persist.wm.extensions.enabled. L'inclusione di questi pacchetti nel makefile inserisce anche le dichiarazioni in etc/permissions/, rendendole disponibili per i processi dell'applicazione. Normalmente, i moduli vengono caricati ed eseguiti come parte del processo dell'applicazione in fase di runtime quando vengono utilizzati dalla libreria Jetpack WindowManager, il che rende il suo funzionamento simile al codice del framework lato client, come mostrato nella figura seguente:

Figura 1. Estensioni WindowManager caricate nel processo dell'applicazione in modo simile al codice della piattaforma.

Il modulo androidx.window.extensions è l'attuale modulo Estensioni in fase di sviluppo attivo. Il modulo androidx.window.sidecar è un modulo legacy incluso per la compatibilità con le prime versioni di Jetpack WindowManager, ma il sidecar non è più gestito attivamente.

La figura seguente mostra la logica per determinare l'utilizzo di androidx.window.extensions o androidx.window.sidecar.

Figura 2. Albero decisionale per accedere a androidx.window.extensions o androidx.window.sidecar.

Moduli delle estensioni

Le estensioni forniscono funzionalità di gestione delle finestre per i dispositivi pieghevoli con schermi di grandi dimensioni e per i dispositivi che supportano la gestione delle finestre su display esterni. Le aree delle funzionalità includono:

• Incorporamento delle attività
• Informazioni sul layout della finestra
• Area della finestra

Le implementazioni OEM delle estensioni possono fornire componenti null o componenti con implementazioni predefinite o stub dei metodi nell'interfaccia WindowExtensions se l'hardware del dispositivo non supporta le funzionalità corrispondenti, a meno che la funzionalità non sia specificamente richiesta nel Compatibility Definition Document (CDD) 7.1.1.1.

Estensioni e API Jetpack

Il modulo WindowManager Extensions fornisce una propria superficie API oltre alle API della piattaforma pubblica. Il modulo Estensioni è sviluppato pubblicamente in una libreria Jetpack androidx.window.extensions non rivolta agli sviluppatori, in modo che Jetpack WindowManager (androidx.window) possa collegarsi in fase di compilazione. La superficie dell'API Extensions in genere fornisce API di livello inferiore.

Le API fornite dalle estensioni sono destinate all'uso esclusivo della libreria Jetpack WindowManager. Le API Extensions non sono pensate per essere chiamate direttamente dagli sviluppatori di applicazioni. Per garantire il corretto funzionamento, la libreria delle estensioni non deve essere aggiunta come dipendenza per un'applicazione nel file di build Gradle. Evita di precompilare la libreria Extensions direttamente in un'applicazione. Affidati invece al caricamento in fase di runtime per evitare di caricare un mix di classi Extensions precompilate e fornite in fase di runtime.

Jetpack WindowManager (androidx.window) deve essere aggiunto come dipendenza dell'applicazione e fornisce le API pubbliche rivolte agli sviluppatori, incluse quelle per le funzionalità delle estensioni di WindowManager. La libreria WindowManager carica automaticamente le estensioni nel processo dell'applicazione e racchiude le API Extensions di livello inferiore in astrazioni di livello superiore e interfacce più mirate. Le API Jetpack WindowManager seguono gli standard dello sviluppo di applicazioni Android moderne e sono pensate per fornire una comoda interoperabilità integrandosi bene con i codebase che utilizzano altre librerie AndroidX.

Versioni e aggiornamenti delle estensioni

Il modulo Estensioni può essere aggiornato insieme alla piattaforma Android con aggiornamenti annuali o trimestrali. Gli aggiornamenti trimestrali consentono di aumentare il livello dell'API Extensions tra gli aggiornamenti dell'API della piattaforma Android, consentendo un'iterazione più rapida e offrendo agli OEM l'opportunità di aggiungere l'accesso ufficiale alle API alle nuove funzionalità in prossimità dei lanci hardware.

La tabella seguente elenca le versioni dell'API androidx.window.extensions per le varie release di Android.

Versione della piattaforma Android	Livello API WindowManager Extensions	Versione dell'API androidx.window.extensions
Android 15	6	1.5.0 (disponibile a breve)
Android 14 QPR3	5	1.4.0 (disponibile a breve)
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

Il livello API delle estensioni (colonna centrale) aumenta ogni volta che viene aggiunta una funzionalità alla superficie API stabile esistente (colonna di destra).

Nota: gli OEM non sono tenuti a supportare gli aggiornamenti QPR, ma devono coordinare la versione della piattaforma e il livello dell'API Extensions nel seguente modo:

• Qualsiasi versione software della piattaforma di base spedita dagli OEM deve avere almeno la stessa versione delle estensioni definita nella tabella.
• Puoi spedire una versione precedente della piattaforma con una versione più recente delle estensioni, ma di solito l'implementazione richiede anche modifiche approfondite nel core di WindowManager per supportare la funzionalità.
• Le implementazioni che includono una versione precedente della piattaforma e una versione più recente delle estensioni devono superare la suite di test di compatibilità (CTS) corrispondente per le estensioni più recenti. L'implementazione non viene verificata automaticamente tramite i test CTS per la versione della piattaforma precedente corrispondente.

Compatibilità con le versioni precedenti e successive

Jetpack WindowManager gestisce la complessità della gestione di aggiornamenti frequenti del livello API, dell'evoluzione rapida delle API e della compatibilità con le versioni precedenti. Quando il codice della libreria viene eseguito nella procedura di applicazione, la libreria controlla il livello dell'API Extensions dichiarata e fornisce l'accesso alle funzionalità in base al livello dichiarato.

Per proteggere un'applicazione da arresti anomali in fase di esecuzione, WindowManager esegue anche un controllo di reflection Java in fase di esecuzione delle API Extensions disponibili in base al livello API Extensions dichiarato. In caso di mancata corrispondenza, WindowManager può disattivare l'utilizzo delle estensioni (in parte o completamente) e segnalare le funzionalità pertinenti come non disponibili per l'applicazione.

Le estensioni WindowManager sono implementate come modulo system_ext che utilizza API della piattaforma private per chiamare il core di WindowManager, DeviceStateManager, e altri servizi di sistema nell'implementazione delle funzionalità delle estensioni.

La compatibilità potrebbe non essere mantenuta con le versioni pre-release delle estensioni prima del rilascio trimestrale o annuale corrispondente della piattaforma Android con cui le versioni vengono finalizzate. La cronologia completa delle API Extensions è disponibile nel ramo di rilascio window:extensions:extensions API text files.

Le versioni più recenti delle estensioni devono continuare a funzionare con le versioni precedenti di WindowManager compilate nelle applicazioni per mantenere la compatibilità futura. Per garantire questo, qualsiasi nuova versione dell'API Extensions aggiunge solo nuove API e non rimuove quelle precedenti. Di conseguenza, le applicazioni con versioni precedenti di WindowManager possono continuare a utilizzare le API Extensions precedenti con cui sono state compilate.

La verifica CTS garantisce che per qualsiasi versione dichiarata delle API Extensions sul dispositivo, tutte le API per quella versione e le precedenti siano presenti e funzionanti.

Prestazioni

Il modulo Estensioni viene memorizzato nella cache nei caricatori di classi di sistema non bootclasspath per impostazione predefinita a partire da Android 14 (livello API 34), quindi non si verifica alcun impatto sulle prestazioni dovuto al caricamento del modulo in memoria all'avvio dell'app. L'utilizzo delle funzionalità dei singoli moduli potrebbe influire leggermente sulle caratteristiche di rendimento delle app quando vengono eseguite chiamate IPC aggiuntive tra il client e il server.

Moduli

Incorporamento delle attività

Il componente incorporamento dell'attività consente alle applicazioni di ottimizzare la propria UI per i dispositivi con schermi di grandi dimensioni e display esterni. L'incorporamento delle attività consente la presentazione di due attività affiancate in un layout a più riquadri, facilitando lo sviluppo di app adattive per applicazioni legacy.

Il componente di incorporamento dell'attività deve essere disponibile su tutti i dispositivi con un display integrato uguale o superiore a sw600dp. L'incorporamento dell'attività deve essere attivato anche sui dispositivi che supportano connessioni di display esterni, in quanto l'applicazione potrebbe essere visualizzata in dimensioni maggiori quando i display esterni sono connessi in fase di runtime.

Nota :alcuni OEM forzano l'incorporamento di attività definite dal sistema nelle app. Le app possono impedire l'incorporamento di attività definite dal sistema impostando PROPERTY_ACTIVITY_EMBEDDING_ALLOW_SYSTEM_OVERRIDE nel file manifest dell'app. Se un'app ha impostato la proprietà su false, il sistema non deve forzare l'incorporamento dell'attività definita dal sistema nell'app.

Configurazione dispositivo

Non è necessaria alcuna configurazione specifica del dispositivo, se non l'attivazione del modulo Estensioni come descritto nella sezione Distribuzione del modulo Estensioni. È consigliabile attivare le estensioni su tutti i dispositivi che supportano la modalità multi-finestra. È probabile che le versioni future di Android richiederanno le estensioni nelle configurazioni comuni di dispositivi portatili e con schermi di grandi dimensioni.

Informazioni sul layout delle finestre

Il componente delle informazioni sul layout della finestra identifica la posizione e lo stato della cerniera su un dispositivo pieghevole quando la cerniera attraversa una finestra dell'applicazione. Le informazioni sul layout della finestra consentono alle applicazioni di rispondere e mostrare layout ottimizzati in modalità Tabletop sui dispositivi pieghevoli. Per informazioni dettagliate, consulta Rendere la tua app compatibile con la piega.

I dispositivi Android pieghevoli che includono una cerniera che collega aree del pannello del display separate o continue devono rendere disponibili le informazioni sulla cerniera alle applicazioni tramite WindowLayoutComponent.

La posizione e i limiti della cerniera devono essere segnalati rispetto alla finestra dell'applicazione identificata da un Context passato all'API. Se i limiti della finestra dell'applicazione non si intersecano con i limiti della cerniera, la cerniera DisplayFeature non deve essere segnalata. È inoltre accettabile non segnalare le funzionalità di visualizzazione quando la loro posizione potrebbe non essere segnalata in modo affidabile, ad esempio quando una finestra dell'applicazione può essere spostata liberamente dall'utente in modalità multi-finestra o in modalità letterbox di compatibilità.

Per le funzionalità di piegatura, gli aggiornamenti dello stato devono essere segnalati quando la posizione della cerniera cambia tra gli stati stabili. Per impostazione predefinita, in uno stato di visualizzazione piatta, l'API deve segnalare FoldingFeature.State.FLAT. Se l'hardware del dispositivo può essere lasciato in modalità semi-piegata in uno stato stabile, l'API deve segnalare FoldingFeature.State.HALF_OPENED. Non esiste uno stato chiuso nell'API, poiché in questo caso la finestra dell'applicazione non sarebbe visibile o non attraverserebbe i limiti della cerniera.

Configurazione dispositivo

Per supportare l'implementazione della funzionalità di piegatura, gli OEM devono:

• Configura gli stati del dispositivo in device_state_configuration.xml da utilizzare con DeviceStateManagerService. Per riferimento, consulta DeviceStateProviderImpl.java.

  Se le implementazioni predefinite di DeviceStateProvider o DeviceStatePolicy non sono adatte al dispositivo, è possibile utilizzare un'implementazione personalizzata.

• Attiva il modulo Estensioni come descritto nella sezione Distribuzione del modulo Estensioni.

• Specifica la posizione delle funzionalità di visualizzazione nella risorsa stringa com.android.internal.R.string.config_display_features (di solito in frameworks/base/core/res/res/values/config.xml nell'overlay del dispositivo).

  Il formato previsto per la stringa è:

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

  Il type può essere fold o hinge. I valori di left, top, right e bottom sono coordinate pixel intere nello spazio delle coordinate del display nell'orientamento naturale del display. La stringa di configurazione può contenere più funzionalità di visualizzazione separate da punti e virgole.

  Ad esempio:

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

• Definisci la mappatura tra gli identificatori dello stato del dispositivo interni utilizzati in DeviceStateManager e le costanti di stato pubbliche inviate agli sviluppatori in com.android.internal.R.array.config_device_state_postures.

  Il formato previsto per ogni voce è:

  <device_specific_state_identifier>:<Jetpack WindowManager state identifier>

  Gli identificatori di stato supportati sono:

  • COMMON_STATE_NO_FOLDING_FEATURES = 1: Lo stato non ha funzionalità di piegatura da segnalare. Ad esempio, può essere lo stato chiuso del tipico dispositivo pieghevole con lo schermo principale sul lato interno.
  • COMMON_STATE_HALF_OPENED = 2: la funzionalità di piegatura è aperta a metà.
  • COMMON_STATE_FLAT = 3: La funzionalità di piegatura è piatta. Ad esempio, può essere lo stato aperto del tipico dispositivo pieghevole con lo schermo principale sul lato interno.
  • COMMON_STATE_USE_BASE_STATE = 1000: in Android 14, un valore che può essere utilizzato per gli stati emulati in cui lo stato della cerniera viene derivato utilizzando lo stato di base, come definito in CommonFoldingFeature.java

  Per saperne di più, consulta DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int).

  Ad esempio:

  <!-- 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>
  

Area della finestra

Il componente area della finestra fornisce un insieme di funzionalità che consentono alle applicazioni di accedere a display e aree di visualizzazione aggiuntivi su alcuni dispositivi pieghevoli e con più display.

La modalità Display posteriore consente a un'applicazione di mostrare la UI di anteprima della fotocamera sul display della cover di un dispositivo pieghevole per consentire l'utilizzo della fotocamera principale del dispositivo per selfie e video. I dispositivi con un display di copertura compatibile con Android (come definito dalla CDD di Android in termini di attributi quali dimensioni, densità e ausili di navigazione disponibili) che si allinea alle videocamere del dispositivo posteriore deve fornire l'accesso alla modalità display posteriore.

Su Android 14, la modalità Dual Display consente alle applicazioni in esecuzione sul display interno di un dispositivo pieghevole di mostrare contenuti aggiuntivi sul display della cover rivolto ad altri utenti. Ad esempio, il display della cover può mostrare l'anteprima della fotocamera alla persona fotografata o registrata.

Configurazione dispositivo

Per supportare l'implementazione della funzionalità di piegatura, gli OEM devono:

• Configura gli stati del dispositivo in device_state_configuration.xml da utilizzare con DeviceStateManagerService. Per saperne di più, consulta DeviceStateProviderImpl.java.

  Se l'implementazione predefinita di DeviceStateProvider o DeviceStatePolicy non è adatta al dispositivo, è possibile utilizzare un'implementazione personalizzata.

• Per i dispositivi pieghevoli che supportano la modalità aperta o piatta, specifica gli identificatori di stato corrispondenti in com.android.internal.R.array.config_openDeviceStates.

• Per i dispositivi pieghevoli che supportano gli stati di chiusura, elenca gli identificatori di stato corrispondenti in com.android.internal.R.array.config_foldedDeviceStates.

• Per i dispositivi pieghevoli che supportano uno stato di chiusura parziale (la cerniera è aperta a metà come un laptop), elenca gli stati corrispondenti in com.android.internal.R.array.config_halfFoldedDeviceStates.

• Per i dispositivi che supportano la modalità display posteriore:

  • Elenca gli stati corrispondenti in com.android.internal.R.array.config_rearDisplayDeviceStates per DeviceStateManager.
  • Specifica l'indirizzo di visualizzazione fisico del display posteriore in com.android.internal.R.string.config_rearDisplayPhysicalAddress.
  • Specifica l'identificatore di stato in com.android.internal.R.integer.config_deviceStateRearDisplay da utilizzare per le estensioni.
  • Aggiungi l'identificatore di stato in com.android.internal.R.array.config_deviceStatesAvailableForAppRequests per renderlo disponibile alle applicazioni.

• Su Android 14, per i dispositivi che supportano la modalità Dual (concorrente) display:

  • Imposta com.android.internal.R.bool.config_supportsConcurrentInternalDisplays su true.
  • Specifica l'indirizzo di visualizzazione fisico del display posteriore in com.android.internal.R.config_deviceStateConcurrentRearDisplay.
  • Specifica l'identificatore di stato in com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay da utilizzare dalle estensioni se l'identificatore deve essere reso disponibile per le applicazioni.
  • Aggiungi l'identificatore di stato in com.android.internal.R.array.config_deviceStatesAvailableForAppRequests per renderlo disponibile alle applicazioni.

Verifica

Gli OEM devono verificare le proprie implementazioni per garantire il comportamento previsto negli scenari comuni. I test CTS e quelli che utilizzano Jetpack WindowManager sono disponibili per gli OEM per testare le implementazioni.

Test CTS

Per eseguire i test CTS, vedi Eseguire i test CTS. I test CTS correlati a Jetpack WindowManager si trovano in cts/tests/framework/base/windowmanager/jetpack/. Il nome del modulo di test è CtsWindowManagerJetpackTestCases.

Test di WindowManager

Per scaricare i test di Jetpack WindowManager, segui le istruzioni di Android Jetpack. I test si trovano nella libreria delle finestre nel modulo window:window: window/window/src/androidTest/.

Per eseguire i test del dispositivo per il modulo window:window dalla riga di comando, procedi nel seguente modo:

1. Collega un dispositivo su cui sono attive le opzioni sviluppatore e il debug USB.
2. Consente al computer di eseguire il debug del dispositivo.
3. Apri una shell nella directory principale del repository androidx.
4. Passa alla directory framework/support.
5. Esegui questo comando: ./gradlew window:window:connectedAndroidTest.
6. Analizza i risultati.

Per eseguire i test da Android Studio:

1. Apri Android Studio.
2. Collega un dispositivo su cui sono attive le opzioni sviluppatore e il debug USB.
3. Consente al computer di eseguire il debug del dispositivo.
4. Vai a un test all'interno della libreria di finestre del modulo Finestra.
5. Apri una classe di test ed esegui il test utilizzando le frecce verdi sul lato destro dell'editor.

In alternativa, puoi creare una configurazione in Android Studio per eseguire un metodo di test, una classe di test o tutti i test in un modulo.

I risultati possono essere analizzati manualmente esaminando l'output della shell. Alcuni test vengono ignorati se il dispositivo non soddisfa determinati presupposti. I risultati vengono salvati in una posizione standard e gli analisti possono scrivere uno script per automatizzare l'analisi dei risultati.