Pulsanti fisici

In genere un dispositivo indossabile contiene più pulsanti fisici, chiamati anche _stems_. I dispositivi Wear OS hanno sempre, almeno, un pulsante: il tasto di accensione. Oltre a questo, potrebbero essere presenti zero o più pulsanti multifunzione.

Nella tua app puoi assegnare pulsanti multifunzione alle azioni. Ad esempio, un'app per l'attività fisica potrebbe avviare o sospendere un esercizio utilizzando pulsanti multifunzione:

Nota: Wear OS 3.0 riserva due pulsanti per il sistema operativo, mentre Wear OS 2.0 ne prenota uno solo. In questo modo ridurrai il numero di pulsanti a cui puoi assegnare azioni.

Per casi d'uso adeguati e considerazioni sulla progettazione, esamina i principi di progettazione di Wear OS.

Questa guida descrive come recuperare informazioni sui pulsanti multifunzione disponibili su un dispositivo e come elaborare le pressioni dei pulsanti.

Metadati del pulsante

Per ottenere informazioni aggiuntive sui pulsanti su un dispositivo, usa l'API definita nella libreria AndroidX Wear Input. Aggiungi la dipendenza seguente nel file build.gradle del modulo dell'app:

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

Numero di pulsanti

Per scoprire quanti pulsanti sono disponibili sul dispositivo, utilizza il metodo WearableButtons.getButtonCount(). Questo metodo include il tasto di accensione, quindi se il metodo restituisce un valore maggiore di uno, sono disponibili pulsanti multifunzione da utilizzare. Per ottenere un conteggio preciso dei pulsanti multifunzione assegnabili, sottraine uno dal conteggio, dato che il primo è sempre il tasto di accensione.

Codici per la pressione dei pulsanti

Ogni pulsante è mappato a una costante int della classe KeyEvent, come mostrato nella seguente tabella:

Pulsante	Evento chiave
Pulsante multifunzione 1	KEYCODE_STEM_1
Pulsante multifunzione 2	KEYCODE_STEM_2
Pulsante multifunzione 3	KEYCODE_STEM_3

Il codice di esempio seguente mostra come ottenere il numero di pulsanti disponibili:

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
}

Maneggia la pressione dei pulsanti

Esistono diversi possibili codici chiave dei pulsanti che la tua app può gestire:

• KEYCODE_STEM_1
• KEYCODE_STEM_2
• KEYCODE_STEM_3

La tua app può ricevere questi codici chiave e convertirli in azioni in-app specifiche.

Per gestire la pressione di un pulsante, implementa il metodo onKeyDown().

Ad esempio, questa implementazione risponde alla pressione dei pulsanti per controllare le azioni in un'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);
}

Stabilire la posizione dei pulsanti

La libreria AndroidX offre due metodi che descrivono la posizione di un pulsante:

• WearableButtons.getButtonLabel() restituisce una stringa localizzata che descrive la posizione generale del pulsante sul dispositivo.
• WearableButtons.getButtonIcon() restituisce un'icona che rappresenta la posizione generale del pulsante sul dispositivo.

Nota: consigliamo di evitare di utilizzare descrittori testuali per la descrizione dei pulsanti e delle loro funzioni. Utilizza invece indicatori visivi. Tuttavia, in alcuni casi può essere più sensato descrivere un pulsante.

I metodi precedenti erano progettati per descrizioni semplici. Se queste API non soddisfano le esigenze della tua app, puoi utilizzare anche l'API WearableButtons.getButtonInfo() per ottenere la posizione del pulsante sullo schermo e gestirlo in modo più personalizzato. Per ulteriori informazioni sulle API, consulta la documentazione di riferimento per le API Wear.