Estensioni WindowManager

La libreria Jetpack WindowManager consente agli sviluppatori di applicazioni di supportare nuovi fattori di forma dei dispositivi e ambienti con più finestre.

WindowManager Extensions (Estensioni) è un modulo della piattaforma Android che richiede l'attivazione e consente una serie di funzionalità di WindowManager di Jetpack. 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 Estensioni

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

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

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

In questo modo 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 file make inserisce anche le dichiarazioni in etc/permissions/, rendendole disponibili per i processi di applicazione. In genere, i moduli vengono caricati ed eseguiti nell'ambito del processo di applicazione in fase di esecuzione quando vengono utilizzati dalla libreria WindowManager di Jetpack, il che rende il loro 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 di estensioni

Le estensioni forniscono funzionalità di visualizzazione a schermo diviso per dispositivi pieghevoli con schermi di grandi dimensioni e per dispositivi che supportano la visualizzazione a schermo diviso su display esterni. Le aree di 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 richiesta specificamente nel Documento di definizione della compatibilità (CDD) 7.1.1.1.

Estensioni e API Jetpack

Il modulo Estensioni WindowManager fornisce una propria API oltre alle API della piattaforma pubblica. Il modulo Estensioni viene sviluppato pubblicamente in una libreria Jetpack rivolta non agli sviluppatori, in modo che Jetpack WindowManager (androidx.window) possa eseguirne il collegamento in fase di compilazione.androidx.window.extensions In genere, l'interfaccia API Extensions fornisce API di livello inferiore.

Le API fornite da Estensioni sono destinate a essere utilizzate solo dalla libreria WindowManager di Jetpack. Le API Extensions non sono progettate per essere richiamate direttamente dagli sviluppatori di applicazioni. La libreria Extensions non deve essere aggiunta come dipendenza per un'applicazione nel file di compilazione Gradle per garantire il corretto funzionamento. Evita di compilare in anticipo la libreria Extensions direttamente in un'applicazione. Utilizza invece il caricamento in fase di runtime per evitare di caricare una combinazione 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à di WindowManager Extensions. La libreria WindowManager carica automaticamente le estensioni nel processo dell'applicazione e racchiude le API di estensioni di livello inferiore in astrazioni di livello superiore e interfacce più mirate. Le API WindowManager Jetpack rispettano gli standard di sviluppo delle applicazioni Android moderne e sono progettate per offrire un'interoperabilità comoda integrandosi bene con le basi di codice che utilizzano altre librerie AndroidX.

Versioni e aggiornamenti delle estensioni

Il modulo Estensioni può essere aggiornato insieme agli aggiornamenti annuali o trimestrali della piattaforma Android. Gli aggiornamenti trimestrali consentono di aumentare il livello dell'API Extensions tra un aggiornamento dell'API della piattaforma Android e l'altro, 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 diverse 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 dell'API Extensions (colonna centrale) viene aumentato ogni volta che viene eseguita un'aggiunzione all'interfaccia 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 come segue:

• Qualsiasi versione software della piattaforma di base fornita dagli OEM deve avere almeno la stessa versione di Estensioni definita nella tabella.
• Puoi distribuire una versione precedente della piattaforma con una versione più recente di Extension, ma in genere l'implementazione richiede anche modifiche sostanziali al nucleo 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 precedente della piattaforma corrispondente.

Compatibilità con le versioni precedenti e successive

Jetpack WindowManager gestisce la complessità di gestire aggiornamenti frequenti a livello di API, evoluzione rapida dell'API e compatibilità con le versioni precedenti. Quando il codice della libreria viene eseguito nella procedura di applicazione, la libreria controlla il livello dell'API Extensions dichiarato 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 riflessione 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'uso delle estensioni (parzialmente o completamente) e segnalare le funzionalità pertinenti come non disponibili per l'applicazione.

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

La compatibilità potrebbe non essere mantenuta con le versioni pre-release di Estensioni prima della corrispondente release trimestrale o annuale della piattaforma Android con la quale le versioni vengono finalizzate. La cronologia completa delle API di Estensioni è disponibile nel ramo di rilascio dei window:extensions:extensions file di testo dell'API.

Per mantenere la compatibilità con le versioni successive, le versioni più recenti di Estensioni devono continuare a funzionare con le versioni precedenti di WindowManager compilate nelle applicazioni. Per garantirlo, 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 di Estensioni sul dispositivo, tutte le API per quella versione e le versioni 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), pertanto il caricamento del modulo in memoria all'avvio dell'app non influisce sul rendimento. L'utilizzo delle funzionalità dei singoli moduli potrebbe avere una lieve influenza sulle caratteristiche di prestazioni delle app quando vengono eseguite chiamate IPC aggiuntive tra il client e il server.

Moduli

Incorporamento delle attività

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

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

