Input Handling ============== .. automodule:: libavg.avg :no-members: .. inheritance-diagram:: Event CursorEvent MouseEvent TouchEvent KeyEvent :parts: 1 .. inheritance-diagram:: Contact :parts: 1 .. inheritance-diagram:: InputDevice :parts: 1 .. autoclass:: Contact A Contact encapsulates the information of one touch on an input device from the down event to an up event. It exposes some aggregate information about the touch - distance and direction travelled etc. - and supports event handlers that are only called for this single contact. For compatibility reasons, a mouse device also produces contacts. A mouse contact exists from the press of a button to its release. If multiple buttons are pressed without a complete release (e.g. LEFTDOWN-RIGHTDOWN-LEFTUP-RIGHTUP), the mouse contact exists for the complete sequence. **Messages:** All message parameters are of type :py:class:`CursorEvent`. To get these messages, call :py:meth:`Publisher.subscribe`. All subscribers are unsubscribed automatically after the up event. .. py:method:: CURSOR_MOTION(cursorevent) Emitted whenever the contact moves. .. py:method:: CURSOR_UP(cursorevent) Emitted when the mouse button is released or the touch leaves the surface. .. py:attribute:: age Time that has passed since the down event in milliseconds. Read-only. .. py:attribute:: distancefromstart Distance of the current position from the initial position in pixels. Read-only. .. py:attribute:: distancetravelled The total distance travelled since the initial down event. Read-only. .. py:attribute:: events An array containing all events that this contact has generated in the past. Read-only. .. py:attribute:: id A numerical id for this contact. This corresponds to the :py:attr:`CursorEvent.cursorid` field. Contacts for touch events have unique ids, while contacts for mouse events always have the :py:attr:`id` :py:const:`-1`. ids are not reused. Read-only. .. py:attribute:: motionangle Angle of the current position from the initial position in radians. Like all angles in libavg, :py:attr:`motionangle` is 0 on the positive x axis and increases clockwise. Read-only. .. py:attribute:: motionvec The difference of the current position and the initial position as a :py:class:`Point2D`. Read-only. .. py:method:: connectListener(motionCallback, upCallback) -> id .. deprecated:: 1.8 Use the message interface instead. Registers event handlers that get called when CURSORMOTION and CURSORUP events for this :py:class:`Contact` occur. Event handlers can be unregistered using :py:meth:`disconnectListener`. They are automatically unregistered after the up event. The :py:attr:`id` returned is unique for this contact. .. py:method:: disconnectListener(id) .. deprecated:: 1.8 Use the message interface instead. Unregisters an event handler. The parameter is the :py:attr:`id` returned in :py:meth:`connectListener`. It is an error to call :py:meth:`disconnectListener` with an invalid id. .. autoclass:: CursorEvent Base class for all events which contain a position in the global coordinate system. .. py:attribute:: contact The :py:class:`Contact` that the event belongs to, if there is one. Read-only. .. py:attribute:: cursorid A numerical identifier for the current cursor. .. py:attribute:: node The :py:class:`Node` that the event occured in. If this is :py:const:`None`, the event happened outside of the application window and the cursor was captured by the application. Read-only. .. py:attribute:: pos Position in the global coordinate system. Read-only. .. py:attribute:: source The type of the device that emitted the event. See :py:attr:`Event.source`. Read-only. .. py:attribute:: x x position in the global coordinate system. Read-only. .. py:attribute:: y y position in the global coordinate system. Read-only. .. autoclass:: Event(type, source, [when]) Base class for user input events. :param type type: The type of the event. See :py:attr:`Event.type`. :param source source: The source of the event. See :py:attr:`Event.source`. :param Integer when: The time the event occured .. py:attribute:: inputdevice The address of the device that emitted the event. Read-only .. py:attribute:: inputdevicename The name of the device that emitted the event. Read-only. .. py:attribute:: source One of :py:const:`MOUSE`, :py:const:`TOUCH`, :py:const:`TRACK`, :py:const:`CUSTOM` or :py:const:`NONE`. Read-only .. py:attribute:: type One of :py:const:`KEYUP`, :py:const:`KEYDOWN`, :py:const:`CURSORMOTION`, :py:const:`CURSORUP`, :py:const:`CURSORDOWN`, :py:const:`CURSOROVER` or :py:const:`CURSOROUT`. Read-only. .. py:attribute:: when The time when the event occured in milliseconds since program start. Read-only. .. autoclass:: InputDevice(name, [eventReceiverNode]) Base class for input devices which feed events to the system. Derived classes can be either user-defined or one of the predefined libavg input devices. User-defined InputDevice objects are registered with the system by calling :py:meth:`Player.addInputDevice`. After this, the emitted events are processed like any other events. .. py:attribute:: eventreceivernode The :py:class:`DivNode` that the input device will deliver events to. By default, this is the libavg root node. Useful for restricting events to a part of the total canvas or for sending events directly to an offscreen canvas. Event bubbling starts at this node and proceeds down the tree from there. Read-only. .. py:attribute:: name The name of the device. Read-only. .. py:method:: pollEvents() -> list Abstract method which returns a list of pending events. Override this method in your derived input device class. After registering the input device, this method gets called on every frame. .. py:method:: start() Initializes the input device if needed. By default this is an empty method. .. autoclass:: KeyEvent Generated when a key is pressed or released. .. py:attribute:: keycode The keycode of the key according to US keyboard layout. Read-only. .. py:attribute:: keystring A character or word describing the key pressed. Read-only. .. py:attribute:: modifiers Any modifier keys pressed, or'ed together. Possible Modifiers are :py:const:`KEYMOD_NONE`, :py:const:`KEYMOD_LSHIFT`, :py:const:`KEYMOD_RSHIFT`, :py:const:`KEYMOD_LCTRL`, :py:const:`KEYMOD_RCTRL`, :py:const:`KEYMOD_LALT`, :py:const:`KEYMOD_RALT`, :py:const:`KEYMOD_LMETA`, :py:const:`KEYMOD_RMETA`, :py:const:`KEYMOD_NUM`, :py:const:`KEYMOD_CAPS`, :py:const:`KEYMOD_MODE`. Read-only. .. py:attribute:: scancode The untranslated (hardware-dependent) scancode of the key pressed. Read-only. .. py:attribute:: unicode Unicode index of the character. Takes into account the current keyboard layout and any modifiers pressed. This attribute is only filled in the :py:const:`KEYDOWN` event. Read-only. .. autoclass:: MouseEvent(type, leftButtonState, middleButtonState, rightButtonState, pos, button, [speed, when]) Generated when a mouse-related event occurs. .. py:attribute:: button The button that caused the event. Read-only. .. py:attribute:: cursorid Always :samp:`-1` for mouse events, but can be used to handle mouse and tracking events in one handler. Read-only. .. py:attribute:: leftbuttonstate :py:const:`True` if the left mouse button is currently pressed. Read-only. .. py:attribute:: middlebuttonstate :py:const:`True` if the middle mouse button is currently pressed. Read-only. .. py:attribute:: rightbuttonstate :py:const:`True` if the right mouse button is currently pressed. Read-only. .. py:attribute:: source Always :py:const:`MOUSE`. Read-only .. py:attribute:: speed Current speed of the mouse in pixels per millisecond as a :py:class:`Point2D`. Read-only. .. autoclass:: TouchEvent(id, type, pos, source, [speed]) Generated when a touch or other tracking event occurs. Touch events happen only when a multi-touch sensitive surface or other camera tracker is active. .. py:attribute:: area Size of the blob found in pixels. Read-only. .. py:attribute:: center Position as :py:class:`Point2D`, with sub-pixel accuracy. Used for calibration. Read-only. .. py:attribute:: cursorid An identifier for the current touch. A single touch will generate a down, zero or more motion and a single up event in its lifetime, all with the same :py:attr:`cursorid`. .. py:attribute:: eccentricity .. py:attribute:: handorientation The angle of the hand relative to the finger. :py:attr:`handorientation` is only defined for events with :py:attr:`source`=:py:const:`TOUCH`. If the tracker has detected a hovering hand attached to the finger, this is the actual hand-finger angle. If no hand was detected, the angle is approximated using the position of the touch on the surface. :py:attr:`handorientation` ranges from :py:const:`-pi` to :py:const:`pi`, with 0 being the positive x axis. Angles increase in a clockwise fashion. For :py:const:`CURSORUP` events, the angle is always approximated. .. py:attribute:: majoraxis Major axis of an ellipse that is similar to the blob. Read-only. .. py:attribute:: minoraxis Minor axis of an ellipse that is similar to the blob. Read-only. .. py:attribute:: orientation Angle of the blob in radians. For hovering hands, this is roughly the direction of the hand, modulo 180 degrees. Read-only. .. py:attribute:: source :py:attr:`source` can be either :py:const:`TRACK` or :py:const:`TOUCH`. In most cases, actual touches will generate :py:const:`TOUCH` events. When used with a DI device, the internal tracker also generates :py:const:`TRACK` events for hands above the surface. When used with an FTIR device, the internal tracker generates :py:const:`TRACK` events for the actual touches. Read-only. .. py:attribute:: speed Current speed of the touch in pixels per millisecond as a :py:class:`Point2D`. Read-only. .. py:method:: getContour() -> list Returns the contour of the blob as a list of points if supported by the tracker being used. .. py:method:: getRelatedEvents() -> events Only for DI devices and the internal tracker: Returns a python tuple containing the events 'related' to this one. For :py:const:`TOUCH` events (fingers), the tuple contains one element: the corresponding :py:const:`TRACK` event (hand). For :py:const:`TRACK` events, the tuple contains all :py:const:`TOUCH` events that belong to the same hand. .. autoclass:: Tracker A class that uses a camera to track moving objects and delivers the movements as avg events. Create a tracker by using :py:meth:`Player.enableMultitouch()` with :samp:`AVG_MULTITOUCH_DRIVER=TRACKER`. The properties of this class are explained under https://www.libavg.de/wiki/ProgrammersGuide/Tracker. .. py:method:: abortCalibration() Aborts coordinate calibration session and restores the previous coordinate transformer. .. py:method:: endCalibration() Ends coordinate calibration session and activates the coordinate transformer generated. .. py:method:: getDisplayROIPos() .. py:method:: getDisplayROISize() .. py:method:: getImage(imageid) -> Bitmap Returns one of the intermediate images necessary for tracking. These images are only available if setDebugImages was called before with appropriate parameters. Possible :py:attr:`imageid` values are :py:const:`IMG_CAMERA`, :py:const:`IMG_DISTORTED`, :py:const:`IMG_NOHISTORY`, :py:const:`IMG_HISTOGRAM`, :py:const:`IMG_FINGERS` or :py:const:`IMG_HIGHPASS`. .. py:method:: getParam(element) -> value Returns a tracker configuration parameter. .. py:method:: resetHistory() Throws away the current history image and generates a new one from the next second of images. .. py:method:: saveConfig() Saves the current tracker configuration to the default config file. .. py:method:: setDebugImages(img, finger) Controls whether debug images of intermediate tracking results and detected finger positions are generated and exported to python. Generating the debug images takes a moderate amount of time, so it is turned off by default. :param img: Whether to generate intermediate result images. :param finger: Whether to generate the :py:const:`IMG_FINGERS` result image. .. py:method:: setParam(element, value) Sets one of the tracker configuration parameters. .. py:method:: startCalibration(displayextents) -> TrackerCalibrator Starts coordinate calibration session. The returned :py:class:`TrackerCalibrator` exists until :py:meth:`endCalibration` or :py:meth:`abortCalibration` is called. :param displayextents: The width and height of the display area. .. autoclass:: TrackerCalibrator Generates a mapping of display points to camera points using a set of reference points. Python code should display reference points that the user must touch to establish a mapping. Created by :py:meth:`Tracker.startCalibration`. .. py:method:: getDisplayPoint() -> Point2D .. py:method:: nextPoint() -> bool Advances to the next point. Returns :py:const:`False` and ends calibration if all points have been set. .. py:method:: setCamPoint(pos)