Boutons physiques

Un accessoire connecté contient généralement plusieurs boutons physiques. Les appareils Wear OS comportent toujours au moins un bouton : le bouton Marche/Arrêt. Au-delà, ils peuvent utiliser d'autres boutons multifonctions, mais cela n'est pas obligatoire.

Dans votre application, vous pouvez attribuer des boutons multifonctions aux actions. Par exemple, une application de fitness peut démarrer ou suspendre une séance d'entraînement à l'aide de boutons multifonctions :

Remarque : Wear OS 3.0 réserve deux boutons à l'OS, contrairement à Wear OS 2.0, qui n'en réserve qu'un seul. Cela réduit le nombre de boutons auxquels vous pouvez attribuer des actions.

Pour les cas d'utilisation appropriés et les considérations de conception, consultez les principes de conception pour Wear OS.

Ce guide explique comment récupérer des informations concernant les boutons multifonctions disponibles sur un appareil et comment traiter les pressions sur les boutons.

Métadonnées des boutons

Pour en savoir plus sur les boutons d'un appareil, utilisez l'API définie dans la bibliothèque AndroidX Wear Input. Ajoutez la dépendance suivante au fichier build.gradle de votre module d'application :

dependencies {
implementation "androidx.wear:wear-input:1.0.0"
}

Nombre de boutons

Pour connaître le nombre de boutons disponibles sur l'appareil, utilisez la méthode WearableButtons.getButtonCount(). Celle-ci inclut le bouton Marche/Arrêt. Par conséquent, si elle renvoie une valeur supérieure à 1, des boutons multifonctions sont disponibles. Pour obtenir un décompte précis des boutons multifonctions attribuables, soustrayez le nombre 1 de ce décompte, car le premier bouton est toujours le bouton Marche/Arrêt.

Codes de clavier pour les boutons

Chaque bouton est mappé à une constante int de la classe KeyEvent, comme indiqué dans le tableau suivant :

Bouton	Événement de touches
Bouton multifonctions 1	KEYCODE_STEM_1
Bouton multifonctions 2	KEYCODE_STEM_2
Bouton multifonctions 3	KEYCODE_STEM_3

L'exemple de code suivant montre comment obtenir le nombre de boutons disponibles :

Kotlin

val count = WearableButtons.getButtonCount(context)

if (count > 1) {
    // There are multifunction buttons available
}

val buttonInfo = WearableButtons.getButtonInfo(activity, KeyEvent.KEYCODE_STEM_1)

if (buttonInfo == null) {
    // KEYCODE_STEM_1 is unavailable
} else {
    // KEYCODE_STEM_1 is present on the device
}

Java

int count = WearableButtons.getButtonCount(context);

if (count > 1) {
  // There are multifunction buttons available
}

WearableButtons.ButtonInfo buttonInfo =
  WearableButtons.getButtonInfo(activity, KeyEvent.KEYCODE_STEM_1);

if (buttonInfo == null) {
  // KEYCODE_STEM_1 is unavailable
} else {
  // KEYCODE_STEM_1 is present on the device
}

Gérer les pressions sur les boutons

Votre application peut gérer plusieurs codes de clavier spécifiques aux boutons :

• KEYCODE_STEM_1
• KEYCODE_STEM_2
• KEYCODE_STEM_3

Votre application peut recevoir ces codes de clavier et les convertir en actions spécifiques.

Pour gérer une pression sur un bouton, implémentez la méthode onKeyDown().

Par exemple, cette implémentation répond à des pressions sur un bouton permettant de contrôler les actions dans une application :

Kotlin

// Activity
override fun onKeyDown(keyCode: Int, event: KeyEvent): Boolean {
    return if (event.repeatCount == 0) {
        when (keyCode) {
            KeyEvent.KEYCODE_STEM_1 -> {
                // Do stuff
                true
            }
            KeyEvent.KEYCODE_STEM_2 -> {
                // Do stuff
                true
            }
            KeyEvent.KEYCODE_STEM_3 -> {
                // Do stuff
                true
            }
            else -> {
                super.onKeyDown(keyCode, event)
            }
        }
    } else {
        super.onKeyDown(keyCode, event)
    }
}

Java

@Override
// Activity
public boolean onKeyDown(int keyCode, KeyEvent event){
  if (event.getRepeatCount() == 0) {
    if (keyCode == KeyEvent.KEYCODE_STEM_1) {
      // Do stuff
      return true;
    } else if (keyCode == KeyEvent.KEYCODE_STEM_2) {
      // Do stuff
      return true;
    } else if (keyCode == KeyEvent.KEYCODE_STEM_3) {
      // Do stuff
      return true;
    }
  }
  return super.onKeyDown(keyCode, event);
}

Déterminer l'emplacement d'un bouton

La bibliothèque AndroidX propose deux méthodes décrivant l'emplacement d'un bouton :

• WearableButtons.getButtonLabel() affiche une chaîne localisée qui décrit l'emplacement général du bouton sur l'appareil.
• WearableButtons.getButtonIcon() affiche une icône représentant l'emplacement général du bouton sur l'appareil.

Remarque : Nous vous déconseillons d'utiliser des descripteurs textuels pour décrire les boutons et leurs fonctions. Utilisez plutôt des indicateurs visuels. Toutefois, dans certains cas, la description d'un bouton est plus appropriée.

Les méthodes précédentes ont été conçues pour des descriptions simples. Si ces API ne répondent pas aux besoins de votre application, vous pouvez également utiliser l'API WearableButtons.getButtonInfo() pour obtenir l'emplacement du bouton à l'écran et le gérer de manière plus personnalisée. Pour en savoir plus sur les API, consultez la documentation de référence de l'API Wear.