MotionEvent

2016/8/17 11:01:49

第一篇

  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 <em>pointers</em>.
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的手势。