1 /* 2 * Copyright (C) 2010 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.view; 18 19 import android.os.Parcel; 20 import android.os.Parcelable; 21 22 import java.util.concurrent.atomic.AtomicInteger; 23 24 /** 25 * Common base class for input events. 26 */ 27 public abstract class InputEvent implements Parcelable { 28 /** @hide */ 29 protected static final int PARCEL_TOKEN_MOTION_EVENT = 1; 30 /** @hide */ 31 protected static final int PARCEL_TOKEN_KEY_EVENT = 2; 32 33 // Next sequence number. 34 private static final AtomicInteger mNextSeq = new AtomicInteger(); 35 36 /** @hide */ 37 protected int mSeq; 38 39 /** @hide */ 40 protected boolean mRecycled; 41 42 private static final boolean TRACK_RECYCLED_LOCATION = false; 43 private RuntimeException mRecycledLocation; 44 45 /*package*/ InputEvent() { 46 mSeq = mNextSeq.getAndIncrement(); 47 } 48 49 /** 50 * Gets the id for the device that this event came from. An id of 51 * zero indicates that the event didn't come from a physical device 52 * and maps to the default keymap. The other numbers are arbitrary and 53 * you shouldn't depend on the values. 54 * 55 * @return The device id. 56 * @see InputDevice#getDevice 57 */ 58 public abstract int getDeviceId(); 59 60 /** 61 * Gets the device that this event came from. 62 * 63 * @return The device, or null if unknown. 64 */ 65 public final InputDevice getDevice() { 66 return InputDevice.getDevice(getDeviceId()); 67 } 68 69 /** 70 * Gets the source of the event. 71 * 72 * @return The event source or {@link InputDevice#SOURCE_UNKNOWN} if unknown. 73 */ 74 public abstract int getSource(); 75 76 /** 77 * Modifies the source of the event. 78 * 79 * @param source The new source. 80 * @hide 81 */ 82 public abstract void setSource(int source); 83 84 /** 85 * Determines whether the event is from the given source. 86 * 87 * @param source The input source to check against. This can be a specific device type, such as 88 * {@link InputDevice#SOURCE_TOUCH_NAVIGATION}, or a more generic device class, such as 89 * {@link InputDevice#SOURCE_CLASS_POINTER}. 90 * @return Whether the event is from the given source. 91 */ 92 public boolean isFromSource(int source) { 93 return (getSource() & source) == source; 94 } 95 96 /** 97 * Copies the event. 98 * 99 * @return A deep copy of the event. 100 * @hide 101 */ 102 public abstract InputEvent copy(); 103 104 /** 105 * Recycles the event. 106 * This method should only be used by the system since applications do not 107 * expect {@link KeyEvent} objects to be recycled, although {@link MotionEvent} 108 * objects are fine. See {@link KeyEvent#recycle()} for details. 109 * @hide 110 */ 111 public void recycle() { 112 if (TRACK_RECYCLED_LOCATION) { 113 if (mRecycledLocation != null) { 114 throw new RuntimeException(toString() + " recycled twice!", mRecycledLocation); 115 } 116 mRecycledLocation = new RuntimeException("Last recycled here"); 117 } else { 118 if (mRecycled) { 119 throw new RuntimeException(toString() + " recycled twice!"); 120 } 121 mRecycled = true; 122 } 123 } 124 125 /** 126 * Conditionally recycled the event if it is appropriate to do so after 127 * dispatching the event to an application. 128 * 129 * If the event is a {@link MotionEvent} then it is recycled. 130 * 131 * If the event is a {@link KeyEvent} then it is NOT recycled, because applications 132 * expect key events to be immutable so once the event has been dispatched to 133 * the application we can no longer recycle it. 134 * @hide 135 */ 136 public void recycleIfNeededAfterDispatch() { 137 recycle(); 138 } 139 140 /** 141 * Reinitializes the event on reuse (after recycling). 142 * @hide 143 */ 144 protected void prepareForReuse() { 145 mRecycled = false; 146 mRecycledLocation = null; 147 mSeq = mNextSeq.getAndIncrement(); 148 } 149 150 /** 151 * Gets a private flag that indicates when the system has detected that this input event 152 * may be inconsistent with respect to the sequence of previously delivered input events, 153 * such as when a key up event is sent but the key was not down or when a pointer 154 * move event is sent but the pointer is not down. 155 * 156 * @return True if this event is tainted. 157 * @hide 158 */ 159 public abstract boolean isTainted(); 160 161 /** 162 * Sets a private flag that indicates when the system has detected that this input event 163 * may be inconsistent with respect to the sequence of previously delivered input events, 164 * such as when a key up event is sent but the key was not down or when a pointer 165 * move event is sent but the pointer is not down. 166 * 167 * @param tainted True if this event is tainted. 168 * @hide 169 */ 170 public abstract void setTainted(boolean tainted); 171 172 /** 173 * Retrieve the time this event occurred, 174 * in the {@link android.os.SystemClock#uptimeMillis} time base. 175 * 176 * @return Returns the time this event occurred, 177 * in the {@link android.os.SystemClock#uptimeMillis} time base. 178 */ 179 public abstract long getEventTime(); 180 181 /** 182 * Retrieve the time this event occurred, 183 * in the {@link android.os.SystemClock#uptimeMillis} time base but with 184 * nanosecond (instead of millisecond) precision. 185 * <p> 186 * The value is in nanosecond precision but it may not have nanosecond accuracy. 187 * </p> 188 * 189 * @return Returns the time this event occurred, 190 * in the {@link android.os.SystemClock#uptimeMillis} time base but with 191 * nanosecond (instead of millisecond) precision. 192 * 193 * @hide 194 */ 195 public abstract long getEventTimeNano(); 196 197 /** 198 * Gets the unique sequence number of this event. 199 * Every input event that is created or received by a process has a 200 * unique sequence number. Moreover, a new sequence number is obtained 201 * each time an event object is recycled. 202 * 203 * Sequence numbers are only guaranteed to be locally unique within a process. 204 * Sequence numbers are not preserved when events are parceled. 205 * 206 * @return The unique sequence number of this event. 207 * @hide 208 */ 209 public int getSequenceNumber() { 210 return mSeq; 211 } 212 213 public int describeContents() { 214 return 0; 215 } 216 217 public static final Parcelable.Creator<InputEvent> CREATOR 218 = new Parcelable.Creator<InputEvent>() { 219 public InputEvent createFromParcel(Parcel in) { 220 int token = in.readInt(); 221 if (token == PARCEL_TOKEN_KEY_EVENT) { 222 return KeyEvent.createFromParcelBody(in); 223 } else if (token == PARCEL_TOKEN_MOTION_EVENT) { 224 return MotionEvent.createFromParcelBody(in); 225 } else { 226 throw new IllegalStateException("Unexpected input event type token in parcel."); 227 } 228 } 229 230 public InputEvent[] newArray(int size) { 231 return new InputEvent[size]; 232 } 233 }; 234 } 235