Extensiones de WindowManager

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

WindowManager Extensions (Extensiones) es un módulo de la plataforma de Android que se puede habilitar y que permite una variedad de funciones de Jetpack WindowManager. El módulo se implementa en AOSP en frameworks/base/libs/WindowManager/Jetpack y se incluye en los 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 de un dispositivo si las extensiones están habilitadas en el archivo make del dispositivo.

Para habilitar las extensiones en un dispositivo, agrega lo siguiente al archivo make 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. Incluir estos paquetes en el archivo makefile también coloca declaraciones en etc/permissions/, lo que las pone a disposición de los procesos de la aplicación. Normalmente, 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 figura:

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 primeras versiones 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.

Módulos de extensiones

Las extensiones proporcionan funciones de ventanas para dispositivos plegables con pantalla grande y dispositivos que admiten ventanas en pantallas externas. Las áreas de funciones incluyen lo siguiente:

• 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 componentes con implementaciones predeterminadas o de código auxiliar de los métodos en la interfaz WindowExtensions si el hardware del dispositivo no admite las funciones correspondientes, a menos que la función se solicite específicamente en el Documento de Definición de Compatibilidad (CDD) 7.1.1.1.

APIs de extensiones y Jetpack

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

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

Jetpack WindowManager (androidx.window) se debe agregar como una dependencia de la aplicación y proporciona las APIs públicas orientadas al desarrollador, incluidas las de las funciones de WindowManager Extensions. La biblioteca de WindowManager carga automáticamente las extensiones en el proceso de la aplicación y encapsula 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 integrándose bien con las bases de código que usan otras bibliotecas de AndroidX.

Versiones y actualizaciones de extensiones

El módulo de Extensions se puede actualizar junto con las actualizaciones anuales o trimestrales de la plataforma de Android. Las actualizaciones trimestrales permiten aumentar el nivel de la API de Extensions 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 OEM la oportunidad de agregar acceso oficial a la API para nuevas funciones cerca de los lanzamientos de hardware.

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

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

Compatibilidad con versiones anteriores y posteriores

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

Para proteger una aplicación de fallas durante el tiempo de ejecución, WindowManager también realiza una verificación de reflexión de Java en 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 marcar las funciones pertinentes como no disponibles para la aplicación.

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

Es posible que no se mantenga la compatibilidad con las versiones previas al lanzamiento de 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 Extensiones se puede encontrar en los archivos de texto de la API de window:extensions:extensions de la rama de versiones.

Las versiones más recientes de Extensions deben seguir funcionando con las versiones anteriores de WindowManager compiladas en las aplicaciones para mantener la compatibilidad con versiones posteriores. Para garantizar 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 anteriores con las que se compilaron las apps.

La verificación del 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

De forma predeterminada, el módulo Extensions se almacena en caché en los cargadores de clases del sistema que no son de bootclasspath a partir de Android 14 (nivel de API 34), por lo que no hay 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 podría influir ligeramente en las características de rendimiento de las apps cuando se realizan llamadas IPC adicionales 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 con pantallas grandes 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 habilitarse en los dispositivos que admiten conexiones de pantallas externas, ya que la aplicación podría mostrarse en un tamaño más grande cuando se conectan pantallas externas en el tiempo de ejecución.

Configuración del dispositivo

No es necesaria ninguna configuración específica del dispositivo, más allá de habilitar el módulo de Extensiones, como se describe en la sección Distribución del módulo de Extensiones. Es conveniente habilitar las extensiones en todos los dispositivos que admiten el modo multiventana. Es probable que las versiones futuras de Android requieran extensiones en las configuraciones comunes de dispositivos portátiles y de pantalla grande.

Información del diseño de la ventana

El componente de información de diseño de la ventana identifica la posición y el estado de la bisagra en un dispositivo plegable cuando la bisagra 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 panel 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 identificada por un Context que se pasa a la API. Si los límites de la ventana de la aplicación no se intersecan con los límites de la bisagra, no se debe informar la bisagra DisplayFeature. También es aceptable no informar las funciones de pantalla cuando su posición no se pueda informar de manera confiable, como cuando el usuario puede mover libremente la ventana de una aplicación en el modo multiventana o en el modo de compatibilidad letterboxing.

En el caso de las funciones de plegado, los cambios 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 plana, la API debe informar FoldingFeature.State.FLAT. Si el hardware del dispositivo se puede dejar en modo plegado a la mitad 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 estarí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 OEM deben hacer lo siguiente:

• Configura los estados del dispositivo en device_state_configuration.xml para que los use DeviceStateManagerService. Consulta DeviceStateProviderImpl.java para obtener información de 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 de Extensiones como se describe en la sección Distribución del módulo de Extensiones.

• Especifica la ubicación de las funciones de pantalla 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>]

  El 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 está 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 la bisagra se deriva del 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 de área de ventana proporciona un conjunto de funciones que les dan a las aplicaciones acceso a pantallas y áreas de visualización adicionales en algunos dispositivos plegables y con varias pantallas.

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 selfies y videos. Los dispositivos que tienen una pantalla de cubierta compatible con Android (según se define en el CDD de Android en términos de atributos como tamaño, densidad y recursos de navegación disponibles) que se alinea con las cámaras traseras del dispositivo deben proporcionar acceso al modo de pantalla trasera.

En Android 14, el modo de pantalla doble permite que las aplicaciones que se ejecutan en la pantalla interior de un dispositivo plegable muestren contenido adicional en la pantalla de la cubierta orientada hacia 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 OEM 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.

• En el caso de los 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 hacia adentro 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 hacia adentro que admiten un estado de plegado a la mitad (la bisagra está abierta a la mitad, como una laptop), enumera los estados correspondientes en com.android.internal.R.array.config_halfFoldedDeviceStates.

• En el caso de los dispositivos que admiten el modo de pantalla posterior, haz lo siguiente:

  • Enumera los estados correspondientes en com.android.internal.R.array.config_rearDisplayDeviceStates para DeviceStateManager.
  • Especifica la dirección física de la pantalla trasera en com.android.internal.R.string.config_rearDisplayPhysicalAddress.
  • Especifica el identificador de estado en com.android.internal.R.integer.config_deviceStateRearDisplay para que lo usen 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 los dispositivos que admiten el modo de pantalla dual (simultánea), se aplican los siguientes cambios:

  • Establece com.android.internal.R.bool.config_supportsConcurrentInternalDisplays en true.
  • Especifica la dirección física de la pantalla trasera en com.android.internal.R.config_deviceStateConcurrentRearDisplay.
  • Especifica el identificador de estado en com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay para que lo usen 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 OEM deben verificar sus implementaciones para garantizar el comportamiento esperado en situaciones comunes. Las pruebas de CTS y las pruebas con Jetpack WindowManager están disponibles para los OEM para probar las 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 del dispositivo para el 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 manualmente observando el resultado del shell. Algunas pruebas se omiten si el dispositivo no cumple con ciertos supuestos. 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.