Extensions WindowManager

La bibliothèque Jetpack WindowManager permet aux développeurs d'applications d'exploiter de nouveaux facteurs de forme d'appareil et de nouveaux environnements multifenêtres.

Les extensions WindowManager (Extensions) sont un module de plate-forme Android activable qui permet d'utiliser diverses fonctionnalités de Jetpack WindowManager. Le module est implémenté dans AOSP dans frameworks/base/libs/WindowManager/Jetpack et est fourni sur les appareils compatibles avec les fonctionnalités WindowManager.

Distribution du module Extensions

Les extensions sont compilées dans une bibliothèque .jar et placées dans la partition system_ext d'un appareil si elles sont activées dans le fichier de compilation de l'appareil.

Pour activer les extensions sur un appareil, ajoutez ce qui suit au fichier makefile de l'appareil du produit:

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

Cela active les packages androidx.window.extensions et androidx.window.sidecar sur l'appareil et définit la propriété persist.wm.extensions.enabled. L'inclusion de ces packages dans le fichier make place également des déclarations dans etc/permissions/, ce qui les rend disponibles pour les processus d'application. En règle générale, les modules sont chargés et exécutés dans le cadre du processus d'application au moment de l'exécution lorsqu'ils sont utilisés par la bibliothèque Jetpack WindowManager, ce qui rend son fonctionnement semblable au code de framework côté client, comme illustré dans la figure suivante:

Figure 1 : Les extensions WindowManager chargées dans le processus de l'application sont semblables au code de la plate-forme.

Le module androidx.window.extensions est le module Extensions actuellement en cours de développement. Le module androidx.window.sidecar est un ancien module inclus pour la compatibilité avec les premières versions de Jetpack WindowManager, mais le sidecar n'est plus activement géré.

La figure suivante montre la logique permettant de déterminer l'utilisation de androidx.window.extensions ou de androidx.window.sidecar.

Figure 2 : Arbre de décision pour accéder à androidx.window.extensions ou androidx.window.sidecar.

Modules d'extension

Les extensions fournissent des fonctionnalités de fenêtrage pour les appareils pliables à grand écran et les appareils compatibles avec le fenêtrage sur les écrans externes. Les domaines de fonctionnalité incluent les suivants:

• Intégration d'activités
• Informations sur la mise en page de la fenêtre
• Zone de la fenêtre

Les implémentations OEM des extensions peuvent fournir des composants nuls ou des composants avec des implémentations par défaut ou des bouchons des méthodes dans l'interface WindowExtensions si le matériel de l'appareil n'est pas compatible avec les fonctionnalités correspondantes, sauf si la fonctionnalité est spécifiquement demandée dans le document de définition de la compatibilité (CDD) 7.1.1.1.

Extensions et API Jetpack

Le module Extensions WindowManager fournit sa propre surface d'API en plus des API de plate-forme publiques. Le module Extensions est développé publiquement dans une bibliothèque Jetpack androidx.window.extensions destinée aux utilisateurs autres que les développeurs, afin que Jetpack WindowManager (androidx.window) puisse l'associer au moment de la compilation. La surface de l'API Extensions fournit généralement des API de bas niveau.

Les API fournies par les extensions ne sont destinées qu'à la bibliothèque Jetpack WindowManager. Les API Extensions ne sont pas destinées à être appelées directement par les développeurs d'applications. La bibliothèque Extensions ne doit pas être ajoutée en tant que dépendance d'une application dans le fichier de compilation Gradle pour garantir un fonctionnement correct. Évitez de précompiler directement la bibliothèque Extensions dans une application. Utilisez plutôt le chargement au moment de l'exécution pour éviter de charger un mélange de classes Extensions précompilées et fournies par l'environnement d'exécution.

Jetpack WindowManager (androidx.window) doit être ajouté en tant que dépendance d'application et fournit les API publiques destinées aux développeurs, y compris celles pour les fonctionnalités des extensions WindowManager. La bibliothèque WindowManager charge automatiquement les extensions dans le processus de l'application et encapsule les API d'extension de bas niveau dans des abstractions de niveau supérieur et des interfaces plus ciblées. Les API Jetpack WindowManager respectent les normes de développement d'applications Android modernes et sont conçues pour offrir une interopérabilité pratique en s'intégrant bien aux codebases qui utilisent d'autres bibliothèques AndroidX.

