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 vous intéresser aux 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
Créer un cadran, y compris en mode Veille
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 Android Studio directement, c'est le moyen le plus simple de vous assurer que les outils de compilation Android et les outils de plate-forme sont installés.
Un émulateur Wear OS ou une montre Wear OS, avec les options pour les développeurs activées.

2. Comprendre la structure du 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 consulter le projet finish à tout moment. Il contient l'atelier de programmation terminé.

Inspectons 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 sélectionnant 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`	Comme dans une application Android standard, ce fichier contient des informations essentielles sur le cadran et sur ce dont vous avez besoin 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, c'est le fichier par défaut qui est utilisé.
`res/drawable/preview.png`	Chaque cadran nécessite 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 que nous 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`	Comme dans une application Android, il contient des chaînes pouvant être utilisées dans le cadran.

Où se trouve le code ?

Notez qu'il n'y a 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'aucune logique d'exécution ou autre n'est nécessaire, ce qui vous permet de réduire les efforts de développement.

3. Créer un cadran

Nous allons mettre à jour chacun des fichiers ci-dessus pour 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 plus tard avec une capture d'écran de notre cadran terminé.

Dans le cadre de cet atelier de programmation, nous allons également rendre notre cadran personnalisable. Nous déclarons également cette valeur dans 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 réel est contenue dans res/raw/watchface.xml. Inspectez 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 réelles en pixels du cadran, et est ajusté 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 affichera simplement "Hello, World!" sur la montre. Malheureusement, il n'y a pas encore d'heure ! 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

Le cadran est alors créé et installé 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

Le cadran devrait maintenant s'afficher sur votre montre ou dans l'é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. Il occupe donc 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, un fichier hour.png se trouve dans res/drawable et 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 qui fonctionne, mais nous pouvons encore l'améliorer.

5. Ajouter des couleurs et des thèmes

L'un des aspects les plus amusants des cadrans est la possibilité de les personnaliser et de les rendre expressifs.

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

Créer la ColorConfiguration

Nous allons d'abord définir les thèmes de couleurs qui seront disponibles sur 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 couleur, 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 couleur et <SecondHand> à la troisième.

Recréez et déployez le cadran, comme précédemment, et vous verrez qu'il est maintenant en couleur.

De plus, si vous appuyez de manière prolongée sur le cadran et que vous appuyez sur le bouton Paramètres, vous pouvez choisir parmi les six thèmes de couleurs.

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

Nous pouvons encore améliorer ce cadran. Ajoutons un 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 ce qui suit :

<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 l'utilisation de l'élément <Variant>. Cela permet de supprimer l'anneau d'arrière-plan en mode Veille, afin de réduire 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 de 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 une couche permettant d'effectuer des opérations de 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

Les cadrans doivent être soignés. Ajoutons donc quelques touches finales.

Ajouter une ombre au cadran

Les aiguilles du cadran s'accordent bien dans leurs différentes couleurs, mais elles semblent un peu plates. 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. Bien sûr, nous allons utiliser le logo Android.

Toutefois, comme il s'agit d'une montre connectée, essayons quelque chose de différent et ajoutons un logo qui peut se déplacer 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. Il n'est donc pas nécessaire d'ajuster les valeurs 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 existe un fichier preview.png utilisé par le système pour afficher un aperçu du cadran ? Modifions-le maintenant pour mieux refléter notre cadran final !

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 Display Shape (Afficher la forme) :

Enregistrez l'image et remplacez le fichier res/drawable/preview.png par cette nouvelle image. Recréez 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