MotionEvent 概述

第一篇

  Object used to report movement (mouse, pen, finger, trackball) events.
  Motion events may hold either absolute or relative movements and other data,
  depending on the type of device.

MotionEvent用於呈現移動事件（鼠標、手寫筆、手指、追蹤器）事件。Motion events 可根據不同的設備類型，控制移動事件和其他數據。

Overview

簡介

 Motion events describe movements in terms of an action code and a set of axis values.
 The action code specifies the state change that occurred such as a pointer going
 down or up.  The axis values describe the position and other movement properties.

Motion Events 描述移動依據一個動作和一組坐標軸值。這個動作指示發生狀態改變比如指示器將要向下個或者上移動。這個軸值描述的是位置和其他移動屬性。

 For example, when the user first touches the screen, the system delivers a touch
 event to the appropriate {@link View} with the action code {@link #ACTION_DOWN}
 and a set of axis values that include the X and Y coordinates of the touch and
 information about the pressure, size and orientation of the contact area.

例如：當用戶第一次碰觸屏幕，系統是分派一個觸碰事件的操作碼給相應的控件，操作碼包含一組坐標軸值包含有X軸和Y軸觸碰和相關按壓的作用區域的尺寸和方向相關信息。

Some devices can report multiple movement traces at the same time.  Multi-touch
screens emit one movement trace for each finger.  The individual fingers or
other objects that generate movement traces are referred to as pointers.
Motion events contain information about all of the pointers that are currently active
even if some of them have not moved since the last event was delivered.

一些設備可以同時呈現多個移動軌跡，多個手指觸摸屏幕事件運動軌跡發出給每一根手指。每個獨立手指或其他對象被分配生成移動軌跡都引用指針事件包含所有相關信息，直到當前活動事件不移動為止。

The number of pointers only ever changes by one as individual pointers go up and down,
except when the gesture is canceled

多個指示器僅由單個手指改變向上和下，除非當手勢取消掉。

 Each pointer has a unique id that is assigned when it first goes down
 (indicated by {@link #ACTION_DOWN} or {@link #ACTION_POINTER_DOWN}).  A pointer id
 remains valid until the pointer eventually goes up (indicated by {@link #ACTION_UP}
 or {@link #ACTION_POINTER_UP}) or when the gesture is canceled (indicated by
 {@link #ACTION_CANCEL}).

每一個指示器觸發ACTION_DOWN會分配一個唯一的id，這個指示器一直有效直到ACTION_UP觸發或取消掉改手勢行為。

 The MotionEvent class provides many methods to query the position and other properties of
 pointers, such as {@link #getX(int)}, {@link #getY(int)}, {@link #getAxisValue},
 {@link #getPointerId(int)}, {@link #getToolType(int)}, and many others.  Most of these
 methods accept the pointer index as a parameter rather than the pointer id.
 The pointer index of each pointer in the event ranges from 0 to one less than the value
 returned by {@link #getPointerCount()}.

MotionEvent這個類提供很多方法去查詢位置和指示器的其他屬性，比如獲取X軸坐標值、Y軸坐標值、坐標軸值、指示器Id、工具類型、和諸多其他方法。這些大多數的方法接收指示器下標而不是指示器id.每個指示器索引通過從getPointerCount()方法獲取，范圍從0開始或一個也沒有。

 The order in which individual pointers appear within a motion event is undefined.
 Thus the pointer index of a pointer can change from one event to the next but
 the pointer id of a pointer is guaranteed to remain constant as long as the pointer
 remains active.  Use the {@link #getPointerId(int)} method to obtain the
 pointer id of a pointer to track it across all subsequent 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.

哪一個獨立的指示器出現的移動事件順序是不明確的。因此一個指示器的索引可以從一個事件到下一個事件改變但是指示器的id盡可能的長時間的保留活動的常量。使用getPointerId方法獲得指示器id在所有事件隊列中的手勢中追蹤。對於連續的事件，使用findPotinterIndex方法獲得給定移動事件的指示器索引。

 Mouse and stylus buttons can be retrieved using {@link #getButtonState()}.  It is a
 good idea to check the button state while handling {@link #ACTION_DOWN} as part
 of a touch event.  The application may choose to perform some different action
 if the touch event starts due to a secondary button click, such as presenting a
 context menu.

鼠標和手寫筆可以通過使用getButtonState檢索。這是一個很好的想法去檢查按鈕狀態並處理觸碰事件的一部分。應用可以選擇完成不同的行為從事件開始到第二個按鈕點擊，例如按下菜單鍵。

 

Batching

 

批處理

 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.

為了高效，ACTION_DOWN移動事件可以同時和多個移動事件在單一的對象中處理。大多數情況獲得當前坐標可使用getX()和getY()方法。更早的坐標處理訪問getHistoricalX()和getHistoricalY。歷史坐標僅在當前坐標之前；然而，他們仍然和其他呈現的原始移動事件不同。一次處理所有的坐標，第一消耗歷史坐標會消耗當前坐標。

Example: Consuming all samples for all pointers in a motion event in time order.

例如：同時有序消耗所有單個指示器的移動事件

 

 

 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)); 

     } 

 } 

 

 

Device Types

設備類型

 The interpretation of the contents of a MotionEvent varies significantly depending
 on the source class of the device.

解析事件變量的意義依賴於設備的來源類型。

 On pointing devices with source class {@link InputDevice#SOURCE_CLASS_POINTER}
 such as touch screens, the 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}.

指示設備來源類型參考InputDevice.SOURCE_CLASS_POINTER，比如觸摸屏幕，指示器坐標指定X/Y坐標相對位置。每一個完成的手勢被呈現在完成移動事件的行為隊列中，這個隊列描述這個指示器移動和過度。一個手勢開始於事件ACTION_DOWN提供了第一個指示器位置被按下。一個附加的指示器可以按下或釋放，框架層將生成一個ACTION_POINTER_DOWN或ACIONT_POINTER_UP的移動事件。指示移動被描述為ACTION_MOVE的行為。最後，一個手勢結束當指示器釋放通過ACTION_UP事件或ACTION_CANCEL.

 Some pointing devices such as mice may support vertical and/or horizontal scrolling.
 A scroll event is reported as a generic motion event with {@link #ACTION_SCROLL} that
 includes the relative scroll offset in the {@link #AXIS_VSCROLL} and
 {@link #AXIS_HSCROLL} axes.  See {@link #getAxisValue(int)} for information
 about retrieving these additional axes.

一些指示設備例如鼠標可以支持垂直或水平的滾動。滾動事件通過ACTION_SCROLL來呈現包括相關的滾動偏移AXIS_VSCROLL和AXIS_HSCROLL坐標軸。通過getAxisValue檢索獲取更多附加坐標軸信息。

 On trackball devices with source class {@link InputDevice#SOURCE_CLASS_TRACKBALL},
 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.

追蹤球設備來源通過InputDevice.SOURCE_CLASS_TRACKBALL獲得，指示器坐標指定相關移動的X/Y增量。追蹤球手勢由移動事件隊列組成其描述為ACTION_MOVE其中點綴著當追蹤球的按下ACTION_DOWN或ACTION_UP釋放事件。

 On joystick devices with source class {@link InputDevice#SOURCE_CLASS_JOYSTICK},
 the pointer coordinates specify the absolute position of the joystick axes.
 The joystick axis values are normalized to a range of -1.0 to 1.0 where 0.0 corresponds
 to the center position.  More information about the set of available axes and the
 range of motion can be obtained using {@link InputDevice#getMotionRange}.
 Some common joystick axes are {@link #AXIS_X}, {@link #AXIS_Y},
 {@link #AXIS_HAT_X}, {@link #AXIS_HAT_Y}, {@link #AXIS_Z} and {@link #AXIS_RZ}.

操縱桿設備通過InputDevice.SOURCE_CLASS_JOYSTICK方式獲取，指示器指示操縱桿的絕對位置。操縱桿坐標值通常冉偉在-1.0到1.0之間0.0坐標是中心位置。更多信息相關一組可用的坐標軸范圍和時間可以通過InputDevice.getMotionRange獲得。一些通用操縱桿坐標參見AXIS_X,AXIS_HAT_X,AXIS_HAT_Y,AXIS_Z和AXIS_RZ.

Refer to {@link InputDevice} for more information about how different kinds of 
input devices and sources represent pointer coordinates.

參考InputDevices獲取更多不同種類的輸入設備和資源指示器坐標信息。

 

Consistency Guarantees

 

一致性保證

 Motion events are always delivered to views as a consistent stream of events.
 What constitutes a consistent stream varies depending on the type of device.
 For touch events, consistency implies that pointers go down one at a time,
 move around as a group and then go up one at a time or are canceled.

移動事件總是分配給控件保持一致的流。一致流的變動組成取決於設備的類型。對於觸碰事件，一致性意味著指示器按下在一起，移動和釋放取消都和view同時進行的。

 While the framework tries to deliver consistent streams of motion events to
 views, it cannot guarantee it.  Some events may be dropped or modified by
 containing views in the application before they are delivered thereby making
 the stream of events inconsistent.  Views should always be prepared to
 handle {@link #ACTION_CANCEL} and should tolerate anomalous
 situations such as receiving a new {@link #ACTION_DOWN} without first having
 received an {@link #ACTION_UP} for the prior gesture.

然而框架嘗試分配給View一致性的移動事件，但它並不能保證。一些事件可能被拋棄或者修改在應用之前造成事件的不一致。Views應該總是應該處理ACTION_CANCEL和忍受異常的情形例如接收一個新的ACTION_DOWN按下而沒有收到在之前ACTION_UP的手勢。