Créer des cadrans pour Wear OS

1. Avant de commencer

Pour créer des cadrans pour Wear OS, les développeurs doivent utiliser le Watch Face Format, un format basé sur XML qui permet de créer des cadrans expressifs et performants.

Cet atelier de programmation s'adresse aux personnes qui souhaitent créer des cadrans à la main à l'aide du langage XML ou à celles qui souhaitent mieux comprendre le format pour créer leurs propres outils de conception.

Si vous souhaitez utiliser des outils graphiques pour créer votre propre cadran, nous vous recommandons de consulter les outils existants tels que Watch Face Studio.

Prérequis

Vous avez de l'expérience avec le langage XML.

Objectifs de l'atelier

Cet atelier de programmation traite des points suivants :

Comment les cadrans WFF sont-ils empaquetés
Comment créer un cadran, y compris le mode ambiant
Ajouter des éléments tels que des formes
Intégrer des sources de données au cadran
Comment résoudre les problèmes liés au cadran

Vous allez créer un cadran personnalisable, avec différents choix de thèmes de couleurs, un compteur de pas intégré et un indicateur de date.

Ce dont vous avez besoin

Android Studio Meerkat ou version ultérieure : bien qu'il ne soit pas nécessaire d'utiliser directement Android Studio, c'est le moyen le plus simple de s'assurer que les outils de compilation Android et les outils de plate-forme sont installés et seront utilisés.
Un émulateur Wear OS ou une montre Wear OS, avec les options pour les développeurs activées.

2. Comprendre la structure d'un projet Watch Face Format

Télécharger les fichiers de l'atelier de programmation

Pour commencer, téléchargez les fichiers de l'atelier de programmation ici.

$ git clone https://github.com/android/codelab-watch-face-format

Vous pouvez également télécharger le dépôt sous forme de fichier ZIP :

Il existe deux projets dans le répertoire watch-face-format : start et finish. Nous utiliserons le projet start, mais vous pouvez toujours consulter le projet finish à tout moment, car il contient l'atelier de programmation terminé.

Examinons la structure de base du projet Watch Face Format. Vous pouvez utiliser l'éditeur de votre choix ou ouvrir le projet de démarrage dans Android Studio en sélectionnant File > Open… (Fichier > Ouvrir…) et en choisissant le répertoire start.

Dans le répertoire start/watchface/src/main, vous verrez les fichiers suivants. Voyons ce que chacun d'eux fait :

Fichier	Description
`AndroidManifest.xml`	Tout comme dans une application Android standard, ce fichier contient des informations essentielles sur le cadran et sur ce qui est nécessaire pour le créer.
`res/xml/watch_face_info.xml`	Le fichier d'informations du cadran contient des métadonnées sur le cadran, telles que la façon de trouver l'image d'aperçu et si le cadran est personnalisable.
`res/raw/watchface.xml`	Ce fichier contient la définition du cadran lui-même. Bien qu'il soit possible d'avoir plusieurs définitions, il s'agit du fichier par défaut utilisé.
`res/drawable/preview.png`	Chaque cadran a besoin d'une image d'aperçu utilisée par le système. Pour que ce projet puisse être compilé, le dossier "start/" contient un aperçu vide. Nous le mettrons à jour ultérieurement.
`res/drawable/hour.pngres/drawable/minute.pngres/drawable/second.png`	Il s'agit des aiguilles que nous utiliserons dans notre cadran.
`res/values/strings.xml`	Tout comme dans une application Android, contient des chaînes pouvant être utilisées dans le cadran.

Où se trouve le code ?

Notez qu'il n'y a en fait aucun code dans le projet. À l'exception du fichier AndroidManifest.xml, tous les fichiers du projet se trouvent dans res/, le répertoire des ressources. En effet, les cadrans Watch Face Format ne peuvent contenir aucun code. Si vous essayez d'inclure du code Kotlin ou Java, par exemple, le Play Store ne l'acceptera pas.

Le système Wear OS lit ces ressources et se charge de créer et d'exécuter votre cadran pour vous. Cela signifie qu'aucun environnement d'exécution ni aucune autre logique ne sont nécessaires, ce qui vous permet de gagner du temps de développement.

3. Créer un cadran

Nous allons mettre à jour chacun des fichiers ci-dessus afin de créer un cadran fonctionnel.

Préparer le fichier manifeste