Nota: alcuni OEM forzano le app a eseguire l'inserimento di attività predefinite dal sistema. Le app possono impedire l'inserimento di attività predefinite 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'app a eseguire l'inserimento di attività definito dal sistema.

Configurazione dispositivo

Non è necessaria alcuna configurazione specifica del dispositivo, a parte l'attivazione del modulo Estensioni come descritto nella sezione Distribuzione del modulo Estensioni. Ha senso attivare le estensioni su tutti i dispositivi che supportano la modalità a più finestre. È probabile che le versioni future di Android rendano obbligatorie le Estensioni nelle configurazioni comuni dei dispositivi con schermo grande e palmare.

Informazioni sul layout della finestra

Il componente di 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à da tavolo sui dispositivi pieghevoli. Per informazioni dettagliate sull'utilizzo, consulta Rendere l'app consapevole della 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 riportati in base 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 registrata. È anche 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 chiusura, gli aggiornamenti dello stato devono essere registrati quando la posizione della cerniera cambia tra gli stati stabili. Per impostazione predefinita, in uno stato di visualizzazione piatto, l'API deve segnalare FoldingFeature.State.FLAT. Se l'hardware del dispositivo può essere lasciato in modalità semichiusa in uno stato stabile, l'API deve segnalare FoldingFeature.State.HALF_OPENED. L'API non prevede uno stato chiuso, poiché in questo caso la finestra dell'applicazione non sarebbe visibile o non supererebbe 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 da DeviceStateManagerService. Per riferimento futuro, 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>]

  type può essere fold o hinge. I valori per left, top, right e bottom sono coordinate intere dei pixel 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 interno utilizzati in DeviceStateManager e le costanti di stato pubblico 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 simulati in cui lo stato della cerniera viene dedotto utilizzando lo stato di base, come definito in CommonFoldingFeature.java

  Per maggiori informazioni, 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 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à di visualizzazione posteriore consente a un'applicazione di mostrare l'interfaccia utente dell'anteprima della fotocamera sul display del coperchio di un dispositivo pieghevole per consentire l'utilizzo della fotocamera del dispositivo principale per selfie e video. I dispositivi con un display anteriore compatibile con Android (come definito dal CDD di Android in termini di attributi come dimensioni, densità e funzionalità di navigazione disponibili) che si allinea alle fotocamere posteriori del dispositivo devono fornire l'accesso alla modalità di visualizzazione 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 esterno rivolto verso gli altri utenti. Ad esempio, il display esterno 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 da DeviceStateManagerService. Per ulteriori informazioni, 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 a libro, specifica gli identificativi di stato corrispondenti incom.android.internal.R.array.config_openDeviceStates.

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

• Per i dispositivi con cerniera che supportano uno stato a metà (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à di visualizzazione posteriore:

  • Elenca gli stati corrispondenti in com.android.internal.R.array.config_rearDisplayDeviceStates per DeviceStateManager.
  • Specifica l'indirizzo fisico del display posteriore in com.android.internal.R.string.config_rearDisplayPhysicalAddress.
  • Specifica l'identificatore dello stato in com.android.internal.R.integer.config_deviceStateRearDisplay da essere utilizzato dalle Estensioni.
  • Aggiungi l'identificatore dello stato in com.android.internal.R.array.config_deviceStatesAvailableForAppRequests per renderlo disponibile alle applicazioni.

• Su Android 14, per i dispositivi che supportano la modalità di visualizzazione duale (contemporanea):

  • Imposta com.android.internal.R.bool.config_supportsConcurrentInternalDisplays sutrue.
  • Specifica l'indirizzo fisico del display posteriore in com.android.internal.R.config_deviceStateConcurrentRearDisplay.
  • Specifica l'identificatore dello 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 dello 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 i test che utilizzano Jetpack WindowManager sono disponibili per gli OEM per testare le implementazioni.

Test CTS

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

Test di WindowManager

Per scaricare i test di WindowManager di Jetpack, segui le istruzioni di Android Jetpack. I test si trovano nella raccolta 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, svolgi i seguenti passaggi:

1. Collega un dispositivo con le opzioni sviluppatore e il debug USB abilitati.
2. Consenti al computer di eseguire il debug del dispositivo.
3. Apri una shell nella directory principale del repository androidx.
4. Cambia la directory in framework/support.
5. Esegui il seguente comando: ./gradlew window:window:connectedAndroidTest.
6. Analizza i risultati.

Per eseguire i test da Android Studio:

1. Apri Android Studio.
2. Collega un dispositivo con le opzioni sviluppatore e il debug USB abilitati.
3. Consenti al computer di eseguire il debug del dispositivo.
4. Vai a un test all'interno della libreria di finestre del modulo della finestra.
5. Apri un test class ed eseguilo 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 di un modulo.

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