Versions et mises à jour des extensions

Le module Extensions peut être mis à jour avec les mises à jour annuelles ou trimestrielles de la plate-forme Android. Les mises à jour trimestrielles permettent d'augmenter le niveau de l'API Extensions entre les mises à jour de l'API de la plate-forme Android, ce qui permet d'accélérer l'itération et d'offrir aux OEM la possibilité d'ajouter un accès API officiel aux nouvelles fonctionnalités à proximité des lancements de matériel.

Le tableau suivant répertorie les versions de l'API androidx.window.extensions pour différentes versions d'Android.

Version de la plate-forme Android	Niveau d'API des extensions WindowManager	Version de l'API androidx.window.extensions
Android 15	6	1.5.0 (bientôt disponible)
Android 14 QPR3	5	1.4.0 (bientôt disponible)
Android 14 QPR1	4	1.3.0
Android 14	3	1.2.0
Android 13 QPR3	2	1.1.0
Android 13	1	1.0.0
Android 12L	1	1.0.0

Le niveau de l'API Extensions (colonne centrale) augmente chaque fois qu'une extension est ajoutée à la surface de l'API stable existante (colonne de droite).

Remarque:Les OEM ne sont pas tenus de prendre en charge les mises à jour QPR, mais doivent coordonner la version de la plate-forme et le niveau de l'API Extensions comme suit :

• Toute version logicielle de plate-forme de base fournie par les OEM doit avoir au moins la même version d'extensions que celle définie dans le tableau.
• Vous pouvez distribuer une ancienne version de la plate-forme avec une version plus récente d'Extensions, mais l'implémentation nécessite généralement également des modifications importantes dans le noyau WindowManager pour prendre en charge la fonctionnalité.
• Les implémentations qui incluent une ancienne version de la plate-forme et une version plus récente des extensions doivent réussir la suite de tests de compatibilité (CTS) correspondante pour les extensions plus récentes. L'implémentation n'est pas validée automatiquement via les tests CTS pour la version de plate-forme antérieure correspondante.

Rétrocompatibilité et compatibilité ascendante

Jetpack WindowManager gère la complexité de la gestion des mises à jour fréquentes au niveau de l'API, de l'évolution rapide de l'API et de la rétrocompatibilité. Lorsque le code de la bibliothèque est exécuté dans le processus d'application, la bibliothèque vérifie le niveau de l'API Extensions déclaré et fournit l'accès aux fonctionnalités en fonction du niveau déclaré.

Pour éviter qu'une application ne plante au moment de l'exécution, WindowManager effectue également une vérification de la réflexion Java au moment de l'exécution des API Extensions disponibles en fonction du niveau d'API Extensions déclaré. En cas de non-concordance, WindowManager peut désactiver l'utilisation des extensions (partiellement ou complètement) et signaler les fonctionnalités concernées comme non disponibles pour l'application.

Les extensions WindowManager sont implémentées en tant que module system_ext qui utilise des API de plate-forme privées pour appeler le noyau WindowManager, DeviceStateManager et d'autres services système lors de l'implémentation des fonctionnalités d'extension.

La compatibilité avec les versions préliminaires des extensions peut ne pas être maintenue avant la version trimestrielle ou annuelle correspondante de la plate-forme Android avec laquelle les versions sont finalisées. L'historique complet des API Extensions se trouve dans la branche de publication Fichiers de texte de l'API window:extensions:extensions.

Les versions plus récentes d'Extensions doivent continuer à fonctionner avec les anciennes versions de WindowManager compilées dans les applications pour maintenir la rétrocompatibilité. Pour cela, toute nouvelle version de l'API Extensions n'ajoute que de nouvelles API et ne supprime pas les anciennes. Par conséquent, les applications avec des versions plus anciennes de WindowManager peuvent continuer à utiliser les anciennes API Extensions avec lesquelles elles ont été compilées.

