Home | History | Annotate | Download | only in view
      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      * @see InputDevice#getSources
     74      */
     75     public abstract int getSource();
     76 
     77     /**
     78      * Modifies the source of the event.
     79      *
     80      * @param source The new source.
     81      * @hide
     82      */
     83     public abstract void setSource(int source);
     84 
     85     /**
     86      * Determines whether the event is from the given source.
     87      *
     88      * @param source The input source to check against. This can be a specific device type, such as
     89      * {@link InputDevice#SOURCE_TOUCH_NAVIGATION}, or a more generic device class, such as
     90      * {@link InputDevice#SOURCE_CLASS_POINTER}.
     91      * @return Whether the event is from the given source.
     92      */
     93     public boolean isFromSource(int source) {
     94         return (getSource() & source) == source;
     95     }
     96 
     97     /**
     98      * Copies the event.
     99      *
    100      * @return A deep copy of the event.
    101      * @hide
    102      */
    103     public abstract InputEvent copy();
    104 
    105     /**
    106      * Recycles the event.
    107      * This method should only be used by the system since applications do not
    108      * expect {@link KeyEvent} objects to be recycled, although {@link MotionEvent}
    109      * objects are fine.  See {@link KeyEvent#recycle()} for details.
    110      * @hide
    111      */
    112     public void recycle() {
    113         if (TRACK_RECYCLED_LOCATION) {
    114             if (mRecycledLocation != null) {
    115                 throw new RuntimeException(toString() + " recycled twice!", mRecycledLocation);
    116             }
    117             mRecycledLocation = new RuntimeException("Last recycled here");
    118         } else {
    119             if (mRecycled) {
    120                 throw new RuntimeException(toString() + " recycled twice!");
    121             }
    122             mRecycled = true;
    123         }
    124     }
    125 
    126     /**
    127      * Conditionally recycled the event if it is appropriate to do so after
    128      * dispatching the event to an application.
    129      *
    130      * If the event is a {@link MotionEvent} then it is recycled.
    131      *
    132      * If the event is a {@link KeyEvent} then it is NOT recycled, because applications
    133      * expect key events to be immutable so once the event has been dispatched to
    134      * the application we can no longer recycle it.
    135      * @hide
    136      */
    137     public void recycleIfNeededAfterDispatch() {
    138         recycle();
    139     }
    140 
    141     /**
    142      * Reinitializes the event on reuse (after recycling).
    143      * @hide
    144      */
    145     protected void prepareForReuse() {
    146         mRecycled = false;
    147         mRecycledLocation = null;
    148         mSeq = mNextSeq.getAndIncrement();
    149     }
    150 
    151     /**
    152      * Gets a private flag that indicates when the system has detected that this input event
    153      * may be inconsistent with respect to the sequence of previously delivered input events,
    154      * such as when a key up event is sent but the key was not down or when a pointer
    155      * move event is sent but the pointer is not down.
    156      *
    157      * @return True if this event is tainted.
    158      * @hide
    159      */
    160     public abstract boolean isTainted();
    161 
    162     /**
    163      * Sets a private flag that indicates when the system has detected that this input event
    164      * may be inconsistent with respect to the sequence of previously delivered input events,
    165      * such as when a key up event is sent but the key was not down or when a pointer
    166      * move event is sent but the pointer is not down.
    167      *
    168      * @param tainted True if this event is tainted.
    169      * @hide
    170      */
    171     public abstract void setTainted(boolean tainted);
    172 
    173     /**
    174      * Retrieve the time this event occurred,
    175      * in the {@link android.os.SystemClock#uptimeMillis} time base.
    176      *
    177      * @return Returns the time this event occurred,
    178      * in the {@link android.os.SystemClock#uptimeMillis} time base.
    179      */
    180     public abstract long getEventTime();
    181 
    182     /**
    183      * Retrieve the time this event occurred,
    184      * in the {@link android.os.SystemClock#uptimeMillis} time base but with
    185      * nanosecond (instead of millisecond) precision.
    186      * <p>
    187      * The value is in nanosecond precision but it may not have nanosecond accuracy.
    188      * </p>
    189      *
    190      * @return Returns the time this event occurred,
    191      * in the {@link android.os.SystemClock#uptimeMillis} time base but with
    192      * nanosecond (instead of millisecond) precision.
    193      *
    194      * @hide
    195      */
    196     public abstract long getEventTimeNano();
    197 
    198     /**
    199      * Gets the unique sequence number of this event.
    200      * Every input event that is created or received by a process has a
    201      * unique sequence number.  Moreover, a new sequence number is obtained
    202      * each time an event object is recycled.
    203      *
    204      * Sequence numbers are only guaranteed to be locally unique within a process.
    205      * Sequence numbers are not preserved when events are parceled.
    206      *
    207      * @return The unique sequence number of this event.
    208      * @hide
    209      */
    210     public int getSequenceNumber() {
    211         return mSeq;
    212     }
    213 
    214     public int describeContents() {
    215         return 0;
    216     }
    217 
    218     public static final Parcelable.Creator<InputEvent> CREATOR
    219             = new Parcelable.Creator<InputEvent>() {
    220         public InputEvent createFromParcel(Parcel in) {
    221             int token = in.readInt();
    222             if (token == PARCEL_TOKEN_KEY_EVENT) {
    223                 return KeyEvent.createFromParcelBody(in);
    224             } else if (token == PARCEL_TOKEN_MOTION_EVENT) {
    225                 return MotionEvent.createFromParcelBody(in);
    226             } else {
    227                 throw new IllegalStateException("Unexpected input event type token in parcel.");
    228             }
    229         }
    230 
    231         public InputEvent[] newArray(int size) {
    232             return new InputEvent[size];
    233         }
    234     };
    235 }
    236