Botões multifunção no Wear

Além do botão liga/desliga (coroa), o Wear OS by Google é compatível com botões físicos extras conhecidos como botões multifuncionais (MF). A Biblioteca de Suporte de Wearables oferece APIs para determinar informações sobre os botões MF disponíveis em um dispositivo.

Esta lição explica como recuperar informações sobre os botões MF disponíveis em um dispositivo e processar objetos KeyEvent.

Confira os seguintes recursos relacionados:

Gerenciar eventos de teclas

Se o app precisar gerenciar o pressionamento de um botão multifuncional, ele poderá fazê-lo por meio dos códigos de eventos de pressionamento de tecla padrão na estrutura do Android. Geralmente, os códigos de teclas têm correspondência um para um com botões físicos de um dispositivo.

O conjunto disponível de códigos de teclas de botão 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 botão, implemente o método onKeyDown().

Por exemplo, esta implementação responde ao pressionamento de alguns botões 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);
    }
    

Encontrar botões disponíveis

Para descobrir quais botões podem ser usados, você pode usar os métodos WearableButtons.getButtonInfo() e WearableButtons.getButtonCount() disponíveis na Biblioteca de Suporte de Wearables. Uma maneira simples de descobrir se há botões secundários disponíveis é verificar o valor de retorno de WearableButtons.getButtonCount(). Se for maior que 1, isso quer dizer que há botões multifuncionais disponíveis para uso.

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 MF 1 KEYCODE_STEM_1
Botão MF 2 KEYCODE_STEM_2
Botão MF 3 KEYCODE_STEM_3
  • Se o dispositivo tiver apenas um botão MF, ele será sempre mapeado para KEYCODE_STEM_1.
  • Se o dispositivo tiver dois botões MF, eles serão sempre mapeados para KEYCODE_STEM_1 e KEYCODE_STEM_2.
  • Se o dispositivo tiver três botões MF, eles sempre serão mapeados para KEYCODE_STEM_1, KEYCODE_STEM_2 e KEYCODE_STEM_3.

O código de exemplo a seguir mostra como verificar o número de botões disponíveis:

Kotlin

    val count = WearableButtons.getButtonCount(context)

    if (count > 1) {
        // There are multi-function 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 multi-function 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
    }
    

Determinar as posições dos botões

A Biblioteca de Suporte de Wearables oferece duas APIs que descrevem a localização de um botão:

Observação: recomendamos que você evite usar descritores textuais para botões e as funções relacionadas. Em vez disso, use indicadores visuais. No entanto, pode haver alguns casos em que descrever um botão faz mais sentido.

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 conseguir a localização do botão na tela e tratá-lo de uma maneira mais personalizada. Para mais informações sobre as APIs, consulte a Referência de APIs do Wear.