Boutons physiques

Un accessoire connecté contient généralement plusieurs boutons physiques, également appelés tiges. 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. Certains appareils sont également dotés d'un bouton latéral rotatif.

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

Montre avec plusieurs boutons latéraux. Le système désigne l'un des boutons comme bouton multifonction.
Figure 1. Application de fitness Wear OS affichant des boutons multifonctions.

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

Ce document 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 du module de votre application :

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

Nombre de boutons

Pour déterminer le nombre de boutons disponibles sur l'appareil, utilisez la méthode WearableButtons.getButtonCount(). Cette méthode 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 KeyEvent
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 :

val count = WearableButtons.getButtonCount(context)

if (count > 1) {
    Log.d(TAG, "More than one button available")
}

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

if (buttonInfo == null) {
    // KEYCODE_STEM_1 is unavailable
    Log.d(TAG, "KEYCODE_STEM_1 not available")
} else {
    // KEYCODE_STEM_1 is present on the device
    Log.d(TAG, "KEYCODE_STEM_1 is present on the device")
}
HardwareButtonsActivity.kt

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.

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 :

override fun onKeyDown(keyCode: Int, event: KeyEvent?): Boolean {
    return if (event?.repeatCount == 0) {
        when (keyCode) {
            KeyEvent.KEYCODE_STEM_1 -> {
                Log.d(TAG, "KEYCODE_STEM_1 pressed")
                true
            }
            KeyEvent.KEYCODE_STEM_2 -> {
                Log.d(TAG, "KEYCODE_STEM_2 pressed")
                true
            }
            else -> {
                super.onKeyDown(keyCode, event)
            }
        }
    } else {
        super.onKeyDown(keyCode, event)
    }
}
HardwareButtonsActivity.kt

Déterminer l'emplacement d'un bouton

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

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.