Pour identifier le package en tant que cadran Watch Face Format, le fichier manifeste doit déclarer deux éléments :

L'absence de code dans le projet ;
La version de Watch Face Format utilisée.

Commencez par mettre à jour l'élément <application> pour ajouter l'attribut hasCode :

<application
    android:label="@string/watch_face_name"
    android:hasCode="false">

Ensuite, ajoutez un <property> à l'élément <application> en spécifiant la version de Watch Face Format utilisée dans ce cadran :

<property
    android:name="com.google.wear.watchface.format.version"
    android:value="1" />

Définir le fichier `watch_face_info`

Le fichier watch_face_info.xml comporte une exigence obligatoire : indiquer l'emplacement de l'image d'aperçu. Dans ce projet, nous avons fourni une image d'aperçu à res/drawable/preview.png. Il s'agit d'un fichier vide, mais nous le mettrons à jour ultérieurement avec une capture d'écran de notre cadran terminé.

Dans cet atelier de programmation, nous allons également rendre notre cadran personnalisable. Nous déclarons également cela dans le watch_face_info.xml file à l'aide de l'élément <Editable>.

Mettez à jour res/xml/watch_face_info.xml pour ajouter les éléments suivants :

<Preview value="@drawable/preview" />
<Editable value="true" />

Écrire un fichier XML Watch Face Format

La définition du cadran proprement dit est contenue dans res/raw/watchface.xml. Examinez ce fichier dans votre éditeur. Vous verrez que l'élément <WatchFace> définit une largeur et une hauteur de 450x450 pour votre cadran. Cet espace de coordonnées est utilisé dans le reste du fichier, indépendamment des dimensions en pixels réelles sur lesquelles le cadran s'exécute, et est mis à l'échelle en conséquence.

Le code XML est le suivant :

<?xml version="1.0"?>
<WatchFace width="450" height="450">
  <Scene>
    <PartText x="0" y="0" width="450" height="450">
      <Text>
        <Font family="SYNC_TO_DEVICE" size="48">Hello, World!</Font>
      </Text>
    </PartText>
  </Scene>
</WatchFace>

Pour l'instant, cette définition va simplement afficher "Hello, World!" sur la montre. Malheureusement, l'heure n'est pas encore affichée. Mais nous y reviendrons pour résoudre ce problème. Voyons comment créer le cadran et l'installer sur l'appareil.

Créer et déployer le cadran

Sur la ligne de commande, assurez-vous d'être dans le répertoire de démarrage et exécutez la commande suivante :

./gradlew installDebug

Ou sous Windows :

gradlew.bat installDebug

Cela créera le cadran et l'installera sur l'appareil. Appuyez de manière prolongée sur l'écran du cadran et recherchez le cadran Codelab. Vous pouvez également définir le cadran à partir de la ligne de commande :

adb shell am broadcast -a com.google.android.wearable.app.DEBUG_SURFACE --es operation set-watchface --es watchFaceId com.example.codelab

Vous devriez maintenant voir le cadran sur votre montre ou votre émulateur. Félicitations !

4. Ajouter l'heure

Watch Face Format permet d'afficher des horloges analogiques et numériques. Vous pouvez même afficher les deux ou plusieurs horloges sur un seul cadran.

Voyons comment ajouter une horloge analogique à l'aide de l'élément < AnalogClock>. Tout d'abord, supprimez l'intégralité de l'élément <PartText> du fichier watchface.xml et remplacez-le par le code suivant :

<AnalogClock x="0" y="0" width="450" height="450">
  <!-- TODO: Add shadows here later -->
  <HourHand resource="hour"
      x="215" y="50" width="20" height="190"
      pivotX="0.5" pivotY="0.921" >
  </HourHand>
  <MinuteHand resource="minute"
      x="217" y="25" width="16" height="220"
      pivotX="0.5" pivotY="0.9">
  </MinuteHand>
  <SecondHand resource="second"
      x="221" y="15" width="8" height="245"
      pivotX="0.5" pivotY="0.857">
    <Variant mode="AMBIENT" target="alpha" value="0" />
    <Sweep frequency="15" />
  </SecondHand>
</AnalogClock>

L'élément <AnalogClock> a une hauteur et une largeur de 450, ce qui signifie qu'il occupe tout l'écran. Il comporte également trois éléments enfants : < HourHand>, < MinuteHand> et < SecondHand>. Notez les points suivants concernant leur définition :

