Extensiones de WindowManager

La biblioteca Jetpack WindowManager permite a los desarrolladores de aplicaciones admitir nuevos factores de forma de dispositivos y entornos de ventanas múltiples.

Extensiones de WindowManager (Extensiones) es un módulo de plataforma Android opcional que permite 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 MAKE del dispositivo.

Para habilitar Extensiones en un dispositivo, agregue 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 . Incluir estos paquetes en el archivo MAKE también coloca declaraciones en etc/permissions/ , poniéndolas a disposición de los procesos de aplicación. Normalmente, los módulos se cargan y ejecutan como parte del proceso de la aplicación en tiempo de ejecución cuando los usa la biblioteca Jetpack WindowManager, lo que hace que su funcionamiento sea similar al código del marco del lado del cliente, como se muestra en la siguiente figura:

Figura 1. Extensiones de WindowManager cargadas en el proceso de solicitud de forma 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 incluido para compatibilidad con las versiones más antiguas de Jetpack WindowManager, pero el sidecar ya no se mantiene activamente.

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

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

Módulos de extensiones

Las extensiones proporcionan funciones de ventanas para dispositivos de pantalla grande plegables y dispositivos que admiten ventanas en pantallas externas. Las áreas de características incluyen:

• Incrustación de actividad
• Información de diseño de ventana
• Área de ventana

Las implementaciones OEM de Extensiones pueden proporcionar componentes nulos o componentes con implementaciones predeterminadas o auxiliares 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. .

Extensiones y API de Jetpack

El módulo Extensiones de WindowManager proporciona su propia superficie API además de las API de la plataforma pública. El módulo Extensiones se desarrolla públicamente en una biblioteca Jetpack androidx.window.extensions que no está orientada al desarrollador, de modo que Jetpack WindowManager ( androidx.window ) pueda vincularse a él en el momento de la compilación. La superficie API de Extensions normalmente proporciona API de nivel inferior.

Las API que proporcionan las Extensiones están destinadas a ser utilizadas únicamente por la biblioteca Jetpack WindowManager. Las API de Extensiones no deben ser llamadas directamente por los desarrolladores de aplicaciones. La biblioteca de Extensiones no se debe agregar como una dependencia de una aplicación en el archivo de compilación de Gradle para garantizar una funcionalidad correcta. Evite precompilar la biblioteca de Extensiones directamente en una aplicación; en su lugar, confíe en la carga en tiempo de ejecución para evitar el caso de cargar una combinación de clases de Extensiones precompiladas y proporcionadas en tiempo de ejecución.

Jetpack WindowManager ( androidx.window ) está diseñado para agregarse como una dependencia de la aplicación y proporciona API públicas orientadas a los desarrolladores, incluidas aquellas para las funciones de Extensiones de WindowManager. La biblioteca WindowManager carga automáticamente Extensiones en el proceso de aplicación y agrupa las API de Extensiones de nivel inferior en abstracciones de nivel superior e interfaces más enfocadas. Las API de WindowManager Jetpack siguen los estándares del desarrollo moderno de aplicaciones de Android y están destinadas a proporcionar una interoperabilidad conveniente al integrarse bien con bases de código que utilizan otras bibliotecas de AndroidX.

Versiones y actualizaciones de extensiones.

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

La siguiente tabla enumera las versiones de la API androidx.window.extensions para varias versiones de Android.

Versión de la plataforma Android	Nivel de API de extensiones de WindowManager	Versión de la API androidx.window.extensions
Androide 14	3	1.2.0
Android 13 QPR3	2	1.1.0
androide 13	1	1.0.0
Android 12L	1	1.0.0

El nivel de API de Extensiones (columna central) aumenta cada vez que se agrega una superficie 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 extensiones de la siguiente manera:

• Cualquier versión de software de plataforma base enviada por los OEM debe tener al menos la misma versión de Extensiones como se define en la tabla.
• Puede enviar una versión anterior de la plataforma con una versión más nueva de Extensiones, pero normalmente 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 de plataforma anterior y una versión más nueva de Extensiones deben pasar el conjunto de pruebas de compatibilidad (CTS) correspondiente para las Extensiones más nuevas. La implementación no obtiene verificación automática a través de las pruebas CTS para la versión anterior de la plataforma correspondiente.

