物理ボタン

通常、ウェアラブル デバイスには複数の物理ボタン（ステムとも呼ばれます）があります。Wear OS デバイスには少なくとも 1 つのボタンがあります。電源ボタンです。それ以外に、多機能ボタンがいくつか存在する場合もあります。

アプリでは、多機能ボタンをアクションに割り当てることができます。たとえば、フィットネス アプリでは、多機能ボタンを使用してワークアウトを開始したり一時停止したりします。

注: Wear OS 2.0 では OS 用に 1 つのボタンしか予約されていませんが、Wear OS 3.0 では 2 つのボタンが予約されています。そのため、アクションを割り当てることができるボタンの数が少なくなっています。

適切なユースケースとデザイン上の考慮事項については、Wear OS のデザインの原則をご覧ください。

このガイドでは、デバイスで使用できる多機能ボタンに関する情報を取得する方法と、ボタンの押下を処理する方法について説明します。

ボタンのメタデータ

デバイスのボタンに関する追加情報を取得するには、Wear Input AndroidX ライブラリで定義されている API を使用します。アプリ モジュールの build.gradle ファイルに次の依存関係を追加します。 

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

ボタンの数

デバイスで利用可能なボタンの数を確認するには、WearableButtons.getButtonCount() メソッドを使用します。このメソッドには電源ボタンが含まれています。したがって、メソッドが 1 より大きい値を返す場合は、多機能ボタンを利用できます。割り当て可能な多機能ボタンの正確な数を得るには、第一のボタンが常に電源ボタンであるため、返された数から 1 を差し引きます。

ボタン押下のキーコード

次の表に示すように、各ボタンは KeyEvent クラスの int 定数にマッピングされています。

ボタン KeyEvent
多機能ボタン 1 KEYCODE_STEM_1
多機能ボタン 2 KEYCODE_STEM_2
多機能ボタン 3 KEYCODE_STEM_3

次のサンプルコードは、使用可能なボタンの数を取得する方法を示しています。

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
}

ボタンの押下を処理する

アプリで処理できるボタンのキーコードは次のとおりです。

  • KEYCODE_STEM_1
  • KEYCODE_STEM_2
  • KEYCODE_STEM_3

アプリはこれらのキーコードを受け取って、特定のアプリ内操作に変換できます。

ボタンの押下を処理するには、onKeyDown() メソッドを実装します。

たとえば、次の実装では、ボタンの押下に反応してアプリ内操作を制御しています。

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);
}

ボタンの位置を確認する

AndroidX ライブラリには、ボタンの位置を記述する 2 つのメソッドが用意されています。

注: ボタンとその機能について説明するときは、テキスト形式の記述子を使用しないことをおすすめします。代わりにビジュアル インジケーターを使用してください。ただし、ボタンについて説明するほうが効果的な場合もあります。

上記のメソッドは、簡単な説明用に設計されたものです。これらの API がアプリのニーズを満たさない場合は、WearableButtons.getButtonInfo() API を使用して画面上のボタンの位置を取得し、よりカスタマイズされた方法で処理することもできます。これらの API について詳しくは、Wear API リファレンスをご覧ください。