Ressource : chacun de ces éléments enfants possède un attribut de ressource, qui correspond à un élément drawable. Par exemple, il existe un fichier hour.png dans res/drawable, qui est utilisé par l'élément <HourHand>. Notez qu'il n'est pas nécessaire de spécifier @drawable.
Pivots : les aiguilles sont automatiquement pivotées, mais pivotX et pivotY spécifient où le pivot doit avoir lieu. Par exemple, pivotY est calculé comme suit :

Variante : <SecondHand> inclut un élément enfant < Variant>. L'aiguille des secondes est masquée, car le cadran ne se met à jour qu'une fois par minute en mode Veille.

Exécutez maintenant la commande suivante pour recréer et déployer le cadran sur votre appareil ou votre émulateur :

./gradlew installDebug

Cette fois, nous avons une horloge fonctionnelle, mais nous pouvons encore l'améliorer.

5. Ajouter des couleurs et des thèmes

Les cadrans sont amusants en partie parce qu'ils peuvent être personnalisés et expressifs.

Notre cadran est un peu simple pour le moment (il est tout blanc). Ajoutons-y de la couleur ! De plus, nous allons rendre les thèmes de couleur personnalisables.

Créer la ColorConfiguration

Nous allons d'abord définir les thèmes de couleur qui seront disponibles dans le cadran. Dans watchface.xml, recherchez le texte  et remplacez-le par :

<UserConfigurations>
  <ColorConfiguration id="themeColor" displayName="color_label" defaultValue="0">
    <ColorOption id="0" displayName="color_theme_0" colors="#ffbe0b #fb5607 #ff006e #8338ec #883c3c3c" />
    <ColorOption id="1" displayName="color_theme_1" colors="#8ecae6 #219ebc #ffb703 #fb8500 #883c3c3c" />
    <ColorOption id="2" displayName="color_theme_2" colors="#ff595e #ffca3a #8ac926 #1982c4 #883c3c3c" />
    <ColorOption id="3" displayName="color_theme_3" colors="#ff0000 #00ff00 #ff00ff #00ffff #883c3c3c" />
    <ColorOption id="4" displayName="color_theme_4" colors="#ff99c8 #fcf6bd #d0f4de #a9def9 #883c3c3c" />
    <ColorOption id="5" displayName="color_theme_5" colors="#1be7ff #6eeb83 #e4ff1a #ffb800 #883c3c3c" />
  </ColorConfiguration>
</UserConfigurations>

Cela définit six thèmes de couleurs, chacun contenant cinq couleurs. Chaque thème est une liste de couleurs séparées par une espace, comme indiqué dans l'attribut colors.

Chaque thème doit avoir un nom compréhensible. Ajoutez donc les définitions suivantes au fichier res/values/strings.xml :

<string name="color_label">Color Theme</string>
<string name="color_theme_0">Bold</string>
<string name="color_theme_1">Magic</string>
<string name="color_theme_2">Breeze</string>
<string name="color_theme_3">Daytime</string>
<string name="color_theme_4">Relaxed</string>
<string name="color_theme_5">Smart</string>

Utiliser la ColorConfiguration

Après avoir défini les thèmes de couleur, appliquez-les aux aiguilles de la montre en ajoutant un attribut tintColor à chacune d'elles. Modifiez watchface.xml comme suit :

<HourHand ... tintColor="[CONFIGURATION.themeColor.0]">
...
<MinuteHand ... tintColor="[CONFIGURATION.themeColor.1]">
...
<SecondHand ... tintColor="[CONFIGURATION.themeColor.2]">

<HourHand> fait référence à la première couleur du thème sélectionné, <MinuteHand> à la deuxième et <SecondHand> à la troisième.

Recompilez et déployez le cadran, comme précédemment. Vous verrez qu'il est désormais en couleur.

De plus, si vous appuyez de manière prolongée sur le cadran, puis sur le bouton des paramètres, vous pouvez choisir parmi six thèmes de couleur.

6. Ajouter une couleur d'arrière-plan

Nous pouvons faire quelques autres choses pour que ce cadran se démarque. Ajoutons un design d'arrière-plan audacieux. Bien que l'arrière-plan reste principalement noir, cette touche de couleur améliore son apparence.