Compatibilidad hacia atrás y hacia adelante

Jetpack WindowManager maneja la complejidad de lidiar con actualizaciones frecuentes de nivel de API, una rápida evolución de API y compatibilidad con versiones anteriores. Cuando el código de la biblioteca se ejecuta en el proceso de solicitud, la biblioteca verifica el nivel de API de Extensiones declarado y proporciona acceso a las funciones de acuerdo con el nivel declarado.

Para proteger una aplicación contra fallas en tiempo de ejecución, WindowManager también realiza una verificación de reflexión Java en tiempo de ejecución de las API de extensiones disponibles de acuerdo con el nivel de API de extensiones declarado. Si hay una discrepancia, WindowManager puede desactivar el uso de Extensiones (parcial o completamente) e informar las funciones relevantes como no disponibles para la aplicación.

Las extensiones de WindowManager se implementan como un módulo system_ext que utiliza API de plataforma privada 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 versiones previas al lanzamiento de Extensiones antes del correspondiente lanzamiento trimestral o anual de la plataforma Android con el que se finalizan las versiones. El historial completo de las API de extensiones se puede encontrar en la window:extensions:extensions .

Las versiones más nuevas de Extensiones deben seguir funcionando con versiones anteriores de WindowManager compiladas en aplicaciones para mantener la compatibilidad futura. Para garantizar esto, cualquier versión nueva de la API de Extensiones solo agrega nuevas API y no elimina las más antiguas. Como resultado, las aplicaciones con versiones anteriores de WindowManager pueden continuar usando las API de Extensiones más antiguas con las que se compilaron las aplicaciones.

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

Actuación

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

Módulos

Incrustación de actividad

El componente de incrustación de actividades proporciona un conjunto de funciones que permiten a las aplicaciones organizar la presentación de la ventana de actividades dentro de los límites de la aplicación principal. Esto incluye mostrar dos actividades simultáneamente, una al lado de la otra, en un diseño de varios paneles, lo que facilita la optimización de pantalla grande para aplicaciones heredadas.

El componente de incorporación de actividades debe estar disponible en todos los dispositivos que tengan una pantalla incorporada de tamaño igual o mayor que sw600 dp . La incrustación de actividades también debe habilitarse en dispositivos que admitan conexiones de pantalla externa, ya que la aplicación podría mostrarse en un tamaño mayor cuando se conectan pantallas externas en tiempo de ejecución.

Configuración del dispositivo

No es necesaria ninguna configuración específica del dispositivo aparte de habilitar el módulo de Extensiones como se describe en la sección Distribución del módulo de Extensiones . Tiene sentido habilitar Extensiones en todos los dispositivos que admitan el modo de ventanas múltiples. Es probable que las futuras versiones de Android requieran extensiones en configuraciones comunes de dispositivos portátiles y de pantalla grande.

Información de diseño de 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 la bisagra cruza una ventana de aplicación. La información del diseño de la ventana permite que las aplicaciones respondan y muestren diseños optimizados en modo de mesa en dispositivos plegables. Consulte Hacer que su aplicación se pliegue para obtener detalles de uso.

Los dispositivos Android plegables que incluyen una bisagra que conecta áreas de panel de visualización separadas o continuas deben hacer que la información sobre la bisagra esté disponible para 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 pasado 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 DisplayFeature de la bisagra. También es aceptable no informar las funciones de visualización 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 modo de ventanas múltiples o en modo de formato buzón de compatibilidad.

Para las funciones 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 plana, la API debe informar FoldingFeature.State.FLAT . Si el hardware del dispositivo se puede dejar en modo medio plegado en un estado estable, la API debe informar FoldingFeature.State.HALF_OPENED . No existe un estado cerrado en la API, ya que en tal caso la ventana de la aplicación no sería visible o no cruzaría los límites de las bisagras.

Configuración del dispositivo

Para respaldar la implementación de la función de plegado, los OEM deben hacer lo siguiente:

• Configure los estados del dispositivo en device_state_configuration.xml para que los utilice DeviceStateManagerService . Consulte DeviceStateProviderImpl.java como referencia.

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