La vérification CTS garantit que, pour toute version déclarée des API Extensions sur l'appareil, toutes les API de cette version et des versions précédentes sont présentes et fonctionnelles.

Performances

Le module Extensions est mis en cache dans les chargeurs de classe système non bootclasspath par défaut à partir d'Android 14 (niveau d'API 34). Il n'y a donc aucun impact sur les performances en raison du chargement du module en mémoire au démarrage de l'application. L'utilisation de fonctionnalités de module individuelles peut avoir une légère influence sur les caractéristiques de performances des applications lorsque des appels IPC supplémentaires sont effectués entre le client et le serveur.

Modules

Intégration d'activités

Le composant intégration d'activités permet aux applications d'optimiser leur UI pour les appareils à grand écran et les écrans externes. L'intégration d'activités permet de présenter deux activités côte à côte dans une mise en page multi-volets, ce qui facilite le développement d'applications adaptatives pour les anciennes applications.

Le composant d'intégration d'activité doit être disponible sur tous les appareils disposant d'un écran intégré égal ou supérieur à sw600dp. L'intégration d'activités doit également être activée sur les appareils compatibles avec les connexions d'écrans externes, car l'application peut s'afficher dans une taille plus grande lorsque des écrans externes sont connectés au moment de l'exécution.

Remarque :Certains OEM obligent les applications à utiliser l'intégration d'activités définie par le système. Les applications peuvent empêcher l'intégration d'activités définie par le système en définissant PROPERTY_ACTIVITY_EMBEDDING_ALLOW_SYSTEM_OVERRIDE dans le fichier manifeste de l'application. Si une application a défini la propriété sur false, le système ne doit pas forcer l'application à utiliser l'intégration d'activités définie par le système.

Configuration de l'appareil

Aucune configuration d'appareil spécifique n'est nécessaire, sauf pour activer le module Extensions, comme décrit dans la section Distribution du module Extensions. Il est logique d'activer les extensions sur tous les appareils compatibles avec le mode multifenêtre. Les futures versions d'Android rendront probablement les extensions obligatoires pour les configurations d'appareils portables et à grand écran courantes.

Informations sur la mise en page de la fenêtre

Le composant d'informations sur la mise en page de la fenêtre identifie la position et l'état de la charnière sur un appareil pliable lorsque la charnière croise une fenêtre d'application. Les informations de mise en page des fenêtres permettent aux applications de répondre aux mises en page optimisées et de les afficher en mode sur table sur les appareils pliables. Pour en savoir plus sur l'utilisation, consultez la section Adapter votre application aux appareils pliables.

Les appareils Android pliables qui incluent une charnière reliant des zones de panneau d'affichage distinctes ou continues doivent mettre les informations sur la charnière à la disposition des applications via WindowLayoutComponent.

La position et les limites de la charnière doivent être indiquées par rapport à la fenêtre de l'application identifiée par un Context transmis à l'API. Si les limites de la fenêtre de l'application ne se croisent pas avec les limites de la charnière, la charnière DisplayFeature ne doit pas être signalée. Il est également acceptable de ne pas signaler les fonctionnalités d'affichage lorsque leur position ne peut pas être signalée de manière fiable, par exemple lorsqu'une fenêtre d'application peut être déplacée librement par l'utilisateur en mode multifenêtre ou en mode letterbox de compatibilité.

Pour les fonctionnalités de pliage, les mises à jour d'état doivent être signalées lorsque la position de la charnière change entre les états stables. Par défaut, dans un état d'affichage plat, l'API doit indiquer FoldingFeature.State.FLAT. Si le matériel de l'appareil peut être laissé en mode demi-plié dans un état stable, l'API doit signaler FoldingFeature.State.HALF_OPENED. Il n'y a pas d'état fermé dans l'API, car dans ce cas, la fenêtre de l'application ne serait pas visible ou ne franchirait pas les limites de la charnière.

Configuration de l'appareil

