Extensiones de WindowManager

La biblioteca de Jetpack WindowManager permite que los desarrolladores de aplicaciones admitan nuevos factores de forma de dispositivos y entornos multiventana.

Extensiones de WindowManager (Extensiones) es un módulo de plataforma de Android que habilita una variedad de funciones de Jetpack WindowManager. El módulo se implementa en AOSP en frameworks/base/libs/WindowManager/Jetpack y se envía en dispositivos que admiten las funciones de WindowManager.

Distribución del módulo de extensiones

Las extensiones se compilan en una biblioteca .jar y se colocan en la partición system_ext en un dispositivo si las extensiones están habilitadas en el archivo de configuración del dispositivo.

Para habilitar las extensiones en un dispositivo, agrega lo siguiente al archivo make del dispositivo del producto:

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

Esto habilita los paquetes androidx.window.extensions y androidx.window.sidecar en el dispositivo y establece la propiedad persist.wm.extensions.enabled. Si incluyes estos paquetes en el archivo makefile, también se colocarán declaraciones en etc/permissions/, lo que las pondrá a disposición de los procesos de la aplicación. Por lo general, los módulos se cargan y ejecutan como parte del proceso de la aplicación en el tiempo de ejecución cuando los usa la biblioteca de Jetpack WindowManager, lo que hace que su operación sea similar al código del framework del cliente, como se muestra en la siguiente imagen:

Figura 1: Extensiones de WindowManager cargadas en el proceso de la aplicación similar al código de la plataforma

El módulo androidx.window.extensions es el módulo de extensiones actual en desarrollo activo. El módulo androidx.window.sidecar es un módulo heredado que se incluye para la compatibilidad con las versiones más antiguas de Jetpack WindowManager, pero el Sidecar ya no se mantiene de forma activa.

En la siguiente figura, se muestra la lógica para determinar el uso de androidx.window.extensions o androidx.window.sidecar.

Figura 2: Árbol de decisión para acceder a androidx.window.extensions o androidx.window.sidecar.

Módulos de extensiones

Las extensiones proporcionan funciones de ventanas para dispositivos plegables con pantalla grande y dispositivos que admiten ventanas en pantallas externas. Entre las áreas de funciones, se incluyen las siguientes:

• Incorporación de actividades
• Información del diseño de la ventana
• Área de la ventana

Las implementaciones de OEM de extensiones pueden proporcionar componentes nulos o con implementaciones predeterminadas o de stub de los métodos en la interfaz WindowExtensions si el hardware del dispositivo no admite las funciones correspondientes, a menos que se solicite específicamente la función en el Documento de definición de compatibilidad (CDD) 7.1.1.1.

APIs de Extensions y Jetpack

El módulo de extensiones de WindowManager proporciona su propia plataforma de API, además de las APIs de plataforma públicas. El módulo Extensions se desarrolla de forma pública en una biblioteca de Jetpack androidx.window.extensions que no está orientada a los desarrolladores, de modo que Jetpack WindowManager (androidx.window) pueda vincularse con ella en el tiempo de compilación. Por lo general, la plataforma de la API de Extensions proporciona APIs de nivel inferior.

Las APIs que proporcionan las extensiones están diseñadas para que las use solo la biblioteca de WindowManager de Jetpack. Los desarrolladores de aplicaciones no deben llamar directamente a las APIs de Extensions. La biblioteca Extensions no se debe agregar como una dependencia para una aplicación en el archivo de compilación de Gradle para garantizar la funcionalidad correcta. Evita compilar previamente la biblioteca de extensiones en una aplicación directamente. En su lugar, confía en la carga del entorno de ejecución para evitar el caso de cargar una combinación de clases de extensiones precompiladas y proporcionadas por el entorno de ejecución.

