Jetpack WindowManager: cos'è, libreria per dispositivi pieghevoli

Cos'è Jetpack WindowManager?

Jetpack WindowManager è una libreria della suite AndroidX che astrae il lavoro con finestre e configurazioni dello schermo su dispositivi Android. Risolve il problema della frammentazione degli schermi: dai telefoni compatti ai dispositivi pieghevoli e ai tablet con modalità desktop.

Prima di WindowManager, gli sviluppatori utilizzavano la vecchia API Display e Resources#getConfiguration, che non tenevano conto dei dispositivi pieghevoli e delle modalità multi-finestra. WindowManager fornisce un'API unificata per tutti gli scenari: una libreria copre FoldingFeature, WindowMetrics, WindowSizeClass e ScreenContinuity. Ciò riduce il codice boilerplate ed elimina i bug nell'adattamento dell'interfaccia a diversi dispositivi.

Secondo Google I/O 2024, Jetpack WindowManager versione stabile 1.3 include il supporto per sensori di cerniera, un'API per determinare l'angolo di apertura e un'integrazione migliorata con Jetpack Compose. La libreria è retrocompatibile fino ad Android 10 (API 29) tramite Support Library e si adatta automaticamente alle capacità del dispositivo.

FoldingFeature: lavorare con la piega del dispositivo

FoldingFeature è la classe centrale di Jetpack WindowManager per lavorare con dispositivi pieghevoli. Incapsula tutte le informazioni sulla posizione fisica della piega: stato (HALF_OPENED, FLAT, TABLE_TOP), orientamento (VERTICAL, HORIZONTAL), coordinate della cerniera e angolo di apertura in gradi.

Stati di FoldingFeature

La libreria definisce quattro stati di piega. STATE_FLAT — il dispositivo è completamente aperto, lo schermo è piatto. STATE_HALF_OPENED — il dispositivo è parzialmente piegato, lo schermo è a un angolo da 30 a 160 gradi. STATE_TABLE_TOP — il dispositivo è appoggiato su una superficie in posizione laptop. STATE_FULLY_OPENED — uno stato obsoleto, sostituito da FLAT nella versione 1.2.

Orientamento e coordinate della piega

La piega può essere verticale (VERTICAL_FOLD) o orizzontale (HORIZONTAL_FOLD). Bounds è un rettangolo che descrive l'area della piega nelle coordinate della finestra dell'applicazione. Lo sviluppatore utilizza questi dati per posizionare gli elementi dell'interfaccia sopra e sotto la piega, evitando la sovrapposizione del contenuto con l'area critica.

val windowManager = WindowManager(context)
val flow = windowManager.foldingFeature()

flow.collect { feature: FoldingFeature ->
    when (feature.state) {
        FoldingFeature.State.FLAT -> showFullScreen(feature.bounds)
        FoldingFeature.State.HALF_OPENED -> splitContentAcrossFold(feature.bounds)
        FoldingFeature.State.TABLE_TOP -> enableTouchpadMode()
    }
}

WindowMetrics e WindowSizeClass

WindowMetrics è un'API per ottenere dimensioni precise della finestra dell'applicazione, disponibile da WindowManager 1.0. A differenza di Display#getSize, WindowMetrics tiene conto della modalità multi-finestra, DeX e della finestra a forma libera. Le metriche restituiscono currentWindowMetrics (dimensione corrente) e maximumWindowMetrics (dimensione massima possibile sul dispositivo).

WindowSizeClass è un classificatore apparso in WindowManager 1.1. Divide gli schermi in tre categorie: Compact (larghezza inferiore a 600dp — telefono), Medium (600–840dp — tablet in orientamento verticale) e Expanded (oltre 840dp — tablet in orizzontale). Questa classe semplifica il layout adattivo sostituendo decine di controlli di dimensione con un'unica classificazione.

class MyComposable {
    @Composable
    fun AdaptiveLayout(windowSizeClass: WindowSizeClass) {
        when (windowSizeClass.widthSizeClass) {
            WindowWidthSizeClass.Compact -> CompactScreen()
            WindowWidthSizeClass.Expanded -> ExpandedScreen()
            else -> MediumScreen()
        }
    }
}

