Botões físicos

Normalmente, os dispositivos wearable têm vários botões físicos, também conhecidos como “stems”. Os dispositivos Wear OS sempre têm pelo menos um botão: o botão liga/desliga. Além disso, os dispositivos podem incluir botões multifuncionais.

No seu app, é possível atribuir ações aos botões multifuncionais. Por exemplo, um app fitness pode usar um botão multifuncional para começar ou pausar um treino:

Observação: o Wear OS 3.0 reserva dois botões para o SO, diferente do Wear OS 2.0, que reserva apenas um. Isso reduz o número de botões a que você pode atribuir ações.

Para analisar os casos de uso adequados e as considerações de design, consulte os princípios de design para Wear OS.

Este guia descreve como extrair informações sobre os botões multifuncionais disponíveis em um dispositivo e como processar o pressionamento deles.

Metadados de botões

Para receber informações sobre os botões presentes em um dispositivo, use a API definida na biblioteca AndroidX Wear Input. Adicione a dependência abaixo ao arquivo build.gradle do módulo do app. 

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

Número de botões

Para descobrir quantos botões estão disponíveis no dispositivo, use o método WearableButtons.getButtonCount(). Esse método inclui o botão liga/desliga. Portanto, se ele retornar um valor maior que um, isso significa que há botões multifuncionais disponíveis para uso. Para saber o número exato dos botões multifuncionais disponíveis, subtraia um do total, já que o primeiro é sempre o botão liga/desliga.

Códigos de teclas para pressionamento de botão

Cada botão é mapeado para uma constante int da classe KeyEvent, conforme mostrado na tabela a seguir:

Botão Evento de tecla
Botão multifuncional 1 KEYCODE_STEM_1
Botão multifuncional 2 KEYCODE_STEM_2
Botão multifuncional 3 KEYCODE_STEM_3

O código de exemplo abaixo mostra como conferir o número de botões disponíveis:

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
}

Gerenciar o pressionamento de botão

Existem diversos códigos de tecla que o app pode gerenciar:

  • KEYCODE_STEM_1
  • KEYCODE_STEM_2
  • KEYCODE_STEM_3

O app pode receber esses códigos de teclas e convertê-los em ações específicas.

Para gerenciar um pressionamento de botão, implemente o método onKeyDown().

Por exemplo, a implementação abaixo responde ao pressionamento de um botão para controlar ações em um 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);
}

Determinar as posições dos botões

A biblioteca AndroidX inclui dois métodos que descrevem a localização de um botão:

Observação: recomendamos evitar o uso de descrições textuais ao se referir aos botões e às funções deles. Em vez disso, use indicadores visuais. No entanto, podem existir alguns casos em que é melhor descrever o botão.

Os métodos acima foram criados para descrições simples. Se essas APIs não atenderem às necessidades do seu app, também é possível usar a API WearableButtons.getButtonInfo() para descobrir a localização de um botão na tela e gerenciar o pressionamento dele de uma maneira mais personalizada. Para mais informações sobre as APIs, consulte a Referência de APIs do Wear.