The ioHub Mouse Device¶

Platforms: Windows, macOS, Linux

class psychopy.iohub.devices.mouse.MouseDevice(*args, **kwargs)[source]¶

getPosition(return_display_index=False)[source]¶

Returns the current position of the ioHub Mouse Device. Mouse Position is in display coordinate units, with 0,0 being the center of the screen.

Parameters:

return_display_index – If True, the display index that is
returned. (associated with the mouse position will also be)

Returns:

If return_display_index is false (default), return (x, y) position of mouse. If return_display_index is True return ( ( x,y), display_index).

Return type:

tuple

setPosition(pos, display_index=None)[source]¶

Sets the current position of the ioHub Mouse Device. Mouse position ( pos ) should be specified in Display coordinate units, with 0,0 being the center of the screen.

Parameters:

pos ((x,y) list or tuple) – The position, in Display
space (coordinate)
too. (to set the mouse position)
display_index (int) – Optional argument giving the display index
None (to set the mouse pos within. If)
Display (the active ioHub)
used. (device index is)

Returns:

new (x,y) position of mouse in Display coordinate space.

Return type:

tuple

getPositionAndDelta(return_display_index=False)[source]¶

Returns a tuple of tuples, being the current position of the ioHub Mouse Device as an (x,y) tuple, and the amount the mouse position changed the last time it was updated (dx,dy). Mouse Position and Delta are in display coordinate units.

Parameters:: None
Returns:: ( (x,y), (dx,dy) ) position of mouse, change in mouse position, both in Display coordinate space.
Return type:: tuple

getScroll()[source]¶

Returns the current vertical scroll value for the mouse. The vertical scroll value changes when the scroll wheel on a mouse is moved up or down. The vertical scroll value is in an arbitrary value space ranging for -32648 to +32648. Scroll position is initialize to 0 when the experiment starts.

Parameters:: None
Returns:: current vertical scroll value.
Return type:: int

setScroll(s)[source]¶

Sets the current vertical scroll value for the mouse. The vertical scroll value changes when the scroll wheel on a mouse is moved up or down. The vertical scroll value is in an arbitrary value space ranging for -32648 to +32648. Scroll position is initialize to 0 when the experiment starts. This method allows you to change the scroll value to anywhere in the valid value range.

Args (int):: The scroll position you want to set the vertical scroll to. Should be a number between -32648 to +32648.

Returns:: current vertical scroll value.
Return type:: int

getEvents(*args, **kwargs)¶

Retrieve any DeviceEvents that have occurred since the last call to the device’s getEvents() or clearEvents() methods.

Note that calling getEvents() at a device level does not change the Global Event Buffer’s contents.

Parameters:

