diff --git a/doc/sources/guide/inputs.rst b/doc/sources/guide/inputs.rst index 79f54f5eb..9cf92b7cc 100644 --- a/doc/sources/guide/inputs.rst +++ b/doc/sources/guide/inputs.rst @@ -6,26 +6,27 @@ Input architecture Kivy is able to handle most types of input: mouse, touchscreen, accelerometer, gyroscope, etc. It handles the native multitouch protocols on the following -platforms: Tuio, WM_Touch, MacMultitouchSupport, MT Protocol A/B, Android. +platforms: Tuio, WM_Touch, MacMultitouchSupport, MT Protocol A/B and Android. The global architecture can be viewed as:: Input providers -> Motion event -> Post processing -> Dispatch to Window -The class for all input events is the -:class:`~kivy.input.motionevent.MotionEvent`. From this, there are 2 kinds of +The class of all input events is the +:class:`~kivy.input.motionevent.MotionEvent`. It generates 2 kinds of events: - Touch events: a motion event that contains at least an X and Y position. - All the touch events are dispatched accross the Widget tree. + All the touch events are dispatched across the Widget tree. - No-touch events: all the rest. For example, the accelerometer is a continuous event, without position. It never starts or stops. These events - are not dispatched accross the Widget tree. + are not dispatched across the Widget tree. -A Motion event is generated by an Input Provider. An input provider is -responsible for reading the input event from the operating system, the network -or even from another application. Several input providers exist, like: +A Motion event is generated by an :mod:`Input Provider `. +An Input Provider is responsible for reading the input event from the operating +system, the network or even from another application. Several input providers +exist, such as: - :class:`~kivy.input.providers.tuio.TuioMotionEventProvider`: create a UDP server and listen for TUIO/OSC messages. @@ -33,7 +34,7 @@ or even from another application. Several input providers exist, like: windows API for reading multitouch information and sending it to Kivy. - :class:`~kivy.input.providers.probesysfs.ProbeSysfsHardwareProbe`: In Linux, iterate over all the hardware connected to the computer, and - attach a multitouch input provider for each multitouch hardware found. + attaches a multitouch input provider for each multitouch device found. - and much more! When you write an application, you don't need to create an input provider. Kivy @@ -41,7 +42,7 @@ tries to automatically detect available hardware. However, if you want to support custom hardware, you will need to configure kivy to make it work. Before the newly-created Motion Event is passed to the user, Kivy applies -post-processing on the input. Every motion event is analyzed to detect and +post-processing to the input. Every motion event is analyzed to detect and correct faulty input, as well as make meaningful interpretations like: - Double-tap detection, according to a distance and time threshold @@ -49,8 +50,8 @@ correct faulty input, as well as make meaningful interpretations like: - Reducing the amount of generated events if the native touch hardware is sending events with nearly the same position -Then, the motion event is dispatched to the Window. As explained at the start, -all events are not dispatched to the whole widget tree, the window filters them. +After processing, the motion event is dispatched to the Window. As explained previosuly, +not all events are dispatched to the whole widget tree: the window filters them. For a given event: - if it's only a motion event, it will be dispatched to @@ -83,8 +84,8 @@ The print could output:: .. warning:: - Most people mix up the profile's name and the name of the corresponding - property. Just because ``'angle'`` is in the available profile doesnt + Many people mix up the profile's name and the name of the corresponding + property. Just because ``'angle'`` is in the available profile doesn't mean that the touch event object will have an ``angle`` property. For the ``'pos'`` profile, the properties ``pos``, ``x``, and ``y`` will be @@ -99,7 +100,7 @@ profile exists:: print 'The touch angle is', touch.a You can find a list of available profiles in the -:mod:`api-kivy.input.motionevent` documentation. +:mod:`~kivy.input.motionevent` documentation. Touch events ------------ @@ -110,9 +111,10 @@ evaluates to True. For all touch events, you automatically have the X and Y positions available, scaled to the Window width and height. In other words, all touch events have the ``'pos'`` profile. -You must take care about matrix transformation in your touch as soon as you use -a widget with matrix transformation. Some widgets such as Scatter have their own -matrix transformation, meaning the touch must be multiplied by the scatter +You must take care of matrix transformation in your touch as soon as you use +a widget with matrix transformation. Some widgets such as +:class:`~kivy.uix.scatter.Scatter` have their own matrix transformation, +meaning the touch must be multiplied by the scatter matrix to be able to correctly dispatch touch positions to the Scatter's children. @@ -125,22 +127,22 @@ children. - Get coordinate from window space to local space: :meth:`~kivy.uix.widget.Widget.to_widget` -You must use one of them to get the good coordinate. Let's take the scatter -implementation:: +You must use one of them to scale coordinates correctly to the context. +Let's look the scatter implementation:: def on_touch_down(self, touch): - # push the current coordinate, to be able to restore them later. + # push the current coordinate, to be able to restore it later touch.push() # transform the touch coordinate to local space touch.apply_transform_2d(self.to_local) # dispatch the touch as usual to children - # the coordinate in the touch are now in local space + # the coordinate in the touch is now in local space ret = super(..., self).on_touch_down(touch) - # whatever is the result, don't forget to pop the transformation - # after the call, the coordinate will be in parent space + # whatever the result, don't forget to pop your transformation + # after the call, so the coordinate will be back in parent space touch.pop() # return the result (depending what you want.) @@ -164,7 +166,7 @@ now, only a :class:`~kivy.input.shape.ShapeRect` can be exposed:: Double tap ~~~~~~~~~~ -The double tap is the action of tapping twice within a time and a distance. +A double tap is the action of tapping twice within a time and a distance. It's calculated by the doubletap post-processing module. You can test if the current touch is one of a double tap or not:: @@ -179,41 +181,41 @@ current touch is one of a double tap or not:: Grabbing touch events ~~~~~~~~~~~~~~~~~~~~~ -It's possible for the parent widget to dispatch a touch event to its child +It's possible for the parent widget to dispatch a touch event to a child widget from within ``on_touch_down``, but not from ``on_touch_move`` or ``on_touch_up``. This can happen in certain scenarios, like when a touch movement is outside the bounding box of the parent, so the parent decides not to notify its children of the movement. -But you might want to do something ``on_touch_up``. Say you started something on -the down event, like playing a sound, and you'd like to finish things on the up -event. Grabbing is what you need. +But you might want to do something in ``on_touch_up``. Say you started something in +the ``on_touch_down`` event, like playing a sound, and you'd like to finish things +on the ``on_touch_up`` event. Grabbing is what you need. When you grab a touch, you will always receive the move and up event. But there are some limitations to grabbing: - You will receive the event at least twice: one time from your parent (the normal event), and one time from the window (grab). - - You might receive an event with a grab touch, but not from you: it can be - because the parent has sent the touch to its children, while it was in + - You might receive an event with a grabbed touch, but not from you: it can be + because the parent has sent the touch to its children while it was in the grabbed state. - - The touch coordinate is not translated to your widget space, because the + - The touch coordinate is not translated to your widget space because the touch is coming directly from the Window. It's your job to convert the coordinate to your local space. -Here is an example on how to use grabbing:: +Here is an example of how to use grabbing:: def on_touch_down(self, touch): if self.collide_point(*touch.pos): - # if the touch is colliding to our widget, let's grab it. + # if the touch collides with our widget, let's grab it touch.grab(self) # and accept the touch. return True def on_touch_up(self, touch): - # here, you don't check if the touch is colliding or things like that. + # here, you don't check if the touch collides or things like that. # you just need to check if it's a grabbed touch event if touch.grab_current is self: @@ -221,9 +223,8 @@ Here is an example on how to use grabbing:: # do something interesting here print 'Hello world!' - # don't forget to ungrab ourself, or you might have counter effects + # don't forget to ungrab ourself, or you might have side effects touch.ungrab(self) # and accept the last up return True -