Jetpack WindowManager (androidx.window) se debe agregar como dependencia de la aplicación y proporciona las APIs públicas para desarrolladores, incluidas las de las funciones de WindowManager Extensions. La biblioteca de WindowManager carga Extensiones automáticamente en el proceso de la aplicación y une las APIs de Extensiones de nivel inferior en abstracciones de nivel superior y en interfaces más enfocadas. Las APIs de WindowManager de Jetpack siguen los estándares del desarrollo moderno de aplicaciones para Android y están diseñadas para proporcionar una interoperabilidad conveniente, ya que se integran bien con bases de código que usan otras bibliotecas de AndroidX.

Versiones y actualizaciones de extensiones

El módulo Extensions se puede actualizar junto con las actualizaciones anuales o trimestrales de la plataforma de Android. Las actualizaciones trimestrales permiten que el nivel de la API de Extensions aumente entre las actualizaciones de la API de la plataforma de Android, lo que permite una iteración más rápida y brinda a los OEMs la oportunidad de agregar acceso oficial a la API a funciones nuevas cerca de los lanzamientos de hardware.

En la siguiente tabla, se muestran las versiones de la API de androidx.window.extensions para varias versiones de Android.

Versión de la plataforma de Android	Nivel de API de WindowManager Extensions	Versión de la API de androidx.window.extensions
Android 15	6	1.5.0 (próximamente)
QPR3 para Android 14	5	1.4.0 (próximamente)
QPR1 para Android 14	4	1.3.0
Android 14	3	1.2.0
QPR3 para Android 13	2	1.1.0
Android 13	1	1.0.0
Android 12L	1	1.0.0

El nivel de API de Extensions (columna central) aumenta cada vez que se agrega algo a la plataforma de API estable existente (columna derecha).

Nota: Los OEM no están obligados a admitir actualizaciones de QPR, pero deben coordinar la versión de la plataforma y el nivel de API de Extensions de la siguiente manera:

• Cualquier versión de software de plataforma base que envíen los OEMs debe tener al menos la misma versión de extensiones que se define en la tabla.
• Puedes enviar una versión anterior de la plataforma con una versión más reciente de las extensiones, pero, por lo general, la implementación también requiere modificaciones extensas en el núcleo de WindowManager para admitir la funcionalidad.
• Las implementaciones que incluyen una versión anterior de la plataforma y una versión más reciente de las extensiones deben aprobar el conjunto de pruebas de compatibilidad (CTS) correspondiente para las extensiones más recientes. La implementación no obtiene una verificación automática a través de las pruebas de CTS para la versión anterior correspondiente de la plataforma.

Compatibilidad con versiones anteriores y posteriores

Jetpack WindowManager controla la complejidad de lidiar con actualizaciones frecuentes del nivel de API, una evolución rápida de la API y la retrocompatibilidad. Cuando se ejecuta el código de la biblioteca en el proceso de la aplicación, esta verifica el nivel de API de Extensions declarado y proporciona acceso a las funciones según el nivel declarado.

Para evitar que una aplicación falle durante el tiempo de ejecución, WindowManager también realiza una verificación de reflexión de Java en el tiempo de ejecución de las APIs de Extensions disponibles según el nivel de API de Extensions declarado. Si hay una discrepancia, WindowManager puede inhabilitar el uso de extensiones (parcial o completamente) y, además, informar que las funciones relevantes no están disponibles para la aplicación.

Las extensiones de WindowManager se implementan como un módulo system_ext que usa APIs de plataforma privadas para llamar al núcleo de WindowManager, DeviceStateManager y otros servicios del sistema en la implementación de las funciones de Extensiones.

Es posible que no se mantenga la compatibilidad con las versiones previas al lanzamiento de las extensiones antes del lanzamiento trimestral o anual correspondiente de la plataforma de Android con el que se finalizan las versiones. El historial completo de las APIs de Extensions se puede encontrar en los archivos de texto de la API de window:extensions:extensions de la rama de lanzamiento.

