InputEvent .java

/**
 * 注释翻译 by 耀威 on 2016-01-08.
 */

<pre name="code" class="java">package android.view;

import android.os.Parcel;
import android.os.Parcelable;

import java.util.concurrent.atomic.AtomicInteger;

/**
 * 输入事件的共同基类
 */
public abstract class InputEvent implements Parcelable {
    /** @hide */
    protected static final int PARCEL_TOKEN_MOTION_EVENT = 1;
    /** @hide */
    protected static final int PARCEL_TOKEN_KEY_EVENT = 2;

    // 下一个序列号
    private static final AtomicInteger mNextSeq = new AtomicInteger();

    /** @hide */
    protected int mSeq;

    /** @hide */
    protected boolean mRecycled;

    private static final boolean TRACK_RECYCLED_LOCATION = false;
    private RuntimeException mRecycledLocation;

    /*package*/ InputEvent() {
        mSeq = mNextSeq.getAndIncrement();
    }

    /**
     * 得到事件源的设备ID。  An id of
     * id为0表示时间不是来自物理设备或键盘。
     * 其他的非零数字只能作为参考，不应该依赖。
     *
     * @return 设备id.
     * @see InputDevice#getDevice
     */
    public abstract int getDeviceId();

    /**
     * 得到事件源设备
     *
     * @return 设备, 如果未知返回null。.
     */
    public final InputDevice getDevice() {
        return InputDevice.getDevice(getDeviceId());
    }

    /**
     * 得到事件源.
     *
     * @return 事件源or {@link InputDevice#SOURCE_UNKNOWN} if unknown.
     * @see InputDevice#getSources
     */
    public abstract int getSource();

    /**
     * 改变事件源.
     *
     * @param source 新的事件源.
     * @hide
     */
    public abstract void setSource(int source);

    /**
     * 判断事件是否来自给定的事件源.
     *
     * @param source 被检查的事件源. 可能是一个特定的设备类型, 例如
     * {@link InputDevice#SOURCE_TOUCH_NAVIGATION},或者更普通的设备class, 例如
     * {@link InputDevice#SOURCE_CLASS_POINTER}.
     * @return Whether the event is from the given source.
     */
    public boolean isFromSource(int source) {
        return (getSource() & source) == source;
    }

    /**
     * 复制事件.
     *
     * @return 事件的深层副本.
     * @hide
     */
    public abstract InputEvent copy();

    /**
     * 回收事件.
     * 此方法之被系统调用。当应用不再使用需要被回收的可能能用到的 {@link KeyEvent} 对象,
     *  即使{@link MotionEvent}对象是有用的。
     *  See {@link KeyEvent#recycle()} for details.
     * @hide
     */
    public void recycle() {
        if (TRACK_RECYCLED_LOCATION) {
            if (mRecycledLocation != null) {
                throw new RuntimeException(toString() + " recycled twice!", mRecycledLocation);
            }
            mRecycledLocation = new RuntimeException("Last recycled here");
        } else {
            if (mRecycled) {
                throw new RuntimeException(toString() + " recycled twice!");
            }
            mRecycled = true;
        }
    }

    /**
     *分发应用的时间之后，如果合适，有条件的回收事件
     *如果事件是一个  {@link MotionEvent} ，他需要被回收.
     * 如果事件是一个 {@link KeyEvent} ，他不需要被回收, 因为应用表示的
     *  key events是不变的，因此一旦事件被应用分发，我们不再回收他。
     * @hide
     */
    public void recycleIfNeededAfterDispatch() {
        recycle();
    }

    /**
     * 重新初始化重用的事件 (在回收之后).
     * @hide
     */
    protected void prepareForReuse() {
        mRecycled = false;
        mRecycledLocation = null;
        mSeq = mNextSeq.getAndIncrement();
    }

    /**
     * 判断一个私有的标识，表明系统分发的事件与先前分发的事件序列不一致 ,
     * 比如当 a key up event is sent but the key was not down or when a pointer
     * move event is sent but the pointer is not down.
     *
     * @return True if this event is tainted变质.
     * @hide
     */
    public abstract boolean isTainted();

    /**
     * 设置一个私有的标识表明系统分发的事件与先前分发的事件序列不一致 ,
     * such as when a key up event is sent but the key was not down or when a pointer
     * move event is sent but the pointer is not down.
     *
     * @param tainted True if this event is tainted。
     * @hide
     */
    public abstract void setTainted(boolean tainted);

    /**
     *检索事件发生了的时间
     * 以 {@link android.os.SystemClock#uptimeMillis} 为事件基准.
     *
     * @return 返回事件发生的时间,
     * in the {@link android.os.SystemClock#uptimeMillis} time base.
     */
    public abstract long getEventTime();

    /**
     *检索事件发生了的时间
     * 以 {@link android.os.SystemClock#uptimeMillis} 为时间基准， 但是以
     * 纳秒(而不是毫秒) 为时间精度.
     * <p>
     * 值是以纳秒精度值，但可能没有纳秒精度.
     * </p>
     *
     * @return Returns the time this event occurred,
     * in the {@link android.os.SystemClock#uptimeMillis} time base but with
     * nanosecond (instead of millisecond) precision.
     *
     * @hide
     */
    public abstract long getEventTimeNano();

    /**
     * 标记被取消的输入事件.
     *
     * @hide
     */
    public abstract void cancel();

    /**
     * 得到事件独有的序列号.
     * 每一个被创建的或被进程接收的事件都有一个独有的序列号.
     * 此外，每次事件对象被回收会获得一个新的序列号
     *
     * Sequence numbers are only guaranteed to be locally unique within a process.
     * Sequence numbers are not preserved when events are parceled.
     *
     * @return The unique sequence number of this event.
     * @hide
     */
    public int getSequenceNumber() {
        return mSeq;
    }

    public int describeContents() {
        return 0;
    }

    public static final Parcelable.Creator<InputEvent> CREATOR
            = new Parcelable.Creator<InputEvent>() {
        public InputEvent createFromParcel(Parcel in) {
            int token = in.readInt();
            if (token == PARCEL_TOKEN_KEY_EVENT) {
                return KeyEvent.createFromParcelBody(in);
            } else if (token == PARCEL_TOKEN_MOTION_EVENT) {
                return MotionEvent.createFromParcelBody(in);
            } else {
                throw new IllegalStateException("Unexpected input event type token in parcel.");
            }
        }

        public InputEvent[] newArray(int size) {
            return new InputEvent[size];
        }
    };
}