物理ボタン

ウェアラブル デバイスは通常、ステムとも呼ばれる複数の物理ボタンを備えています。Wear OS デバイスには少なくとも 1 つのボタンがあります。電源ボタンです。それ以外に、多機能ボタンがいくつか存在する場合もあります。 一部のデバイスには、物理的な回転サイドボタンも搭載されています。

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

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

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

ボタンのメタデータ

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

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

ボタンの数

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

ボタン押下のキーコード

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

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

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

ボタンの押下を処理する

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

• KEYCODE_STEM_1。
• KEYCODE_STEM_2。

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

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

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

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

ボタンの位置を確認する

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

• WearableButtons.getButtonLabel() デバイス上のボタンの一般的な配置を示すローカライズされた文字列を返します。
• WearableButtons.getButtonIcon() は、デバイス上のボタンの一般的な配置を示すアイコンを返します。

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