Input Handling

class libavg.avg.Contact

Bases: libavg.avg.Publisher

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 CursorEvent. To get these messages, call Publisher.subscribe(). All subscribers are unsubscribed automatically after the up event.

CURSOR_MOTION(cursorevent)

Emitted whenever the contact moves.

CURSOR_UP(cursorevent)

Emitted when the mouse button is released or the touch leaves the surface.

age

Time that has passed since the down event in milliseconds. Read-only.

distancefromstart

Distance of the current position from the initial position in pixels. Read-only.

distancetravelled

The total distance travelled since the initial down event. Read-only.

events

An array containing all events that this contact has generated in the past. Read-only.

id

A numerical id for this contact. This corresponds to the CursorEvent.cursorid field. Contacts for touch events have unique ids, while contacts for mouse events always have the id -1. ids are not reused. Read-only.

motionangle

Angle of the current position from the initial position in radians. Like all angles in libavg, motionangle is 0 on the positive x axis and increases clockwise. Read-only.

motionvec

The difference of the current position and the initial position as a Point2D. Read-only.

connectListener(motionCallback, upCallback) → id

Deprecated since version 1.8: Use the message interface instead.

Registers event handlers that get called when CURSORMOTION and CURSORUP events for this Contact occur. Event handlers can be unregistered using disconnectListener(). They are automatically unregistered after the up event. The id returned is unique for this contact.

disconnectListener(id)

Deprecated since version 1.8: Use the message interface instead.

Unregisters an event handler. The parameter is the id returned in connectListener(). It is an error to call disconnectListener() with an invalid id.

getRelPos(node, abspos) → relpos

Transforms a position in window coordinates to a position in coordinates relative to node. node must be one of the nodes the original down event of the Contact was over. In contrast to Node.getRelPos(), this method transforms window coordinates even if the node is inside a canvas.

class libavg.avg.CursorEvent

Bases: libavg.avg.Event

Base class for all events which contain a position in the global coordinate system.

contact

The Contact that the event belongs to, if there is one. Read-only.

cursorid

A numerical identifier for the current cursor.

node

The Node that the event occured in. If this is None, the event happened outside of the application window and the cursor was captured by the application. Read-only.

pos

Position in the global coordinate system. Read-only.

source

The type of the device that emitted the event. See Event.source. Read-only.

x

x position in the global coordinate system. Read-only.

y

y position in the global coordinate system. Read-only.

userid

If the input source supports user identification, this is the id of the user that touched.

class libavg.avg.Event(type, source[, when])

Bases: Boost.Python.instance

Base class for user input events.

Parameters:

• type (type) – The type of the event. See Event.type.
• source (source) – The source of the event. See Event.source.
• when (Integer) – The time the event occured

inputdevice

The address of the device that emitted the event. Read-only

inputdevicename

The name of the device that emitted the event. Read-only.

source

One of MOUSE, TOUCH, TRACK, CUSTOM or NONE. Read-only

type

One of KEYUP, KEYDOWN, CURSORMOTION, CURSORUP, CURSORDOWN, CURSOROVER or CURSOROUT. Read-only.

when

The time when the event occured in milliseconds since program start. Read-only.

class libavg.avg.KeyEvent

Bases: libavg.avg.Event

Generated when a key is pressed or released.

keyname

The name of the key according to the current keyboard layout. This can be a character like “A” or a word like “Up” for the up arrow key. Read-only.

text

The text that the key represents, if any. Handles shifted (i.e., uppercase) characters and dead key combinations (i.e., “á” if “’” and “a” are pressed in succession).

modifiers

Any modifier keys pressed, or’ed together. Possible Modifiers are KEYMOD_NONE, KEYMOD_LSHIFT, KEYMOD_RSHIFT, KEYMOD_LCTRL, KEYMOD_RCTRL, KEYMOD_LALT, KEYMOD_RALT, KEYMOD_LGUI, KEYMOD_RGUI, KEYMOD_NUM, KEYMOD_CAPS, KEYMOD_GUI, KEYMOD_CTRL, KEYMOD_SHIFT, and KEYMOD_ALT. Read-only.

scancode

A value that represents the physical position of the key on the keyboard. Independent of the keyboard language/layout. Read-only.

class libavg.avg.MouseEvent(type, leftButtonState, middleButtonState, rightButtonState, pos, button[, speed, when])

Bases: libavg.avg.CursorEvent

Generated when a mouse-related event occurs.

button

The button that caused the event. Read-only.

cursorid

Always -1 for mouse events, but can be used to handle mouse and tracking events in one handler. Read-only.

leftbuttonstate

True if the left mouse button is currently pressed. Read-only.

middlebuttonstate

True if the middle mouse button is currently pressed. Read-only.

rightbuttonstate

True if the right mouse button is currently pressed. Read-only.

source

Always MOUSE. Read-only

speed

Current speed of the mouse in pixels per millisecond as a Point2D. Read-only.

class libavg.avg.MouseWheelEvent(pos, motion[, when])

Bases: libavg.avg.CursorEvent

Generated when the mouse wheel is moved.

motion

Direction and magnitude of movement as an (x,y) vector.

class libavg.avg.TangibleEvent(id, markerID, type, pos, speed, orientation)

Bases: libavg.avg.CursorEvent

Generated when a tangible event occurs. Tangible events happen when a surface that supports marker-based tracking is active. Supported only for TUIO-based surfaces.

markerID

The id of the marker. Unlike cursorid, markerID is persistent and stays the same if a tangible is removed from the surface and re-placed again.

orientation

The angle of the marker in radians.

class libavg.avg.TouchEvent(id, type, pos, source[, speed])

Bases: libavg.avg.CursorEvent

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.

area

Size of the blob found in pixels. Read-only.

center

Position as Point2D, with sub-pixel accuracy. Used for calibration. Read-only.

cursorid

An identifier for the current touch. A single touch will generate a down event, zero or more motion events and a single up event in its lifetime, all with the same cursorid.

eccentricity

handorientation

The angle of the hand relative to the finger. handorientation is only defined for events with source = 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. handorientation ranges from -pi to pi, with 0 being the positive x axis. Angles increase in a clockwise fashion.

For CURSORUP events, the angle is always approximated.

majoraxis

Major axis of an ellipse that is similar to the blob. Read-only.

minoraxis

Minor axis of an ellipse that is similar to the blob. Read-only.

orientation

Angle of the blob in radians. For hovering hands, this is roughly the direction of the hand, modulo 180 degrees. Read-only.

source

source can be either TRACK or TOUCH. In most cases, actual touches will generate TOUCH events. When used with a DI device, the internal tracker also generates TRACK events for hands above the surface. When used with an FTIR device, the internal tracker generates TRACK events for the actual touches. Read-only.

speed

Current speed of the touch in pixels per millisecond as a Point2D. Read-only.

getRelatedEvents() → events

Only if supported by the hardware: Returns a python tuple containing the events ‘related’ to this one. For TOUCH events (fingers), the tuple contains one element: the corresponding TRACK event (hand). For TRACK events, the tuple contains all TOUCH events that belong to the same hand.