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 de un dispositivo si las extensiones están habilitadas en el archivo makefile del dispositivo.

Para habilitar las extensiones en un dispositivo, agrega lo siguiente al archivo makefile 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. Cuando incluyes estos paquetes en el archivo makefile, también se colocan declaraciones en etc/permissions/, lo que las pone a disposición de los procesos de aplicaciones. 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:

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 brindar compatibilidad con las primeras versiones de Jetpack WindowManager, pero el archivo adicional 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. 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.

Extensiones y APIs de 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 WindowManager de Jetpack (androidx.window) pueda vincularse con ella en el momento de la 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. Para garantizar la funcionalidad correcta, no se debe agregar la biblioteca de extensiones como dependencia de una aplicación en el archivo de compilación de Gradle. Evita compilar previamente la biblioteca de extensiones en una aplicación directamente. En su lugar, confía en la carga del tiempo de ejecución para evitar cargar una combinación de clases de extensiones ya compiladas y proporcionadas por el entorno de ejecución.

Jetpack WindowManager (androidx.window) se diseñó para agregarse como una dependencia de la aplicación y proporciona las APIs públicas para desarrolladores, incluidas las de las funciones de extensiones de WindowManager. 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 Jetpack de WindowManager siguen los estándares del desarrollo moderno de aplicaciones para Android y están pensadas para proporcionar interoperabilidad conveniente mediante la integración correcta con bases de código que usan otras bibliotecas de AndroidX.

Versiones y actualizaciones de las extensiones

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

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

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 el código de biblioteca se ejecuta en el proceso de aplicación, la biblioteca 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 no hay coincidencia, WindowManager puede inhabilitar el uso de extensiones (de forma parcial o total) y, luego, informar que las funciones relevantes no están disponibles para la app.

Las extensiones de WindowManager se implementan como un módulo system_ext que usa APIs de plataformas 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 preliminares 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 Extensions se puede encontrar en los archivos de texto de la API de window:extensions:extensions de la rama de la versión.

Las versiones más recientes de Extensions deben seguir funcionando con versiones anteriores de WindowManager compiladas en aplicaciones para mantener la retrocompatibilidad. 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, en cualquier versión declarada de las APIs de Extensions en el dispositivo, todas las APIs de esa versión y de las versiones anteriores estén presentes y funcionen.

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 de IPC adicionales entre el cliente y el servidor.

Módulos

Incorporación de actividades

El componente de incorporación de actividades proporciona un conjunto de funciones que permiten a las aplicaciones organizar la presentación de la ventana de actividad dentro de los límites de la aplicación superior. Esto incluye mostrar dos actividades simultáneamente en un diseño de varios paneles, lo que facilita la optimización de pantallas grandes para aplicaciones heredadas.

El componente de incorporación de actividades debe estar disponible en todos los dispositivos que tengan una pantalla integrada de un tamaño igual o mayor que sw600 dp. La incorporación de actividades también debe habilitarse en 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 durante el tiempo de ejecución.

Configuración del dispositivo

No se necesita ninguna configuración de dispositivo específica, salvo habilitar el módulo de extensiones, como se describe en la sección Distribución del módulo de extensiones. Tiene sentido habilitar las extensiones en todos los dispositivos que admitan 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 a diseños optimizados y los muestren 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 de la bisagra y los límites deben informarse 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 cruzan con los límites de la bisagra, no se debe informar sobre 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 características de plegado, las actualizaciones de estado deben informarse 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 de extensiones como se describe en la sección Distribución del módulo de extensiones.

• Especifica la ubicación de las características de la pantalla en el recurso de cadenas com.android.internal.R.string.config_display_features (por lo general, en frameworks/base/core/res/res/values/config.xml, en la superposición de dispositivos).

  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 varios elementos de visualización separados 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 del dispositivo internos que se usan en DeviceStateManager y las constantes de estado público 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 características de plegado para informar. Por ejemplo, puede ser el estado cerrado del típico dispositivo plegable con la pantalla principal en el lado interno.
  • COMMON_STATE_HALF_OPENED = 2: La función de plegado está semiabierta.
  • COMMON_STATE_FLAT = 3: La función plegable es plana. Por ejemplo, puede ser el estado abierto de un dispositivo plegable típico con la pantalla principal en el lado interno.
  • COMMON_STATE_USE_BASE_STATE = 1000: En Android 14, un valor que se puede usar para los estados emulados en los que el estado de la 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 de área de ventana proporciona un conjunto de funciones que 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 portada de un dispositivo plegable para permitir el uso de la cámara principal del dispositivo para 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 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 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.

• 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 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 compatibles con 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 en 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 se debe poner a disposición de 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 Windows, en el módulo window:window: window/window/src/androidTest/.

Para ejecutar las pruebas de 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 de forma manual si se observa el resultado de la shell. Algunas pruebas se omiten 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.