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];
        }
    };
}