Nous allons utiliser l'élément < PartDraw> de Watch Face Format, qui vous permet de créer un calque pour dessiner des primitives telles que des lignes, des rectangles, des ovales et des arcs. Remplacez le texte  par le code suivant :

<Group x="100" y="100" width="250" height="250" name="background" alpha="127">
  <Variant mode="AMBIENT" target="alpha" value="0" />
  <PartDraw x="0" y="0" width="250" height="250">
    <Ellipse x="0" y="0" width="250" height="250">
      <Fill color="[CONFIGURATION.themeColor.3]" />
    </Ellipse>
    <Ellipse x="50" y="50" width="150" height="150">
      <Fill color="#000000" />
    </Ellipse>
  </PartDraw>
</Group>

Notez à nouveau l'utilisation de l'élément <Variant> : cela supprimera notre anneau d'arrière-plan en mode ambiant, afin de minimiser le nombre de pixels allumés.

Notez également que nous utilisons à nouveau le thème de couleur pour sélectionner la couleur de l'anneau, ce qui permet de conserver le style sur tous les éléments du cadran.

7. Valider votre cadran

Avant d'aller plus loin dans l'amélioration du cadran, voyons comment optimiser le processus de développement à l'aide du validateur Watch Face Format.

Le validateur est un outil qui vérifie que votre code XML est correct. Il vous permet de gagner du temps en évitant de créer et de déployer un cadran qui ne fonctionne pas.

Téléchargez le fichier JAR du validateur à partir du dépôt GitHub.
Exécuter le validateur sur votre fichier watchface.xml

java -jar wff-validator.jar 1 watchface/src/main/res/raw/watchface.xml

Si le code XML du cadran est valide, un message de confirmation s'affiche. En revanche, si une erreur est détectée, les détails de l'erreur et l'emplacement s'affichent, par exemple :

SEVERE: [Line 18:Column 49]: cvc-complex-type.2.4.a: Invalid content was found starting with element 'PartDrw'

8. Utiliser des sources de données

Le Watch Face Format peut utiliser différentes sources de données pour rendre votre cadran plus utile.