Las versiones más recientes de Extensions deben seguir funcionando con versiones anteriores de WindowManager compiladas en aplicaciones para mantener la retrocompatibilidad. Para asegurarnos de esto, cualquier versión nueva de la API de Extensions solo agrega APIs nuevas y no quita las anteriores. Como resultado, las aplicaciones con versiones anteriores de WindowManager pueden seguir usando las APIs de Extensions más antiguas con las que se compilaron las apps.

La verificación de CTS garantiza que, para cualquier versión declarada de las APIs de Extensions en el dispositivo, todas las APIs de esa versión y las anteriores estén presentes y sean funcionales.

Rendimiento

El módulo Extensions se almacena en caché en los cargadores de clases del sistema que no son de bootclasspath de forma predeterminada a partir de Android 14 (nivel de API 34), por lo que no hay un impacto en el rendimiento debido a la carga del módulo en la memoria al inicio de la app. El uso de funciones de módulos individuales puede tener una ligera influencia en las características de rendimiento de las apps cuando se realizan llamadas adicionales de IPC entre el cliente y el servidor.

Módulos

Incorporación de actividades

El componente de incorporación de actividades permite que las aplicaciones optimicen su IU para dispositivos de pantalla grande y pantallas externas. La incorporación de actividades permite presentar dos actividades en paralelo en un diseño de varios paneles, lo que facilita el desarrollo de apps adaptables para aplicaciones heredadas.

El componente de incorporación de actividades debe estar disponible en todos los dispositivos que tengan una pantalla integrada igual o superior a sw600dp. La incorporación de actividades también debe estar habilitada en dispositivos que admitan conexiones de pantallas externas, ya que la aplicación podría mostrarse en un tamaño más grande cuando se conecten pantallas externas durante el tiempo de ejecución.

Nota: Algunos OEMs fuerzan a las apps a incorporar actividades definidas por el sistema. Las apps pueden evitar la incorporación de actividades definidas por el sistema configurando PROPERTY_ACTIVITY_EMBEDDING_ALLOW_SYSTEM_OVERRIDE en el archivo de manifiesto de la app. Si una app configuró la propiedad como false, el sistema no debe forzar a la app a la incorporación de actividades definida por el sistema.

Configuración del dispositivo

No es necesario realizar ninguna configuración específica del dispositivo, excepto habilitar el módulo Extensions, como se describe en la sección Distribución del módulo Extensions. Tiene sentido habilitar las extensiones en todos los dispositivos que admiten el modo multiventana. Es probable que las versiones futuras de Android requieran extensiones en configuraciones comunes de dispositivos de mano y de pantalla grande.

Información del diseño de la ventana

El componente de información de diseño de ventana identifica la posición y el estado de la bisagra en un dispositivo plegable cuando esta cruza una ventana de la aplicación. La información del diseño de la ventana permite que las aplicaciones respondan y muestren diseños optimizados en el modo de mesa en dispositivos plegables. Consulta Cómo hacer que tu app funcione en dispositivos plegables para obtener detalles sobre el uso.

Los dispositivos Android plegables que incluyen una bisagra que conecta áreas de paneles de pantalla separadas o continuas deben poner la información sobre la bisagra a disposición de las aplicaciones a través de WindowLayoutComponent.

La posición y los límites de la bisagra se deben informar en relación con la ventana de la aplicación que identifica un Context que se pasa a la API. Si los límites de la ventana de la aplicación no se cruzan con los límites de la bisagra, no se debe informar la bisagra DisplayFeature. También se acepta no informar las funciones de visualización cuando su posición no se pueda informar de forma confiable, por ejemplo, cuando el usuario puede mover libremente una ventana de la aplicación en el modo multiventana o en el modo letterbox de compatibilidad.

En el caso de las funciones de plegado, las actualizaciones de estado se deben informar cuando la posición de la bisagra cambia entre los estados estables. De forma predeterminada, en un estado de visualización plano, la API debe informar FoldingFeature.State.FLAT. Si el hardware del dispositivo se puede dejar en un modo medio plegado en un estado estable, la API debe informar FoldingFeature.State.HALF_OPENED. No hay un estado cerrado en la API, ya que, en ese caso, la ventana de la aplicación no sería visible o no cruzaría los límites de la bisagra.