• Habilite el módulo Extensiones como se describe en la sección Distribución del módulo Extensiones .

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

  El formato esperado para la cadena es:

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

  El type puede ser fold o hinge . Los valores de left , top , right e bottom son coordenadas de píxeles enteras en el espacio de coordenadas de visualización en la orientación de visualización natural. 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>
  

• Defina la asignación entre los identificadores de estado del dispositivo interno utilizados en DeviceStateManager y las constantes de estado públicas enviadas a los desarrolladores en com.android.internal.R.array.config_device_state_postures .

  El formato esperado para cada entrada es:

  <device_specific_state_identifier>:<Jetpack WindowManager state identifier>

  Los identificadores de estado admitidos son:

  • 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 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 típico dispositivo plegable con la pantalla principal en el lado interior.
  • COMMON_STATE_USE_BASE_STATE = 1000 : en Android 14, un valor que se puede usar para estados emulados donde el estado de bisagra se deriva utilizando el estado base, como se define en CommonFoldingFeature.java .

  Consulte 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 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 de múltiples pantallas.

El modo de pantalla trasera permite que una aplicación muestre la interfaz de usuario 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 lo define el CDD de Android en términos de atributos como tamaño, densidad y posibilidades de navegación disponibles) que se alinea con las cámaras traseras del dispositivo deben brindar acceso al modo de pantalla trasera.

En Android 14, el modo de pantalla dual permite que las aplicaciones que se ejecutan en la pantalla interna de un dispositivo plegable muestren contenido adicional en la pantalla de la cubierta frente a otros usuarios; por ejemplo, la pantalla de la portada puede mostrar la vista previa de la cámara a la persona que está siendo fotografiada o grabada.

Configuración del dispositivo

Para respaldar la implementación de la función de plegado, los OEM deben hacer lo siguiente:

• Configure los estados del dispositivo en device_state_configuration.xml para que los utilice DeviceStateManagerService . Consulte 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 utilizar una implementación personalizada.

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

• Para dispositivos plegables que admiten estados plegados, enumere los identificadores de estado correspondientes en com.android.internal.R.array.config_foldedDeviceStates .

• Para dispositivos plegables que admiten un estado medio plegado (la bisagra está medio abierta como una computadora portátil), enumere los estados correspondientes en com.android.internal.R.array.config_halfFoldedDeviceStates .

• Para dispositivos que admiten el modo de pantalla trasera:

  • Enumere los estados correspondientes en com.android.internal.R.array.config_rearDisplayDeviceStates para DeviceStateManager .
  • Especifique la dirección de visualización física de la pantalla trasera en com.android.internal.R.string.config_rearDisplayPhysicalAddress .
  • Especifique el identificador de estado en com.android.internal.R.integer.config_deviceStateRearDisplay que utilizarán las Extensiones.
  • Agregue 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 visualización dual (simultáneo):

  • Establezca com.android.internal.R.bool.config_supportsConcurrentInternalDisplays en true .
  • Especifique la dirección de visualización física de la pantalla trasera en com.android.internal.R.config_deviceStateConcurrentRearDisplay .
  • Especifique el identificador de estado en com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay que utilizarán Extensiones si el identificador debe estar disponible para las aplicaciones.
  • Agregue 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 escenarios comunes. Las pruebas CTS y las pruebas que utilizan Jetpack WindowManager están disponibles para los OEM para probar implementaciones.

pruebas CTS

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

Pruebas del administrador de ventanas

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

Para ejecutar las pruebas de dispositivo para el módulo window:window desde la línea de comando, haga lo siguiente:

1. Conecte un dispositivo que tenga opciones de desarrollador y depuración USB habilitadas.
2. Permita que la computadora depure el dispositivo.
3. Abra un shell en el directorio raíz del repositorio de androidx.
4. Cambie el directorio a framework/support .
5. Ejecute el siguiente comando: ./gradlew window:window:connectedAndroidTest .
6. Analiza los resultados.

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

1. Abra Android Studio.
2. Conecte un dispositivo que tenga opciones de desarrollador y depuración USB habilitadas.
3. Permita que la computadora depure el dispositivo.
4. Navegue hasta una prueba dentro de la biblioteca de ventanas del módulo de ventana.
5. Abra una clase de prueba y ejecútela usando las flechas verdes en el lado derecho del editor.

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

Los resultados se pueden analizar manualmente mirando la salida 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 un script para automatizar el análisis de los resultados.