Pour prendre en charge l'implémentation de la fonctionnalité de pliage, les OEM doivent procéder comme suit:

• Configurez les états de l'appareil dans device_state_configuration.xml pour qu'ils soient utilisés par DeviceStateManagerService. Pour en savoir plus, consultez la page DeviceStateProviderImpl.java.

  Si les implémentations par défaut de DeviceStateProvider ou de DeviceStatePolicy ne conviennent pas à l'appareil, une implémentation personnalisée peut être utilisée.

• Activez le module Extensions comme décrit dans la section Distribution du module Extensions.

• Spécifiez l'emplacement des fonctionnalités d'affichage dans la ressource de chaîne com.android.internal.R.string.config_display_features (généralement dans frameworks/base/core/res/res/values/config.xml dans la superposition de l'appareil).

  Le format attendu pour la chaîne est le suivant:

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

  type peut correspondre à fold ou hinge. Les valeurs de left, top, right et bottom sont des coordonnées de pixel entières dans l'espace de coordonnées de l'écran dans l'orientation naturelle de l'écran. La chaîne de configuration peut contenir plusieurs fonctionnalités d'affichage séparées par des points-virgules.

  Exemple :

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

• Définissez le mappage entre les identifiants d'état de l'appareil interne utilisés dans DeviceStateManager et les constantes d'état publiques envoyées aux développeurs dans com.android.internal.R.array.config_device_state_postures.

  Le format attendu pour chaque entrée est le suivant:

  <device_specific_state_identifier>:<Jetpack WindowManager state identifier>

  Les identifiants d'état acceptés sont les suivants:

  • COMMON_STATE_NO_FOLDING_FEATURES = 1: l'état ne comporte aucune fonctionnalité de pliage à signaler. Il peut s'agir, par exemple, de l'état fermé de l'appareil pliable classique avec l'écran principal à l'intérieur.
  • COMMON_STATE_HALF_OPENED = 2: la fonctionnalité de pliage est à moitié ouverte.
  • COMMON_STATE_FLAT = 3: la fonctionnalité de pliage est plate. Par exemple, il peut s'agir de l'état ouvert de l'appareil pliable typique avec l'écran principal à l'intérieur.
  • COMMON_STATE_USE_BASE_STATE = 1000: dans Android 14, valeur pouvant être utilisée pour les états émulés où l'état de la charnière est dérivé à l'aide de l'état de base, comme défini dans CommonFoldingFeature.java

  Pour en savoir plus, consultez DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int).

  Exemple :

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

Zone de la fenêtre

Le composant de zone de fenêtre fournit un ensemble de fonctionnalités qui donnent aux applications accès à des écrans et des zones d'affichage supplémentaires sur certains appareils pliables et multi-écrans.