Configuración del dispositivo

Para admitir la implementación de la función de plegado, los OEMs deben hacer lo siguiente:

• Configura los estados del dispositivo en device_state_configuration.xml para que los use DeviceStateManagerService. Consulta DeviceStateProviderImpl.java como referencia.

  Si las implementaciones predeterminadas de DeviceStateProvider o DeviceStatePolicy no son adecuadas para el dispositivo, se puede usar una implementación personalizada.

• Habilita el módulo Extensions como se describe en la sección Distribución del módulo Extensions.

• Especifica la ubicación de las funciones de visualización en el recurso de cadena com.android.internal.R.string.config_display_features (por lo general, en frameworks/base/core/res/res/values/config.xml en la superposición del dispositivo).

  El formato esperado para la cadena es el siguiente:

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

  type puede ser fold o hinge. Los valores de left, top, right y bottom son coordenadas de píxeles enteros en el espacio de coordenadas de la pantalla en la orientación natural de la pantalla. La cadena de configuración puede contener varias funciones de visualización separadas por punto y coma.

  Por ejemplo:

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

• Define la asignación entre los identificadores de estado interno del dispositivo que se usan en DeviceStateManager y las constantes de estado públicas que se envían a los desarrolladores en com.android.internal.R.array.config_device_state_postures.

  El formato esperado para cada entrada es el siguiente:

  <device_specific_state_identifier>:<Jetpack WindowManager state identifier>

  Los identificadores de estado admitidos son los siguientes:

  • COMMON_STATE_NO_FOLDING_FEATURES = 1: El estado no tiene funciones de plegado para informar. Por ejemplo, puede ser el estado cerrado del dispositivo plegable típico con la pantalla principal en el lado interior.
  • COMMON_STATE_HALF_OPENED = 2: La función de plegado está medio abierta.
  • COMMON_STATE_FLAT = 3: La función de plegado es plana. Por ejemplo, puede ser el estado abierto del dispositivo plegable típico con la pantalla principal en el lado interno.
  • COMMON_STATE_USE_BASE_STATE = 1000: En Android 14, es un valor que se puede usar para estados emulados en los que el estado de bisagra se deriva con el estado base, como se define en CommonFoldingFeature.java.

  Consulta DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int) para obtener más información.

  Por ejemplo:

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

Área de la ventana

El componente del área de la ventana proporciona un conjunto de funciones que les brindan a las aplicaciones acceso a pantallas y áreas de visualización adicionales en algunos dispositivos plegables y multipantalla.

El modo de pantalla posterior permite que una aplicación muestre la IU de vista previa de la cámara en la pantalla de la cubierta de un dispositivo plegable para permitir el uso de la cámara principal del dispositivo para tomar selfies y videos. Los dispositivos que tienen una cubierta de pantalla compatible con Android (según se define en el CDD de Android en términos de atributos como el tamaño, la densidad y los indicadores de navegación disponibles) que se alinea con las cámaras posteriores del dispositivo deben proporcionar acceso al modo de pantalla posterior.

En Android 14, el modo Dual Screen permite que las aplicaciones que se ejecutan en la pantalla interior de un dispositivo plegable muestren contenido adicional en la pantalla de la cubierta que se orienta a otros usuarios. Por ejemplo, la pantalla de la cubierta puede mostrar la vista previa de la cámara a la persona que se está fotografiando o grabando.

Configuración del dispositivo

Para admitir la implementación de la función de plegado, los OEMs deben hacer lo siguiente:

• Configura los estados del dispositivo en device_state_configuration.xml para que los use DeviceStateManagerService. Consulta DeviceStateProviderImpl.java para obtener más información.

  Si la implementación predeterminada de DeviceStateProvider o DeviceStatePolicy no es adecuada para el dispositivo, se puede usar una implementación personalizada.