ScreenContinuityController e continuità dello schermo

ScreenContinuityController è un componente di WindowManager responsabile di preservare lo stato dell'Activity quando cambia la configurazione del dispositivo pieghevole. Quando l'utente apre o chiude il telefono, il controller notifica all'applicazione la nuova postura e fornisce meccanismi per una transizione fluida.

Il controller registra listener tramite registerContinuityListener, che accetta un callback con un oggetto FoldingFeature. A ogni cambio di postura, il callback viene attivato prima della ricreazione dell'Activity, dando allo sviluppatore l'opportunità di salvare manualmente lo stato. Se l'applicazione utilizza ViewModel, non è necessaria alcuna gestione aggiuntiva: i dati vengono salvati automaticamente.

ScreenContinuity in Jetpack Compose

Le applicazioni Compose beneficiano di ScreenContinuity tramite LocalWindowSizeClass e CompositionLocalProvider. I componenti si ricompongono automaticamente quando WindowMetrics cambiano. rememberSaveable preserva lo stato tra le ricomposizioni e Modifier.windowInsets tiene conto delle aree di sistema dello schermo.

val controller = WindowManager(context).screenContinuityController
controller.registerContinuityListener { feature ->
    if (feature.state == FoldingFeature.State.FLAT) {
        logContinuityEvent("Device unfolded")
    }
}

Esempi di integrazione in Kotlin

Consideriamo un esempio completo di un'Activity che utilizza Jetpack WindowManager per adattare l'interfaccia a diverse posture di un dispositivo pieghevole. WindowManagerActivity si sottoscrive ai cambiamenti di FoldingFeature tramite l'API Flow e passa tra layout a pannello singolo e doppio pannello.

class WindowManagerActivity : AppCompatActivity() {
    private lateinit var binding: ActivityWindowBinding

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = ActivityWindowBinding.inflate(layoutInflater)
        setContentView(binding.root)

        val windowManager = WindowManager(this)
        val metrics = windowManager.currentWindowMetrics

        if (metrics.bounds.width() > dpToPx(600)) {
            showDualPaneLayout()
        } else {
            showSinglePaneLayout()
        }
    }

    private fun showDualPaneLayout() {
        binding.content.layoutManager = GridLayoutManager(this, 2)
    }

    private fun showSinglePaneLayout() {
        binding.content.layoutManager = LinearLayoutManager(this)
    }
}

L'esempio mostra uno scenario di base: l'applicazione verifica WindowMetrics e seleziona un layout a pannello singolo o doppio pannello. Nei progetti reali, si consiglia di utilizzare WindowSizeClass per un adattamento più flessibile e FoldingFeature per gestire i dispositivi pieghevoli. La libreria supporta anche la transizione senza soluzione di continuità — animazione fluida durante il passaggio tra layout.

Test e debug di WindowManager

Android Studio include strumenti integrati per testare Jetpack WindowManager. L'emulatore supporta dispositivi pieghevoli (Pixel Fold, Galaxy Z Fold) con cambio di postura tramite la scheda Folding Postures. Layout Inspector mostra le WindowMetrics correnti e i confini di FoldingFeature in tempo reale.

Debug tramite ADB

Il comando adb shell dumpsys window displays mostra informazioni su tutti i display collegati e le loro configurazioni. Per simulare una piega, utilizzare adb shell am broadcast -a android.intent.action.SCREEN_ON con parametri di postura aggiuntivi. WindowManager registra tutte le modifiche di FoldingFeature tramite WindowManager#logState.

Errori comuni

I principali problemi di integrazione — ignorare gli aggiornamenti di WindowMetrics in modalità multi-finestra, gestione errata dei bounds con una piega verticale e mancanza di test su tutte le posture. Si consiglia di testare ogni postura separatamente e verificare il comportamento durante il passaggio dall'una all'altra. L'uso di WindowSizeClass invece di controlli manuali delle dimensioni riduce i bug del 60%.