Le mode d'affichage arrière permet à une application d'afficher l'UI d'aperçu de l'appareil photo sur l'écran de couverture d'un appareil pliable afin d'utiliser la caméra principale de l'appareil pour les selfies et les vidéos. Les appareils dotés d'un écran de couverture compatible avec Android (tel que défini par le CDD Android en termes d'attributs tels que la taille, la densité et les affordances de navigation disponibles) qui s'aligne sur les caméras arrière de l'appareil doivent fournir un accès au mode d'affichage arrière.

Sur Android 14, le mode Dual Screen permet aux applications exécutées sur l'écran intérieur d'un appareil pliable d'afficher du contenu supplémentaire sur l'écran de couverture visible par les autres utilisateurs. Par exemple, l'écran de couverture peut afficher l'aperçu de l'appareil photo à la personne photographiée ou filmée.

Configuration de l'appareil

Pour prendre en charge l'implémentation de la fonctionnalité de pliage, les OEM doivent procéder comme suit:

• Configurez les états de l'appareil dans device_state_configuration.xml pour qu'ils soient utilisés par DeviceStateManagerService. Pour en savoir plus, consultez DeviceStateProviderImpl.java.

  Si l'implémentation par défaut de DeviceStateProvider ou de DeviceStatePolicy n'est pas adaptée à l'appareil, une implémentation personnalisée peut être utilisée.

• Pour les appareils pliables compatibles avec le mode ouvert ou plat, spécifiez les identifiants d'état correspondants dans com.android.internal.R.array.config_openDeviceStates.

• Pour les appareils pliables compatibles avec les états pliés, listez les identifiants d'état correspondants dans com.android.internal.R.array.config_foldedDeviceStates.

• Pour les appareils pliables qui acceptent un état à moitié plié (la charnière est à moitié ouverte comme un ordinateur portable), listez les états correspondants dans com.android.internal.R.array.config_halfFoldedDeviceStates.

• Pour les appareils compatibles avec le mode d'affichage arrière:

  • Répertoriez les états correspondants dans com.android.internal.R.array.config_rearDisplayDeviceStates pour DeviceStateManager.
  • Spécifiez l'adresse d'affichage physique de l'écran arrière dans com.android.internal.R.string.config_rearDisplayPhysicalAddress.
  • Spécifiez l'identifiant d'état dans com.android.internal.R.integer.config_deviceStateRearDisplay à utiliser par les extensions.
  • Ajoutez l'identifiant d'état dans com.android.internal.R.array.config_deviceStatesAvailableForAppRequests pour le mettre à la disposition des applications.

• Sur Android 14, pour les appareils compatibles avec le mode d'affichage double (concurremment) :

  • Définissez com.android.internal.R.bool.config_supportsConcurrentInternalDisplays sur true.
  • Spécifiez l'adresse d'affichage physique de l'écran arrière dans com.android.internal.R.config_deviceStateConcurrentRearDisplay.
  • Spécifiez l'identifiant d'état dans com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay à utiliser par les extensions si l'identifiant doit être mis à la disposition des applications.
  • Ajoutez l'identifiant d'état dans com.android.internal.R.array.config_deviceStatesAvailableForAppRequests pour le mettre à la disposition des applications.

Validation

Les OEM doivent vérifier leurs implémentations pour s'assurer du comportement attendu dans les scénarios courants. Les tests CTS et les tests utilisant Jetpack WindowManager sont disponibles pour les OEM afin de tester les implémentations.

Tests CTS

Pour exécuter les tests CTS, consultez la section Exécuter des tests CTS. Les tests CTS liés à Jetpack WindowManager se trouvent sous cts/tests/framework/base/windowmanager/jetpack/. Le nom du module de test est CtsWindowManagerJetpackTestCases.

Tests WindowManager

Pour télécharger les tests Jetpack WindowManager, suivez les instructions Android Jetpack. Les tests se trouvent dans la bibliothèque de fenêtres sous le module window:window : window/window/src/androidTest/.

Pour exécuter les tests de l'appareil pour le module window:window à partir de la ligne de commande, procédez comme suit:

1. Branchez un appareil sur lequel les options pour les développeurs et le débogage USB sont activés.
2. Autorisez l'ordinateur à déboguer l'appareil.
3. Ouvrez une interface système dans le répertoire racine du dépôt androidx.
4. Remplacez le répertoire par framework/support.
5. Exécutez la commande suivante: ./gradlew window:window:connectedAndroidTest.
6. Analysez les résultats.

Pour exécuter les tests à partir d'Android Studio, procédez comme suit:

1. Ouvrez Android Studio.
2. Branchez un appareil sur lequel les options pour les développeurs et le débogage USB sont activés.
3. Autorisez l'ordinateur à déboguer l'appareil.
4. Accédez à un test dans la bibliothèque de fenêtres du module de fenêtre.
5. Ouvrez une classe de test et exécutez-la à l'aide des flèches vertes sur le côté droit de l'éditeur.

Vous pouvez également créer une configuration dans Android Studio pour exécuter une méthode de test, une classe de test ou tous les tests d'un module.

Les résultats peuvent être analysés manuellement en examinant la sortie de l'interface système. Certains tests sont ignorés si l'appareil ne répond pas à certaines hypothèses. Les résultats sont enregistrés dans un emplacement standard, et les analystes peuvent écrire un script pour automatiser l'analyse des résultats.