• Para dispositivos plegables que admiten el modo abierto o plano, especifica los identificadores de estado correspondientes en com.android.internal.R.array.config_openDeviceStates.

• En el caso de los dispositivos plegables que admiten estados plegados, enumera los identificadores de estado correspondientes en com.android.internal.R.array.config_foldedDeviceStates.

• En el caso de los dispositivos plegables que admiten un estado medio plegado (la bisagra está medio abierta como una laptop), enumera los estados correspondientes en com.android.internal.R.array.config_halfFoldedDeviceStates.

• Para dispositivos que admiten el modo de pantalla posterior:

  • Enumera los estados correspondientes en com.android.internal.R.array.config_rearDisplayDeviceStates para DeviceStateManager.
  • Especifica la dirección física de la pantalla posterior en com.android.internal.R.string.config_rearDisplayPhysicalAddress.
  • Especifica el identificador de estado en com.android.internal.R.integer.config_deviceStateRearDisplay que usarán las extensiones.
  • Agrega el identificador de estado en com.android.internal.R.array.config_deviceStatesAvailableForAppRequests para que esté disponible para las aplicaciones.

• En Android 14, para dispositivos que admiten el modo de pantalla doble (simultáneo), haz lo siguiente:

  • Establece com.android.internal.R.bool.config_supportsConcurrentInternalDisplays como true.
  • Especifica la dirección física de la pantalla posterior en com.android.internal.R.config_deviceStateConcurrentRearDisplay.
  • Especifica el identificador de estado en com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay que usarán las extensiones si el identificador está destinado a estar disponible para las aplicaciones.
  • Agrega el identificador de estado en com.android.internal.R.array.config_deviceStatesAvailableForAppRequests para que esté disponible para las aplicaciones.

Verificación

Los OEMs deben verificar sus implementaciones para garantizar el comportamiento esperado en situaciones comunes. Las pruebas de CTS y las que usan Jetpack WindowManager están disponibles para los OEMs para probar implementaciones.

Pruebas de CTS

Para ejecutar las pruebas de CTS, consulta Cómo ejecutar pruebas de CTS. Las pruebas de CTS relacionadas con Jetpack WindowManager se encuentran en cts/tests/framework/base/windowmanager/jetpack/. El nombre del módulo de prueba es CtsWindowManagerJetpackTestCases.

Pruebas de WindowManager

Para descargar las pruebas de Jetpack WindowManager, sigue las instrucciones de Android Jetpack. Las pruebas se encuentran en la biblioteca de ventanas, en el módulo window:window: window/window/src/androidTest/.

Para ejecutar las pruebas de dispositivos del módulo window:window desde la línea de comandos, haz lo siguiente:

1. Conecta un dispositivo que tenga habilitadas las opciones para desarrolladores y la depuración por USB.
2. Permite que la computadora depure el dispositivo.
3. Abre una shell en el directorio raíz del repositorio de androidx.
4. Cambia el directorio a framework/support.
5. Ejecuta el siguiente comando: ./gradlew window:window:connectedAndroidTest.
6. Analiza los resultados.

Para ejecutar las pruebas desde Android Studio, haz lo siguiente:

1. Abre Android Studio.
2. Conecta un dispositivo que tenga habilitadas las opciones para desarrolladores y la depuración por USB.
3. Permite que la computadora depure el dispositivo.
4. Navega a una prueba dentro de la biblioteca de ventanas del módulo de ventanas.
5. Abre una clase de prueba y ejecútala con las flechas verdes que se encuentran en el lado derecho del editor.

Como alternativa, puedes crear una configuración en Android Studio para ejecutar un método de prueba, una clase de prueba o todas las pruebas de un módulo.

Los resultados se pueden analizar de forma manual si se observa el resultado de la shell. Se omiten algunas pruebas si el dispositivo no cumple con ciertas suposiciones. Los resultados se guardan en una ubicación estándar, y los analistas pueden escribir una secuencia de comandos para automatizar el análisis de los resultados.