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:
![](https://developer.android.google.cn/static/wear/images/multi_function_buttons.png?authuser=19&hl=pt-br)
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:
-
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.
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.