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 (Extensions) è 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 posizionate nella partizione system_ext su un dispositivo se le estensioni sono attivate nel makefile del dispositivo.

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

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

Questa operazione attiva i pacchetti androidx.window.extensions e androidx.window.sidecar sul dispositivo e imposta la proprietà persist.wm.extensions.enabled. Se includi questi pacchetti nel makefile, le dichiarazioni vengono inserite anche in etc/permissions/, rendendole disponibili ai processi dell'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 a quello del codice del framework lato client, come mostrato nella figura seguente:

Figura 1. Estensioni WindowManager caricate nell'applicazione processo simile al codice di 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 androidx.window.extensions o androidx.window.sidecar.

Moduli di estensioni

Le estensioni offrono funzionalità di windowing per i dispositivi pieghevoli con schermo di grandi dimensioni e per i dispositivi che supportano il windowing su display esterni. Le aree di funzionalità includono:

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 la propria superficie API oltre alle API della piattaforma pubblica. Il modulo Estensioni è sviluppato pubblicamente in una libreria androidx.window.extensions Jetpack non rivolta agli sviluppatori, in modo che Jetpack WindowManager (androidx.window) possa collegarsi al modulo al momento della compilazione. 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. Per garantire la corretta funzionalità, la libreria Extensions non deve essere aggiunta come dipendenza per un'applicazione nel file di build Gradle. Evita di precompilare direttamente la libreria delle estensioni in un'applicazione; utilizza invece il caricamento del runtime per evitare il caricamento di una combinazione di classi di Extensions precompilate e fornite dal 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à pratica 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 gli aggiornamenti delle API della piattaforma Android, consentendo un'iterazione più rapida e offrendo agli OEM l'opportunità di aggiungere l'accesso API ufficiale alle nuove funzionalità in prossimità del lancio di hardware.

Nella tabella seguente sono elencate 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)
QPR1 per Android 14 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 aggiunta alla superficie API stabile esistente (colonna destra).

Compatibilità con le versioni precedenti e successive

Jetpack WindowManager gestisce la complessità di gestire aggiornamenti frequenti a livello di API, evoluzione rapida delle 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 dagli arresti anomali in fase di runtime, WindowManager esegue anche un controllo della riflessione Java di runtime 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 di WindowManager sono implementate come modulo system_ext che utilizza API di piattaforma private per chiamare il core di WindowManager, DeviceStateManager e altri servizi di sistema nell'implementazione delle funzionalità di Estensioni.

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

Le versioni più recenti delle estensioni devono continuare a funzionare con le versioni precedenti di WindowManager compilate in applicazioni per mantenere la compatibilità in avanti. A questo scopo, ogni 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 su cui le app erano 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 ha alcun impatto sulle prestazioni. 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 Inserimento di attività fornisce un insieme di funzionalità che consentono alle applicazioni di organizzare la presentazione della finestra dell'attività nei limiti dell'applicazione principale. Ciò include la visualizzazione di due attività contemporaneamente affiancate in un layout a più riquadri, facilitando l'ottimizzazione per schermi di grandi dimensioni per le applicazioni legacy.

Il componente di incorporamento delle attività deve essere disponibile su tutti i dispositivi con un display integrato di dimensioni uguali o superiori a sw600 dp. L'incorporamento delle attività deve essere abilitato 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 connessi in fase di runtime.

Configurazione dispositivo

Non è necessaria alcuna configurazione specifica del dispositivo, tranne 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à multi-finestra. È probabile che le future versioni di Android renderanno necessarie le estensioni nelle configurazioni comuni di dispositivi portatili e con schermi di grandi dimensioni.

Informazioni sulla disposizione delle finestre

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 i dettagli sull'utilizzo, vedi Rendere la tua app sensibile.

I dispositivi Android pieghevoli che includono una cerniera che collega aree del display separate o continua devono rendere le informazioni sulla cerniera disponibili per le 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 stato di visualizzazione fissa, 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. Non esiste uno stato chiuso nell'API, 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. Consulta la pagina DeviceStateProviderImpl.java come riferimento.

    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 di left, top, right e bottom sono coordinate di pixel interi nello spazio delle coordinate del display nell'orientamento naturale del display. La stringa di configurazione può contenere più caratteristiche di visualizzazione separate da punti e virgola.

    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 di stato dei dispositivi 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 caratteristiche pieghevoli da segnalare. Ad esempio, può essere lo stato chiuso di un tipico dispositivo in-fold con la schermata principale sul lato interno.
    • COMMON_STATE_HALF_OPENED = 2: la funzionalità di piegatura è aperta a metà.
    • COMMON_STATE_FLAT = 3: la funzionalità di chiusura è piatta. Ad esempio, può essere lo stato aperto di un tipico dispositivo ripiegato con la schermata 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 cerniera viene derivato utilizzando lo stato base, come definito in CommonFoldingFeature.java

    Per ulteriori informazioni, visita la pagina 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 di anteprima della fotocamera sul display di copertina di un dispositivo pieghevole per consentire l'utilizzo della fotocamera principale del dispositivo per selfie e video. I dispositivi con un display compatibile con Android (come definito dalla CDD di Android in termini di attributi quali dimensioni, densità e condizioni di navigazione disponibili) coprono un display in linea con le fotocamere posteriori del dispositivo, devono fornire l'accesso alla modalità di visualizzazione posteriore.

Su Android 14, la modalità Dual Screen consente alle applicazioni eseguite sul display interno di un dispositivo pieghevole di mostrare contenuti aggiuntivi sul display della copertina rivolti ad altri utenti. Ad esempio, il display della copertina 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 maggiori informazioni, consulta DeviceStateProviderImpl.java.

    Se l'implementazione predefinita di DeviceStateProvider o DeviceStatePolicy non è adatta per il dispositivo, è possibile usare un'implementazione personalizzata.

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

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

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

  • Per i dispositivi che supportano la modalità schermo 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 dello stato in com.android.internal.R.integer.config_deviceStateRearDisplay che deve essere utilizzato dalle 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à di visualizzazione doppia (simultanea):

    • 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 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 implementazioni per garantire il comportamento previsto in 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 relativi a Jetpack WindowManager sono 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 per 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:

  1. Collega un dispositivo con opzioni sviluppatore e debug USB attivato.
  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 opzioni sviluppatore e debug USB attivato.
  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 una classe di test ed eseguila 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 automatizzarne l'analisi.