ワコムデジタイザ向けAndroid API
本書は、実装された海底の概要を説明し、利用できるようになったデータを最大限に活用するためのアプリ開発者向けの指針となることを目指しています。
INDEX
詳細
1 互換性
以下に、Androidの入力APIの開発における重要なマイルストーンを列挙します。使用可能な機能と要求されるデバイスサポートの水準とを比較検討してください。
1.1 APIレベル1(Android 1.0)
このAPIレベルで使用できるのは基本的なツール情報のみです。高解像度の座標と筆圧は取得できますが、その他のデータはほとんど取得できません。マルチタッチはまだサポートされておらず、ボタンの状態や消しゴムの区別などの興味深いスタイラス属性もサポートされません。
1.2 APIレベル5(Android 2.0:Éclair)
マルチタッチにより単一のデバイスに対する複数回のタッチを追跡できます。一方、複数デバイス(例:タッチスクリーンとEMR)の間の接触もAndroid 1.0と同様に追跡できます。Androidは、タッチスクリーンからのイベントの送信を停止して、代わりにスタイラスから新しいイベントの送信を開始できます。デバイスIDが変化するため切り替えを検知できますが、Gingerbreadまでは各デバイスのタイプを判断することができません。
1.3 APIレベル8(Android 2.2:Froyo)
1.4 APIレベル9(Android 2.3:Gingerbread)
新しい軸の1つが、スタイラスまたは指の方位角を測定する「向き」です。これは、ワコムのIntuosシリーズのタブレットで測定できる2つの傾きデータの1つです。もう1つの高度角(仰角)は、Ice Cream Sandwich以降を対象とするアプリ以外では使用できません。
InputDeviceクラスを使用すると、各MotionEventの発生元入力デバイスに関するデータを取得できます。また、デバイス名、軸の範囲、(限定的な)タイプ情報も取得できます。このクラスは以降のAPIレベルで改善されます(例:Ice Cream SandwichでのSOURCE_STYLUSの追加)。
1.5 APIレベル12(Android 3.1:Honeycomb MR1)
1.6 APIレベル14(Android 4.0:Ice Cream Sandwich)
Ice Cream SandwichではHover APIの一部が作り直されました。HoneycombではonGenericMotionEventを使用してスタイラスのホバリングをアプリに通知しますが、ICSではonHoverEventがこの機能を引き継ぎます。加えて、新しくACTION_HOVER_ENTERとACTION_HOVER_EXITの2つのホバーアクションが導入されています。これらをアプリで使用すると、ペンがセンサーに接近したり離れたりするのに合わせて、カーソルを動的に表示したり非表示にしたりすることができます。
追加のツール軸を使用できます。特に、Intuosタブレットから報告される傾きデータの後半(高度角)を使用すると、空間内のペンの正確な向きを読み取って判定することができます。距離データも提供され、画面の表面からスタイラスのおおよその距離をアプリに通知します。
Ice Cream Sandwichには、サイドスイッチの状態などのボタンの状態情報を提供し、ペン先のスタイラスと消しゴムを区別する機能もあります。
1.7 APIレベル16(Android 4.1:Jelly Bean)
2 機能
2.1 イベントリスナー
public void View.setOnTouchListener(View.OnTouchListener l)
このViewにタッチイベントが送信されたときに呼び出されるコールバックを定義します。タッチイベントは、タッチスクリーンにタッチしたり、スタイラス/マウスをドラッグしたりするなどの操作によって生成されます。
public void View.setOnGenericMotionListener(View.OnGenericMotionListener l)
このビューに一般的な動作イベント(タッチ以外)が送信されたときに呼び出されるコールバックを定義します。Ice Cream Sandwich以後は、ホバーイベントは総合動作リスナーに送信されなくなりました。
public void View.setOnHoverListener(View.OnHoverListener l)
このビューにホバーイベントが送信されたときに呼び出されるコールバックを定義します。
2.2 イベントアクション
実行されているアクションの種類を返します。2つのうち1つ目のメソッドは、アクションおよびアクションを実行したポインタインデックスを返します。2つ目のメソッドはアクションのみを返すので、以下の定数と簡単に比較できます。
押下ジェスチャーが開始されました。動作には初期位置が含まれます。
public static int ACTION_MOVE
押下ジェスチャーが(ACTION_DOWNとACTION_UPの間で)変化しました。動作には、最新の点に加えて、前回のダウンイベントまたは移動イベント以降のすべての中間点が含まれます。
public static int ACTION_UP
押下ジェスチャーが終了しました。動作には、最新の点に加えて、前回のダウンイベントまたは移動イベント以降のすべての中間点が含まれます。
public static int ACTION_HOVER_MOVE
変化が発生しましたが、(ACTION_MOVEと異なり)ポインタは押されていません。動作には、最新の点に加えて、前回のホバーイベント以降のすべての中間点が含まれます。
public static int ACTION_HOVER_ENTER
ポインタは押されていませんが、ウィンドウまたはビューの境界に入りました。このアクションはポインタの下にあるウィンドウまたはビューに常に送信されます。
public static int ACTION_HOVER_EXIT
ポインタは押されていませんが、ウィンドウまたはビューの境界から出ました。
2.3 イベントポインタ
2.3.1 インデックス
このイベントに含まれるデータのポインタの数。常に1以上です。
「interesting」アクション(例:ACTION_POINTER_DOWNまたはACTION_POINTER_UP)が発生した場合、このメソッドは注目すべきポインタのインデックスを返します。通常のイベント(例:ACTION_MOVE)については、このメソッドを呼び出す必要はありません。
特定のポインタデータインデックスに関連付けられたポインタ識別子を返します。ポインタインデックスとは異なり、ポインタ識別子は常にポインタ固有であり、安全に追跡に使用できます。
2.3.2 タイプ
指定されたポインタインデックスのポインタのツールタイプを取得します。ツールタイプは、指やスタイラスなど、接触に使用されるツールが分かる場合、そのタイプを示します。
ツールはスタイラスです。
public static final int MotionEvent.TOOL_TYPE_ERASER
ツールは消しゴムまたは逆向きに使用されるスタイラスです。
public static final int MotionEvent.TOOL_TYPE_FINGER
ツールは指です。
public static final int MotionEvent.TOOL_TYPE_UNKNOWN
この定数はツールタイプが未知の場合または該当するツールがない場合に使用されます。
2.4 イベント軸
特定の軸のデータを取得するメソッドは通常は複数あります。空のメソッドは1つ目のポインタインデックスについて最新のデータを返します。別種のメソッドでは、取得するデータのインデックスまたは世代を指定できます。
2.4.1 履歴
カーネルからのすべての入力イベントを直ちに転送することで発生する処理オーバーヘッドを最小化するために、Androidはイベントを短時間バッファリングしてからMotionEventを一括して送信します。スムーズな入力を必要とするアプリケーションでは、各種のgetHistoricalFoo(int pos)関数を通して中間の入力デバイス状態を使用できます。
このイベントの履歴に含まれる点の数を返します。これらは、このイベントと直前のイベントの間に発生した移動です。
このイベントと直前のイベントの間で履歴の移動にかかった時間を、uptimeMillis()時間基準で返します。
2.4.2 位置
Androidでは、画面ユニット内のイベントの位置がサブピクセル精度で提供されます。何らかの理由で座標をデバイスユニットに変換する必要がある場合は、getXPrecision()およびgetYPrecision()の関数も提供されます。
public final float MotionEvent.getX(int pointerIndex)
public final float MotionEvent.getHistoricalX(int pos)
public final float MotionEvent.getHistoricalX(int pos, int pointerIndex)
public static final int MotionEvent.AXIS_X
動作イベントのX軸
public final float MotionEvent.getY(int pointerIndex)
public final float MotionEvent.getHistoricalY(int pos)
public final float MotionEvent.getHistoricalY(int pos, int pointerIndex)
public static final int MotionEvent.AXIS_Y
動作イベントのY軸
このイベントの元のX座標を返します。画面上のタッチイベントの場合、これはイベントが発生したウィンドウおよびビューについて調整される前の、画面上のイベントの元の位置です。
このイベントの元のY座標を返します。画面上のタッチイベントの場合、これはイベントが発生したウィンドウおよびビューについて調整される前の、画面上のイベントの元の位置です。
2.4.3 力/サイズ
デバイスはいくつかの異なる属性で力を測定し、報告できます。スタイラスは筆圧を報告します。タッチスクリーンは接点のサイズまたは長軸と短軸の長さを報告できます。
public final float MotionEvent.getPressure(int pointerIndex)
public final float MotionEvent.getHistoricalPressure(int pos)
public final float MotionEvent.getHistoricalPressure(int pos, int pointerIndex)
public static final int MotionEvent.AXIS_PRESSURE
接点が画面に加える圧力を取得します。この値は0.0~1.0の範囲で標準化されますが、入力ドライバによってはこの範囲を越える場合があります。
public final float MotionEvent.getSize(int pointerIndex)
public final float MotionEvent.getHistoricalSize(int pos)
public final float MotionEvent.getHistoricalSize(int pos, int pointerIndex)
public static final int MotionEvent.AXIS_SIZE
接点のサイズを、検知可能な最大サイズに対する比率として取得します。
public final float MotionEvent.getTouchMajor(int pointerIndex)
public final float MotionEvent.getHistoricalTouchMajor(int pos)
public final float MotionEvent.getHistoricalTouchMajor(int pos, int pointerIndex)
public static final int MotionEvent.AXIS_TOUCH_MAJOR
接点の接触面積を表す楕円の長軸の長さを返します。
public final float MotionEvent.getTouchMinor(int pointerIndex)
public final float MotionEvent.getHistoricalTouchMinor(int pos)
public final float MotionEvent.getHistoricalTouchMinor(int pos, int pointerIndex)
public static final int MotionEvent.AXIS_TOUCH_MINOR
接点の接触面積を表す楕円の短軸の長さを返します。
public final float MotionEvent.getToolMajor(int pointerIndex)
public final float MotionEvent.getHistoricalToolMajor(int pos)
public final float MotionEvent.getHistoricalToolMajor(int pos, int pointerIndex)
public static final int MotionEvent.AXIS_TOOL_MAJOR
接近するツールのサイズを表す楕円の長軸の長さを返します。ツールの面積は、接点の実際の接触面積にかかわらず、デバイスに接触している指のおおよそのサイズを表します。
public final float MotionEvent.getToolMinor(int pointerIndex)
public final float MotionEvent.getHistoricalToolMinor(int pos)
public final float MotionEvent.getHistoricalToolMinor(int pos, int pointerIndex)
public static final int MotionEvent.AXIS_TOOL_MINOR
接近するツールのサイズを表す楕円の短軸の長さを返します。ツールの面積は、接点の実際の接触面積にかかわらず、デバイスに接触している指のおおよそのサイズを表します。
2.4.4 向き
最新版のAndroidは、ハードウェアがサポートしていれば、他に3つのツール軸を報告できます。これらは、空間内のツールの3D方向に関する追加情報を提供します。
public final float MotionEvent.getOrientation(int pointerIndex)
public final float MotionEvent.getHistoricalOrientation(int pos)
public final float MotionEvent.getHistoricalOrientation(int pos, int pointerIndex)
public static final int MotionEvent.AXIS_ORIENTATION
画面の上端に対する接点の方位角。
画面の垂線に対する接点の高度角。
ツールと画面の間の距離。
2.5 イベントボタン
マウスやスタイラスのボタンなど、押されているすべてのボタンの状態を取得します。ボタンの状態の履歴情報は参照できません。
第1ボタン(マウスの左ボタン)。このボタン定数は、指またはスタイラスの先端が触れただけでは設定されません。ユーザーが実際にボタンを押す必要があります。
public static final int MotionEvent.BUTTON_SECONDARY
第2ボタン(マウスの右ボタン、スタイラスの1つ目のボタン)。
public static final int MotionEvent.BUTTON_TERIARY
第3ボタン(マウスの中央ボタン、スタイラスの2つ目のボタン)。
2.6 デバイス情報
2.6.1 デバイス
Androidはシステムに接続されたすべての入力デバイスを追跡し、それぞれにID番号を割り当てます。このID番号は、異なるデバイスで発生する動作イベントを区別し、発生元デバイスに関する情報を取得するために使用できます。
このイベントが発生したデバイスのIDを取得します。IDが0の場合、イベントは物理デバイスで発生したのではなく、デフォルトキーマップにマッピングされていることを示します。他の数は不定なので、この値に依存した操作を行わないでください。
指定したIDに関連付けられたInputDeviceを返します。
システム内のすべての入力デバイスのIDを取得します。
この入力デバイスの名前を取得します。
入力デバイスの固定的な識別子である入力デバイスディスクリプタを取得します。このディスクリプタを使用すると、アプリケーションを再起動する場合も入力デバイスに関連付けられた設定を安全に保存できます。
2.6.2 イベント発生元
各動作イベントには、イベントの「発生元」に関する情報をタグ付けすることができます。これによって提供される追加のデバイスタイプ情報は、タッチスクリーンのイベントをスタイラスのイベントと区別する場合などに使用できます。
イベントの発生元を取得します。
この入力デバイスがサポートする入力元を、複合ビットフィールドとして取得します。単一の入力デバイスに複数の入力元がある場合があるため、以下の定数と単純に比較するだけでは不十分であることに注意してください。
入力元はタッチスクリーンのポインティングデバイスです。
public static final int InputDevice.SOURCE_STYLUS
入力デバイスはスタイラスのポインティングデバイスです。
public static final int InputDevice.SOURCE_UNKNOWN
入力元は不明です。
Wacom Technology Corp.
バージョン 1.0 2013年