Botones físicos

Por lo general, un dispositivo wearable contiene varios botones físicos, también conocidos como _coronas_. Los dispositivos Wear OS siempre tienen, como mínimo, un botón (el botón de encendido). Además, es posible que haya cero o más botones multifunción.

En tu app, puedes asignar botones multifunción a acciones. Por ejemplo, una app de fitness puede iniciar o pausar un entrenamiento mediante botones multifunción:

Nota: Wear OS 3.0 reserva dos botones para el SO, mientras que Wear OS 2.0 solo reserva uno. Esto reduce la cantidad de botones a los que puedes asignar acciones.

Para conocer los casos de uso apropiados y las consideraciones de diseño, consulta los lineamientos de diseño de Wear OS.

En esta guía, se describe cómo recuperar información sobre los botones multifunción disponibles en un dispositivo y cómo procesar las pulsaciones de botones.

Metadatos de los botones

Para obtener información adicional sobre los botones de un dispositivo, usa la API definida en la biblioteca de AndroidX Wear Input. Agrega la siguiente dependencia en el archivo build.gradle del módulo de tu app.

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

Cantidad de botones

Para averiguar cuántos botones están disponibles en el dispositivo, usa el método WearableButtons.getButtonCount(). Este método incluye el botón de encendido, por lo que, si el método muestra un valor mayor que uno, hay botones multifunción disponibles para usar. Para obtener un recuento preciso de los botones multifunción asignables, resta uno de la cantidad, ya que el primer botón siempre es el de encendido.

Claves de códigos para la pulsación de botones

Cada botón se asigna a una constante int de la clase KeyEvent, como se muestra en la siguiente tabla:

Botón KeyEvent
Botón multifunción 1 KEYCODE_STEM_1
Botón multifunción 2 KEYCODE_STEM_2
Botón multifunción 3 KEYCODE_STEM_3

El siguiente código de ejemplo muestra cómo obtener el recuento de botones 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
}

Cómo controlar las pulsaciones de los botones

Tu app puede controlar varios códigos de botones:

  • KEYCODE_STEM_1
  • KEYCODE_STEM_2
  • KEYCODE_STEM_3

Tu app puede recibir estos códigos clave y convertirlos en acciones específicas en la app.

Para controlar cómo se presiona un botón, implementa el método onKeyDown().

Por ejemplo, esta implementación responde a las pulsaciones de un botón para controlar acciones en una app:

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);
}

Cómo determinar las posiciones de los botones

La biblioteca de AndroidX proporciona dos métodos que describen la ubicación de un botón:

Nota: Te recomendamos que evites el uso de descriptores textuales a la hora de describir los botones y sus funciones. En su lugar, usa indicadores visuales. Sin embargo, puede haber algunos casos en los que describir un botón tenga más sentido.

Los métodos anteriores se diseñaron para descripciones simples. Si estas APIs no satisfacen las necesidades de tu app, también puedes usar la API de WearableButtons.getButtonInfo() para obtener la ubicación del botón en la pantalla y manejarlo de manera más personalizada. Si quieres obtener más información sobre las APIs, consulta la referencia de la API de Wear.