Ajoutons deux sources de données couramment utilisées pour rendre votre cadran plus utile : la date actuelle (qui n'a pas déjà oublié la date ?) et le nombre de pas quotidiens.

Chacun de ces éléments est placé dans un conteneur < PartText>, qui est un calque permettant d'effectuer des opérations sur le texte.

Ajouter la date

Remplacez le texte  par le code suivant :

<PartText x="225" y="225" width="225" height="225">
  <Variant mode="AMBIENT" target="alpha" value="0" />
  <TextCircular centerX="0" centerY="0" width="415" height="415" startAngle="180" endAngle="90" align="CENTER" direction="COUNTER_CLOCKWISE">
    <Font family="SYNC_TO_DEVICE" size="28" color="[CONFIGURATION.themeColor.0]">
      <Template>
        <![CDATA[%d %s]]>
        <Parameter expression="[DAY]"/>
        <Parameter expression="[MONTH_S]"/>
      </Template>
    </Font>
  </TextCircular>
</PartText>

Dans l'extrait ci-dessus, nous utilisons < Template> pour mettre en forme deux sources de données dans une chaîne. DAY est un entier compris entre 1 et 31, et MONTH_S est déjà une chaîne. Nous utilisons donc l'expression de mise en forme %d %s pour placer l'entier et la chaîne ensemble.

Il est recommandé de l'entourer d'un élément CDATA, car cela évite que des espaces blancs soient accidentellement intégrés dans le rendu, ce qui peut affecter le positionnement et l'alignement.

Enfin, notez que nous avons à nouveau utilisé le thème de couleur pour nous assurer que ce dernier ajout au cadran conserve le thème existant.

Ajouter le nombre de pas

Remplacez le texte  par le code suivant :

<PartText x="0" y="0" width="225" height="225">
  <Variant mode="AMBIENT" target="alpha" value="0" />
  <TextCircular centerX="225" centerY="225" width="415" height="415" startAngle="270" endAngle="360" align="CENTER" direction="CLOCKWISE">
    <Font family="SYNC_TO_DEVICE" size="28" color="[CONFIGURATION.themeColor.2]">
      <Template>
        <![CDATA[%05d]]>
        <Parameter expression="[STEP_COUNT]"/>
      </Template>
    </Font>
  </TextCircular>
</PartText>

Watch Face Format est compatible avec toute une gamme de sources de données. Le nombre de pas est un excellent ajout à n'importe quel cadran, car il permet à l'utilisateur de suivre ses mouvements et ses exercices quotidiens.

Créez et déployez le cadran pour vérifier les derniers ajouts :

9. Touches finales et aperçu

Le souci du détail est essentiel pour les cadrans. Nous allons donc ajouter quelques touches finales.

Ajouter une ombre au cadran

Les aiguilles du cadran fonctionnent bien ensemble avec leurs différentes couleurs, mais elles semblent un peu plates par rapport au cadran. Remplacez  par le code suivant pour ajouter des ombres derrière les aiguilles de la montre :

<HourHand resource="hour" x="220" y="55" width="20" height="190"
    pivotX="0.5" pivotY="0.921" tintColor="[CONFIGURATION.themeColor.4]">
  <Variant mode="AMBIENT" target="alpha" value="0" />
</HourHand>
<MinuteHand resource="minute" x="222" y="30" width="16" height="220"
    pivotX="0.5" pivotY="0.9" tintColor="[CONFIGURATION.themeColor.4]">
  <Variant mode="AMBIENT" target="alpha" value="0" />
</MinuteHand>
<SecondHand resource="second" x="226" y="20" width="8" height="245"
    pivotX="0.5" pivotY="0.857" tintColor="[CONFIGURATION.themeColor.4]">
  <Variant mode="AMBIENT" target="alpha" value="0" />
  <Sweep frequency="15" />
</SecondHand>

Ajouter un logo ludique

Tous les fabricants de montres connus affichent leur logo sur leurs cadrans. Nous allons donc ajouter le nôtre. Utilisons le logo Android !

Cependant, comme il s'agit d'une montre connectée, faisons quelque chose de différent et ajoutons un logo qui peut bouger en fonction de l'angle du poignet de l'utilisateur.

Pour ce faire, nous allons placer notre image dans un élément < Group>, puis utiliser un élément < Transform> pour appliquer une rotation à l'élément <Group>, en fonction de l'angle du poignet. Notre structure se présente comme suit :

Le point de pivot par défaut d'un élément se trouve au centre. Nous n'avons donc pas besoin d'ajuster les pivotX et pivotY de <Group>. L'application de <Transform> à <Group> fait pivoter <PartImage> autour de ce point pivot central.

Dans <Transform>, nous utilisons la source de données [ ACCELEROMETER_ANGLE_XY], qui représente la somme des angles dans les directions X et Y.

Remplacez  par l'extrait de code suivant :

<Group x="92" y="92" width="266" height="266" name="logo_container">
  <Variant mode="AMBIENT" target="alpha" value="0" />
  <Transform target="angle" mode="BY" value="0.1 * [ACCELEROMETER_ANGLE_XY]" />
  <PartImage x="97" y="0" width="72" height="72"
    tintColor="[CONFIGURATION.themeColor.2]">
    <Image resource="android"/>
  </PartImage>
</Group>

Redéployez votre cadran. Si vous utilisez un appareil physique, mettez-le et déplacez votre poignet pour voir le logo Android bouger. Si vous utilisez un émulateur, ouvrez les commandes étendues de l'émulateur et manipulez les angles X et Y dans les capteurs virtuels.

Mettre à jour l'aperçu

Vous vous souvenez qu'au début de l'atelier de programmation, nous avons vu qu'il existait un fichier preview.png utilisé par le système pour afficher un aperçu du cadran ? Nous allons maintenant mettre à jour cette image pour qu'elle reflète mieux le cadran terminé.

Le moyen le plus simple de générer une capture d'écran consiste à utiliser l'émulateur. Une fois le cadran en cours d'exécution, cliquez sur le bouton de capture d'écran :

Assurez-vous que la capture est définie sur Forme de l'écran :

Enregistrez l'image et remplacez le fichier res/drawable/preview.png par cette nouvelle image. Recompilez et déployez votre cadran comme précédemment.

10. Félicitations

Félicitations ! Vous avez appris les principes de base de la création d'un cadran avec le Watch Face Format.

Solution de l'atelier de programmation

Le code nécessaire à la solution de cet atelier de programmation est disponible sur GitHub :

$ git clone https://github.com/android/codelab-watch-face-format