event_type_id (int) – If specified, provides the ioHub DeviceEvent ID for which events
ID (should be returned for. Events that have occurred but do not match the event)
class; (specified are ignored. Event type ID's can be accessed via the EventConstants)
EventConstants. (all available event types are class attributes of)
clearEvents (int) – Can be used to indicate if the events being returned should also be
True (removed from the device event buffer.)
buffer. (being returned. False results in events being left in the device event)
asType (str) – Optional kwarg giving the object type to return events as. Valid values
'namedtuple' (are)

Returns:

New events that the ioHub has received since the last getEvents() or clearEvents() call to the device. Events are ordered by the ioHub time of each event, older event at index 0. The event object type is determined by the asType parameter passed to the method. By default a namedtuple object is returned for each event.

Return type:

(list)

clearEvents(event_type=None, filter_id=None, call_proc_events=True)¶

Clears any DeviceEvents that have occurred since the last call to the device’s getEvents(), or clearEvents() methods.

Note that calling clearEvents() at the device level only clears the given device’s event buffer. The ioHub Process’s Global Event Buffer is unchanged.

Parameters:: None
Returns:: None

Mouse Event Types¶

The Mouse device supports the following event types. Device events returned by getEvents() are automatically converted to either namedtuple or dictionary objects with the same attributes / keys as the associated event class attributes.

class psychopy.iohub.devices.mouse.MouseMoveEvent(*args, **kwargs)[source]¶

MouseMoveEvent’s occur when the mouse position changes. Mouse position is mapped to the coordinate space defined in the ioHub configuration file for the Display.

Event Type ID: EventConstants.MOUSE_MOVE

Event Type String: ‘MOUSE_MOVE’

time¶: time of event, in sec.msec format, using psychopy timebase.

x_position¶: x position of the Mouse when the event occurred; in display coordinate space.

y_position¶: y position of the Mouse when the event occurred; in display coordinate space.

scroll_x¶: Horizontal scroll wheel absolute position when the event occurred. macOS only. Always 0 on other OS’s.

scroll_y¶: Vertical scroll wheel absolute position when the event occurred.

modifiers¶: List of the modifiers that were active when the mouse event occurred, provided as a list of the modifier constant labels.

display_id¶: The id of the display that the mouse was over when the event occurred. Only supported on Windows at this time. Always 0 on other OS’s.

window_id¶: Window handle reference that the mouse was over when the event occurred (window does not need to have focus).

event_id¶: The id assigned to the device event. Every event generated by iohub during an experiment session is assigned a unique id, starting from 0.

type¶: The type id for the event. This is used to create DeviceEvent objects or dictionary representations of an event based on the data from an event list.

class psychopy.iohub.devices.mouse.MouseDragEvent(*args, **kwargs)[source]¶

MouseDragEvents occur when the mouse position changes and at least one mouse button is pressed. Mouse position is mapped to the coordinate space defined in the ioHub configuration file for the Display.

Event Type ID: EventConstants.MOUSE_DRAG

Event Type String: ‘MOUSE_DRAG’

time¶: x position of the Mouse when the event occurred; in display coordinate space.

x_position¶: x position of the Mouse when the event occurred; in display coordinate space.

button_state¶: 1 if a mouse button press caused the event, 0 if button was released.

button_id¶: Index of the mouse button that caused the event. MouseConstants.MOUSE_BUTTON_LEFT, MouseConstants.MOUSE_BUTTON_RIGHT and MouseConstants.MOUSE_BUTTON_MIDDLE are int constants representing left, right, and middle buttons of the mouse.

pressed_buttons¶: All currently pressed button id’s logically OR’ed together.

y_position¶: y position of the Mouse when the event occurred; in display coordinate space.

scroll_x¶: Horizontal scroll wheel absolute position when the event occurred. macOS only. Always 0 on other OS’s.

scroll_y¶: Vertical scroll wheel absolute position when the event occurred.

modifiers¶: List of the modifiers that were active when the mouse event occurred, provided as a list of the modifier constant labels.

display_id¶: The id of the display that the mouse was over when the event occurred. Only supported on Windows at this time. Always 0 on other OS’s.

window_id¶: Window handle reference that the mouse was over when the event occurred (window does not need to have focus).

event_id¶: The id assigned to the device event. Every event generated by iohub during an experiment session is assigned a unique id, starting from 0.

type¶: The type id for the event. This is used to create DeviceEvent objects or dictionary representations of an event based on the data from an event list.

class psychopy.iohub.devices.mouse.MouseButtonPressEvent(*args, **kwargs)[source]¶

MouseButtonPressEvent’s are created when a button on the mouse is pressed. The button_state of the event will equal MouseConstants.MOUSE_BUTTON_STATE_PRESSED, and the button that was pressed (button_id) will be MouseConstants.MOUSE_BUTTON_LEFT, MouseConstants.MOUSE_BUTTON_RIGHT, or MouseConstants.MOUSE_BUTTON_MIDDLE, assuming you have a 3 button mouse.

To get the current state of all three buttons on the Mouse Device, the pressed_buttons attribute can be read, which tracks the state of all three mouse buttons as an int that is equal to the sum of any pressed button id’s ( MouseConstants.MOUSE_BUTTON_LEFT, MouseConstants.MOUSE_BUTTON_RIGHT, or MouseConstants.MOUSE_BUTTON_MIDDLE ).

To tell if a given mouse button was depressed when the event occurred, regardless of which button triggered the event, you can use the following:

isButtonPressed = event.pressed_buttons &
MouseConstants.MOUSE_BUTTON_xxx == MouseConstants.MOUSE_BUTTON_xxx

where xxx is LEFT, RIGHT, or MIDDLE.

For example, if at the time of the event both the left and right mouse buttons were in a pressed state:

buttonToCheck=MouseConstants.MOUSE_BUTTON_RIGHT
isButtonPressed = event.pressed_buttons & buttonToCheck ==
buttonToCheck

print isButtonPressed

>> True

buttonToCheck=MouseConstants.MOUSE_BUTTON_LEFT
isButtonPressed = event.pressed_buttons & buttonToCheck ==
buttonToCheck

print isButtonPressed

>> True

buttonToCheck=MouseConstants.MOUSE_BUTTON_MIDDLE
isButtonPressed = event.pressed_buttons & buttonToCheck ==
buttonToCheck

print isButtonPressed

>> False

Event Type ID: EventConstants.MOUSE_BUTTON_PRESS

Event Type String: ‘MOUSE_BUTTON_PRESS’

:rtype : MouseButtonEvent :param args: :param kwargs:

time¶: x position of the Mouse when the event occurred; in display coordinate space.

x_position¶: x position of the Mouse when the event occurred; in display coordinate space.

button_state¶: 1 if a mouse button press caused the event, 0 if button was released.

button_id¶: Index of the mouse button that caused the event. MouseConstants.MOUSE_BUTTON_LEFT, MouseConstants.MOUSE_BUTTON_RIGHT and MouseConstants.MOUSE_BUTTON_MIDDLE are int constants representing left, right, and middle buttons of the mouse.

pressed_buttons¶: All currently pressed button id’s logically OR’ed together.

y_position¶: y position of the Mouse when the event occurred; in display coordinate space.

scroll_x¶: Horizontal scroll wheel absolute position when the event occurred. macOS only. Always 0 on other OS’s.

scroll_y¶: Vertical scroll wheel absolute position when the event occurred.

modifiers¶: List of the modifiers that were active when the mouse event occurred, provided as a list of the modifier constant labels.

display_id¶: The id of the display that the mouse was over when the event occurred. Only supported on Windows at this time. Always 0 on other OS’s.

window_id¶: Window handle reference that the mouse was over when the event occurred (window does not need to have focus).

event_id¶: The id assigned to the device event. Every event generated by iohub during an experiment session is assigned a unique id, starting from 0.

type¶: The type id for the event. This is used to create DeviceEvent objects or dictionary representations of an event based on the data from an event list.

class psychopy.iohub.devices.mouse.MouseButtonReleaseEvent(*args, **kwargs)[source]¶

MouseButtonUpEvent’s are created when a button on the mouse is released.

The button_state of the event will equal MouseConstants.MOUSE_BUTTON_STATE_RELEASED, and the button that was pressed (button_id) will be MouseConstants.MOUSE_BUTTON_LEFT, MouseConstants.MOUSE_BUTTON_RIGHT, or MouseConstants.MOUSE_BUTTON_MIDDLE, assuming you have a 3 button mouse.

Event Type ID: EventConstants.MOUSE_BUTTON_RELEASE

Event Type String: ‘MOUSE_BUTTON_RELEASE’

:rtype : MouseButtonEvent :param args: :param kwargs:

time¶: x position of the Mouse when the event occurred; in display coordinate space.

x_position¶: x position of the Mouse when the event occurred; in display coordinate space.

button_state¶: 1 if a mouse button press caused the event, 0 if button was released.

button_id¶: Index of the mouse button that caused the event. MouseConstants.MOUSE_BUTTON_LEFT, MouseConstants.MOUSE_BUTTON_RIGHT and MouseConstants.MOUSE_BUTTON_MIDDLE are int constants representing left, right, and middle buttons of the mouse.

pressed_buttons¶: All currently pressed button id’s logically OR’ed together.

y_position¶: y position of the Mouse when the event occurred; in display coordinate space.

scroll_x¶: Horizontal scroll wheel absolute position when the event occurred. macOS only. Always 0 on other OS’s.

scroll_y¶: Vertical scroll wheel absolute position when the event occurred.

modifiers¶: List of the modifiers that were active when the mouse event occurred, provided as a list of the modifier constant labels.

display_id¶: The id of the display that the mouse was over when the event occurred. Only supported on Windows at this time. Always 0 on other OS’s.

window_id¶: Window handle reference that the mouse was over when the event occurred (window does not need to have focus).

event_id¶: The id assigned to the device event. Every event generated by iohub during an experiment session is assigned a unique id, starting from 0.

type¶: The type id for the event. This is used to create DeviceEvent objects or dictionary representations of an event based on the data from an event list.

class psychopy.iohub.devices.mouse.MouseScrollEvent(*args, **kwargs)[source]¶

MouseScrollEvent’s are generated when the scroll wheel on the Mouse Device (if it has one) is moved. Vertical scrolling is supported on all operating systems, horizontal scrolling is only supported on OS X.

Each MouseScrollEvent provides the number of units the wheel was turned in each supported dimension, as well as the absolute scroll value for of each supported dimension.

Event Type ID: EventConstants.MOUSE_SCROLL

Event Type String: ‘MOUSE_SCROLL’

:rtype : MouseScrollEvent :param args: :param kwargs:

time¶: x position of the Mouse when the event occurred; in display coordinate space.

x_position¶: x position of the Mouse when the event occurred; in display coordinate space.

button_state¶: 1 if a mouse button press caused the event, 0 if button was released.

button_id¶: Index of the mouse button that caused the event. MouseConstants.MOUSE_BUTTON_LEFT, MouseConstants.MOUSE_BUTTON_RIGHT and MouseConstants.MOUSE_BUTTON_MIDDLE are int constants representing left, right, and middle buttons of the mouse.

pressed_buttons¶: All currently pressed button id’s logically OR’ed together.

y_position¶: y position of the Mouse when the event occurred; in display coordinate space.

scroll_x¶: Horizontal scroll wheel absolute position when the event occurred. macOS only. Always 0 on other OS’s.

scroll_dx¶: Horizontal scroll wheel position change when the event occurred. macOS only. Always 0 on other OS’s.

scroll_y¶: Vertical scroll wheel absolute position when the event occurred.

scroll_dy¶: Vertical scroll wheel position change when the event occurred.

modifiers¶: List of the modifiers that were active when the mouse event occurred, provided as a list of the modifier constant labels.

display_id¶: The id of the display that the mouse was over when the event occurred. Only supported on Windows at this time. Always 0 on other OS’s.

window_id¶: Window handle reference that the mouse was over when the event occurred (window does not need to have focus).

event_id¶: The id assigned to the device event. Every event generated by iohub during an experiment session is assigned a unique id, starting from 0.

type¶: The type id for the event. This is used to create DeviceEvent objects or dictionary representations of an event based on the data from an event list.