Botões físicos

Normalmente, os dispositivos wearable têm vários botões físicos, também conhecidos como hastes. 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. Alguns dispositivos também têm um botão lateral giratório.

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

Figura 1. App fitness do Wear OS mostrando botões multifuncionais.

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

Este documento 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 seguinte dependência ao arquivo build.gradle do módulo do app:

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

Número de botões

Para determinar 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 a seguir mostra como verificar o número de botões disponíveis:

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

Processar o pressionamento de botão

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

• KEYCODE_STEM_1.
• KEYCODE_STEM_2.

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:

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

Determinar as posições dos botões

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

• WearableButtons.getButtonLabel() retorna uma string localizada que descreve o posicionamento geral do botão no dispositivo.
• WearableButtons.getButtonIcon() retorna um ícone que representa o posicionamento geral do botão no dispositivo.

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 do 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.