Merge "Input API review." into gingerbread (24326f72) · Commits · e / os / android_frameworks_base

core/java/android/view/InputDevice.java

+3 −40

Original line number	Diff line number	Diff line
		@@ -28,8 +28,7 @@ import android.os.ServiceManager;
		* keyboard may compose the capabilities of a standard keyboard together with a track pad mouse
		* or other pointing device.
		* </p><p>
		* Some input devices present multiple distinguishable sources of input. For example, a
		* game pad may have two analog joysticks, a directional pad and a full complement of buttons.
		* Some input devices present multiple distinguishable sources of input.
		* Applications can query the framework about the characteristics of each distinct source.
		* </p><p>
		* As a further wrinkle, different kinds of input sources uses different coordinate systems
		@@ -55,7 +54,7 @@ public final class InputDevice implements Parcelable {

		/**
		* The input source has buttons or keys.
		* Examples: {@link #SOURCE_KEYBOARD}, {@link #SOURCE_GAMEPAD}, {@link #SOURCE_DPAD}.
		* Examples: {@link #SOURCE_KEYBOARD}, {@link #SOURCE_DPAD}.
		*
		* A {@link KeyEvent} should be interpreted as a button or key press.
		*
		@@ -100,18 +99,6 @@ public final class InputDevice implements Parcelable {
		*/
		public static final int SOURCE_CLASS_POSITION = 0x00000008;

		/**
		* The input source is a joystick.
		*
		* A {@link KeyEvent} should be interpreted as a joystick button press.
		*
		* A {@link MotionEvent} should be interpreted in absolute coordinates as a joystick
		* position in normalized device-specific units nominally between -1.0 and 1.0.
		*
		* Use {@link #getMotionRange} to query the range and precision of motion.
		*/
		public static final int SOURCE_CLASS_JOYSTICK = 0x00000010;

		/**
		* The input source is unknown.
		*/
		@@ -131,13 +118,6 @@ public final class InputDevice implements Parcelable {
		*/
		public static final int SOURCE_DPAD = 0x00000200 \| SOURCE_CLASS_BUTTON;

		/**
		* The input source is a gamepad.
		*
		* @see #SOURCE_CLASS_BUTTON
		*/
		public static final int SOURCE_GAMEPAD = 0x00000400 \| SOURCE_CLASS_BUTTON;

		/**
		* The input source is a touch screen pointing device.
		*
		@@ -169,20 +149,6 @@ public final class InputDevice implements Parcelable {
		*/
		public static final int SOURCE_TOUCHPAD = 0x00100000 \| SOURCE_CLASS_POSITION;

		/**
		* The input source is a joystick mounted on the left or is a standalone joystick.
		*
		* @see #SOURCE_CLASS_JOYSTICK
		*/
		public static final int SOURCE_JOYSTICK_LEFT = 0x01000000 \| SOURCE_CLASS_JOYSTICK;

		/**
		* The input source is a joystick mounted on the right.
		*
		* @see #SOURCE_CLASS_JOYSTICK
		*/
		public static final int SOURCE_JOYSTICK_RIGHT = 0x02000000 \| SOURCE_CLASS_JOYSTICK;

		/**
		* A special input source constant that is used when filtering input devices
		* to match devices that provide any type of input source.
		@@ -411,7 +377,7 @@ public final class InputDevice implements Parcelable {
		/**
		* Gets the extent of the center flat position with respect to this coordinate.
		* For example, a flat value of 8 means that the center position is between -8 and +8.
		* This value is mainly useful for calibrating joysticks.
		* This value is mainly useful for calibrating self-centering devices.
		* @return The extent of the center flat position.
		*/
		public float getFlat() {
		@@ -506,13 +472,10 @@ public final class InputDevice implements Parcelable {
		description.append(" Sources:");
		appendSourceDescriptionIfApplicable(description, SOURCE_KEYBOARD, "keyboard");
		appendSourceDescriptionIfApplicable(description, SOURCE_DPAD, "dpad");
		appendSourceDescriptionIfApplicable(description, SOURCE_GAMEPAD, "gamepad");
		appendSourceDescriptionIfApplicable(description, SOURCE_TOUCHSCREEN, "touchscreen");
		appendSourceDescriptionIfApplicable(description, SOURCE_MOUSE, "mouse");
		appendSourceDescriptionIfApplicable(description, SOURCE_TRACKBALL, "trackball");
		appendSourceDescriptionIfApplicable(description, SOURCE_TOUCHPAD, "touchpad");
		appendSourceDescriptionIfApplicable(description, SOURCE_JOYSTICK_LEFT, "joystick_left");
		appendSourceDescriptionIfApplicable(description, SOURCE_JOYSTICK_RIGHT, "joystick_right");
		description.append("\n");

		appendRangeDescriptionIfApplicable(description, MOTION_RANGE_X, "x");

core/java/android/view/KeyEvent.java

+187 −2

Original line number	Diff line number	Diff line
		@@ -24,120 +24,305 @@ import android.view.KeyCharacterMap;
		import android.view.KeyCharacterMap.KeyData;

		/**
		* Contains constants for key events.
		* Object used to report key and button events.
		* <p>
		* Each key press is described by a sequence of key events. A key press
		* starts with a key event with {@link #ACTION_DOWN}. If the key is held
		* sufficiently long that it repeats, then the initial down is followed
		* additional key events with {@link #ACTION_DOWN} and a non-zero value for
		* {@link #getRepeatCount()}. The last key event is a {@link #ACTION_UP}
		* for the key up. If the key press is canceled, the key up event will have the
		* {@link #FLAG_CANCELED} flag set.
		* </p><p>
		* Key events are generally accompanied by a key code ({@link #getKeyCode()}),
		* scan code ({@link #getScanCode()}) and meta state ({@link #getMetaState()}).
		* Key code constants are defined in this class. Scan code constants are raw
		* device-specific codes obtained from the OS and so are not generally meaningful
		* to applications unless interpreted using the {@link KeyCharacterMap}.
		* Meta states describe the pressed state of key modifiers
		* such as {@link #META_SHIFT_ON} or {@link #META_ALT_ON}.
		* </p><p>
		* When interacting with an IME, the framework may deliver key events
		* with the special action {@link #ACTION_MULTIPLE} that either specifies
		* that single repeated key code or a sequence of characters to insert.
		* </p><p>
		* In general, the framework makes no guarantees that the key events delivered
		* to a view constitute a complete key press. In particular, there is no
		* guarantee that a view will always receive a key event with {@link #ACTION_UP}
		* for each {@link #ACTION_DOWN} that was delivered.
		* </p><p>
		* Refer to {@link InputDevice} for more information about how different kinds of
		* input devices and sources represent keys and buttons.
		* </p>
		*/
		public class KeyEvent extends InputEvent implements Parcelable {
		// key codes
		/** Key code constant: Unknown key code. */
		public static final int KEYCODE_UNKNOWN = 0;
		/** Key code constant: Soft Left key.
		* Usually situated below the display on phones and used as a multi-function
		* feature key for selecting a software defined function shown on the bottom left
		* of the display. */
		public static final int KEYCODE_SOFT_LEFT = 1;
		/** Key code constant: Soft Right key.
		* Usually situated below the display on phones and used as a multi-function
		* feature key for selecting a software defined function shown on the bottom right
		* of the display. */
		public static final int KEYCODE_SOFT_RIGHT = 2;
		/** Key code constant: Home key.
		* This key is handled by the framework and is never delivered to applications. */
		public static final int KEYCODE_HOME = 3;
		/** Key code constant: Back key. */
		public static final int KEYCODE_BACK = 4;
		/** Key code constant: Call key. */
		public static final int KEYCODE_CALL = 5;
		/** Key code constant: End Call key. */
		public static final int KEYCODE_ENDCALL = 6;
		/** Key code constant: '0' key. */
		public static final int KEYCODE_0 = 7;
		/** Key code constant: '1' key. */
		public static final int KEYCODE_1 = 8;
		/** Key code constant: '2' key. */
		public static final int KEYCODE_2 = 9;
		/** Key code constant: '3' key. */
		public static final int KEYCODE_3 = 10;
		/** Key code constant: '4' key. */
		public static final int KEYCODE_4 = 11;
		/** Key code constant: '5' key. */
		public static final int KEYCODE_5 = 12;
		/** Key code constant: '6' key. */
		public static final int KEYCODE_6 = 13;
		/** Key code constant: '7' key. */
		public static final int KEYCODE_7 = 14;
		/** Key code constant: '8' key. */
		public static final int KEYCODE_8 = 15;
		/** Key code constant: '9' key. */
		public static final int KEYCODE_9 = 16;
		/** Key code constant: '' key. /
		public static final int KEYCODE_STAR = 17;
		/** Key code constant: '#' key. */
		public static final int KEYCODE_POUND = 18;
		/** Key code constant: Directional Pad Up key.
		* May also be synthesized from trackball motions. */
		public static final int KEYCODE_DPAD_UP = 19;
		/** Key code constant: Directional Pad Down key.
		* May also be synthesized from trackball motions. */
		public static final int KEYCODE_DPAD_DOWN = 20;
		/** Key code constant: Directional Pad Left key.
		* May also be synthesized from trackball motions. */
		public static final int KEYCODE_DPAD_LEFT = 21;
		/** Key code constant: Directional Pad Right key.
		* May also be synthesized from trackball motions. */
		public static final int KEYCODE_DPAD_RIGHT = 22;
		/** Key code constant: Directional Pad Center key.
		* May also be synthesized from trackball motions. */
		public static final int KEYCODE_DPAD_CENTER = 23;
		/** Key code constant: Volume Up key. */
		public static final int KEYCODE_VOLUME_UP = 24;
		/** Key code constant: Volume Down key. */
		public static final int KEYCODE_VOLUME_DOWN = 25;
		/** Key code constant: Power key. */
		public static final int KEYCODE_POWER = 26;
		/** Key code constant: Camera key.
		* Used to launch a camera application or take pictures. */
		public static final int KEYCODE_CAMERA = 27;
		/** Key code constant: Clear key. */
		public static final int KEYCODE_CLEAR = 28;
		/** Key code constant: 'A' key. */
		public static final int KEYCODE_A = 29;
		/** Key code constant: 'B' key. */
		public static final int KEYCODE_B = 30;
		/** Key code constant: 'C' key. */
		public static final int KEYCODE_C = 31;
		/** Key code constant: 'D' key. */
		public static final int KEYCODE_D = 32;
		/** Key code constant: 'E' key. */
		public static final int KEYCODE_E = 33;
		/** Key code constant: 'F' key. */
		public static final int KEYCODE_F = 34;
		/** Key code constant: 'G' key. */
		public static final int KEYCODE_G = 35;
		/** Key code constant: 'H' key. */
		public static final int KEYCODE_H = 36;
		/** Key code constant: 'I' key. */
		public static final int KEYCODE_I = 37;
		/** Key code constant: 'J' key. */
		public static final int KEYCODE_J = 38;
		/** Key code constant: 'K' key. */
		public static final int KEYCODE_K = 39;
		/** Key code constant: 'L' key. */
		public static final int KEYCODE_L = 40;
		/** Key code constant: 'M' key. */
		public static final int KEYCODE_M = 41;
		/** Key code constant: 'N' key. */
		public static final int KEYCODE_N = 42;
		/** Key code constant: 'O' key. */
		public static final int KEYCODE_O = 43;
		/** Key code constant: 'P' key. */
		public static final int KEYCODE_P = 44;
		/** Key code constant: 'Q' key. */
		public static final int KEYCODE_Q = 45;
		/** Key code constant: 'R' key. */
		public static final int KEYCODE_R = 46;
		/** Key code constant: 'S' key. */
		public static final int KEYCODE_S = 47;
		/** Key code constant: 'T' key. */
		public static final int KEYCODE_T = 48;
		/** Key code constant: 'U' key. */
		public static final int KEYCODE_U = 49;
		/** Key code constant: 'V' key. */
		public static final int KEYCODE_V = 50;
		/** Key code constant: 'W' key. */
		public static final int KEYCODE_W = 51;
		/** Key code constant: 'X' key. */
		public static final int KEYCODE_X = 52;
		/** Key code constant: 'Y' key. */
		public static final int KEYCODE_Y = 53;
		/** Key code constant: 'Z' key. */
		public static final int KEYCODE_Z = 54;
		/** Key code constant: ',' key. */
		public static final int KEYCODE_COMMA = 55;
		/** Key code constant: '.' key. */
		public static final int KEYCODE_PERIOD = 56;
		/** Key code constant: Left Alt modifier key. */
		public static final int KEYCODE_ALT_LEFT = 57;
		/** Key code constant: Right Alt modifier key. */
		public static final int KEYCODE_ALT_RIGHT = 58;
		/** Key code constant: Left Shift modifier key. */
		public static final int KEYCODE_SHIFT_LEFT = 59;
		/** Key code constant: Right Shift modifier key. */
		public static final int KEYCODE_SHIFT_RIGHT = 60;
		/** Key code constant: Tab key. */
		public static final int KEYCODE_TAB = 61;
		/** Key code constant: Space key. */
		public static final int KEYCODE_SPACE = 62;
		/** Key code constant: Symbol modifier key. */
		public static final int KEYCODE_SYM = 63;
		/** Key code constant: Explorer special function key.
		* Used to launch a browser application. */
		public static final int KEYCODE_EXPLORER = 64;
		/** Key code constant: Envelope special function key.
		* Used to launch a mail application. */
		public static final int KEYCODE_ENVELOPE = 65;
		/** Key code constant: Enter key. */
		public static final int KEYCODE_ENTER = 66;
		/** Key code constant: Delete key. */
		public static final int KEYCODE_DEL = 67;
		/** Key code constant: '`' (backtick) key. */
		public static final int KEYCODE_GRAVE = 68;
		/** Key code constant: '-'. */
		public static final int KEYCODE_MINUS = 69;
		/** Key code constant: '=' key. */
		public static final int KEYCODE_EQUALS = 70;
		/** Key code constant: '[' key. */
		public static final int KEYCODE_LEFT_BRACKET = 71;
		/** Key code constant: ']' key. */
		public static final int KEYCODE_RIGHT_BRACKET = 72;
		/** Key code constant: '\' key. */
		public static final int KEYCODE_BACKSLASH = 73;
		/** Key code constant: ';' key. */
		public static final int KEYCODE_SEMICOLON = 74;
		/** Key code constant: ''' (apostrophe) key. */
		public static final int KEYCODE_APOSTROPHE = 75;
		/** Key code constant: '/' key. */
		public static final int KEYCODE_SLASH = 76;
		/** Key code constant: '@' key. */
		public static final int KEYCODE_AT = 77;
		/** Key code constant: Number Lock modifier key. */
		public static final int KEYCODE_NUM = 78;
		/** Key code constant: Headset Hook key.
		* Used to hang up calls and stop media. */
		public static final int KEYCODE_HEADSETHOOK = 79;
		/** Key code constant: Camera Focus key.
		* Used to focus the camera. */
		public static final int KEYCODE_FOCUS = 80; // Camera focus
		/** Key code constant: '+' key. */
		public static final int KEYCODE_PLUS = 81;
		/** Key code constant: Menu key. */
		public static final int KEYCODE_MENU = 82;
		/** Key code constant: Notification key. */
		public static final int KEYCODE_NOTIFICATION = 83;
		/** Key code constant: Search key. */
		public static final int KEYCODE_SEARCH = 84;
		/** Key code constant: Play/Pause media key. */
		public static final int KEYCODE_MEDIA_PLAY_PAUSE= 85;
		/** Key code constant: Stop media key. */
		public static final int KEYCODE_MEDIA_STOP = 86;
		/** Key code constant: Play Next media key. */
		public static final int KEYCODE_MEDIA_NEXT = 87;
		/** Key code constant: Play Previous media key. */
		public static final int KEYCODE_MEDIA_PREVIOUS = 88;
		/** Key code constant: Rewind media key. */
		public static final int KEYCODE_MEDIA_REWIND = 89;
		/** Key code constant: Fast Forward media key. */
		public static final int KEYCODE_MEDIA_FAST_FORWARD = 90;
		/** Key code constant: Mute key. */
		public static final int KEYCODE_MUTE = 91;
		/** Key code constant: Page Up key. */
		public static final int KEYCODE_PAGE_UP = 92;
		/** Key code constant: Page Down key. */
		public static final int KEYCODE_PAGE_DOWN = 93;
		/** Key code constant: Picture Symbols modifier key.
		* Used to switch symbol sets (Emoji, Kao-moji). */
		public static final int KEYCODE_PICTSYMBOLS = 94; // switch symbol-sets (Emoji,Kao-moji)
		/** Key code constant: Switch Charset modifier key.
		* Used to switch character sets (Kanji, Katakana). */
		public static final int KEYCODE_SWITCH_CHARSET = 95; // switch char-sets (Kanji,Katakana)
		/** Key code constant: A Button key.
		* On a game controller, the A button should be either the button labeled A
		* or the first button on the upper row of controller buttons. */
		public static final int KEYCODE_BUTTON_A = 96;
		/** Key code constant: B Button key.
		* On a game controller, the B button should be either the button labeled B
		* or the second button on the upper row of controller buttons. */
		public static final int KEYCODE_BUTTON_B = 97;
		/** Key code constant: C Button key.
		* On a game controller, the C button should be either the button labeled C
		* or the third button on the upper row of controller buttons. */
		public static final int KEYCODE_BUTTON_C = 98;
		/** Key code constant: X Button key.
		* On a game controller, the X button should be either the button labeled X
		* or the first button on the lower row of controller buttons. */
		public static final int KEYCODE_BUTTON_X = 99;
		/** Key code constant: Y Button key.
		* On a game controller, the Y button should be either the button labeled Y
		* or the second button on the lower row of controller buttons. */
		public static final int KEYCODE_BUTTON_Y = 100;
		/** Key code constant: Z Button key.
		* On a game controller, the Z button should be either the button labeled Z
		* or the third button on the lower row of controller buttons. */
		public static final int KEYCODE_BUTTON_Z = 101;
		/** Key code constant: L1 Button key.
		* On a game controller, the L1 button should be either the button labeled L1 (or L)
		* or the top left trigger button. */
		public static final int KEYCODE_BUTTON_L1 = 102;
		/** Key code constant: R1 Button key.
		* On a game controller, the R1 button should be either the button labeled R1 (or R)
		* or the top right trigger button. */
		public static final int KEYCODE_BUTTON_R1 = 103;
		/** Key code constant: L2 Button key.
		* On a game controller, the L2 button should be either the button labeled L2
		* or the bottom left trigger button. */
		public static final int KEYCODE_BUTTON_L2 = 104;
		/** Key code constant: R2 Button key.
		* On a game controller, the R2 button should be either the button labeled R2
		* or the bottom right trigger button. */
		public static final int KEYCODE_BUTTON_R2 = 105;
		/** Key code constant: Left Thumb Button key.
		* On a game controller, the left thumb button indicates that the left (or only)
		* joystick is pressed. */
		public static final int KEYCODE_BUTTON_THUMBL = 106;
		/** Key code constant: Right Thumb Button key.
		* On a game controller, the right thumb button indicates that the right
		* joystick is pressed. */
		public static final int KEYCODE_BUTTON_THUMBR = 107;
		/** Key code constant: Start Button key.
		* On a game controller, the button labeled Start. */
		public static final int KEYCODE_BUTTON_START = 108;
		/** Key code constant: Select Button key.
		* On a game controller, the button labeled Select. */
		public static final int KEYCODE_BUTTON_SELECT = 109;
		/** Key code constant: Mode Button key.
		* On a game controller, the button labeled Mode. */
		public static final int KEYCODE_BUTTON_MODE = 110;

		// NOTE: If you add a new keycode here you must also add it to:

core/java/android/view/MotionEvent.java

+64 −2

Original line number	Diff line number	Diff line
		@@ -24,9 +24,71 @@ import android.os.SystemClock;
		* Object used to report movement (mouse, pen, finger, trackball) events. This
		* class may hold either absolute or relative movements, depending on what
		* it is being used for.
		*
		* Refer to {@link InputDevice} for information about how different kinds of
		* <p>
		* On pointing devices such as touch screens, pointer coordinates specify absolute
		* positions such as view X/Y coordinates. Each complete gesture is represented
		* by a sequence of motion events with actions that describe pointer state transitions
		* and movements. A gesture starts with a motion event with {@link #ACTION_DOWN}
		* that provides the location of the first pointer down. As each additional
		* pointer that goes down or up, the framework will generate a motion event with
		* {@link #ACTION_POINTER_DOWN} or {@link #ACTION_POINTER_UP} accordingly.
		* Pointer movements are described by motion events with {@link #ACTION_MOVE}.
		* Finally, a gesture end either when the final pointer goes up as represented
		* by a motion event with {@link #ACTION_UP} or when gesture is canceled
		* with {@link #ACTION_CANCEL}.
		* </p><p>
		* On trackballs, the pointer coordinates specify relative movements as X/Y deltas.
		* A trackball gesture consists of a sequence of movements described by motion
		* events with {@link #ACTION_MOVE} interspersed with occasional {@link #ACTION_DOWN}
		* or {@link #ACTION_UP} motion events when the trackball button is pressed or released.
		* </p><p>
		* Motion events always report movements for all pointers at once. The number
		* of pointers only ever changes by one as individual pointers go up and down,
		* except when the gesture is canceled.
		* </p><p>
		* The order in which individual pointers appear within a motion event can change
		* from one event to the next. Use the {@link #getPointerId(int)} method to obtain a
		* pointer id to track pointers across motion events in a gesture. Then for
		* successive motion events, use the {@link #findPointerIndex(int)} method to obtain
		* the pointer index for a given pointer id in that motion event.
		* </p><p>
		* For efficiency, motion events with {@link #ACTION_MOVE} may batch together
		* multiple movement samples within a single object. The most current
		* pointer coordinates are available using {@link #getX(int)} and {@link #getY(int)}.
		* Earlier coordinates within the batch are accessed using {@link #getHistoricalX(int, int)}
		* and {@link #getHistoricalY(int, int)}. The coordinates are "historical" only
		* insofar as they are older than the current coordinates in the batch; however,
		* they are still distinct from any other coordinates reported in prior motion events.
		* To process all coordinates in the batch in time order, first consume the historical
		* coordinates then consume the current coordinates.
		* </p><p>
		* Example: Consuming all samples for all pointers in a motion event in time order.
		* </p><p><pre><code>
		* void printSamples(MotionEvent ev) {
		* final int historySize = ev.getHistorySize();
		* final int pointerCount = ev.getPointerCount();
		* for (int h = 0; h < historySize; h++) {
		* System.out.printf("At time %d:", ev.getHistoricalEventTime(h));
		* for (int p = 0; p < pointerCount; p++) {
		* System.out.printf(" pointer %d: (%f,%f)",
		* ev.getPointerId(p), ev.getHistoricalX(p, h), ev.getHistoricalY(p, h));
		* }
		* }
		* System.out.printf("At time %d:", ev.getEventTime());
		* for (int p = 0; p < pointerCount; p++) {
		* System.out.printf(" pointer %d: (%f,%f)",
		* ev.getPointerId(p), ev.getX(p), ev.getY(p));
		* }
		* }
		* </code></pre></p><p>
		* In general, the framework makes no guarantees that the motion events delivered
		* to a view constitute a complete gesture. In particular, there is no
		* guarantee that a view will always receive a motion event with {@link #ACTION_UP}
		* for each {@link #ACTION_DOWN} that was delivered.
		* </p><p>
		* Refer to {@link InputDevice} for more information about how different kinds of
		* input devices and sources represent pointer coordinates.
		* </p>
		*/
		public final class MotionEvent extends InputEvent implements Parcelable {
		private static final long MS_PER_NS = 1000000;

include/ui/EventHub.h

+2 −2

Original line number	Diff line number	Diff line
		@@ -111,10 +111,10 @@ enum {
		/* The input device is a multi-touch touchscreen. */
		INPUT_DEVICE_CLASS_TOUCHSCREEN_MT= 0x00000010,

		/* The input device is a directional pad. */
		/* The input device is a directional pad (implies keyboard, has DPAD keys). */
		INPUT_DEVICE_CLASS_DPAD = 0x00000020,

		/* The input device is a gamepad (implies keyboard). */
		/* The input device is a gamepad (implies keyboard, has BUTTON keys). */
		INPUT_DEVICE_CLASS_GAMEPAD = 0x00000040,

		/* The input device has switches. */

libs/ui/InputReader.cpp

+0 −3

File changed.

Preview size limit exceeded, changes collapsed.