expyriment.io.Mouse

class expyriment.io.Mouse(show_cursor=True, track_button_events=None, track_motion_events=None)

A class implementing a mouse input.

Calling expyriment.control.initialise(exp) will automatically create a mouse instance and will reference it in exp.mouse for easy access.

__init__(show_cursor=True, track_button_events=None, track_motion_events=None)

initialise a mouse input.

Parameters:

show_cursorbool, optional

shows mouse cursor (default = True)

track_button_eventsbool, optional

track button events via Pygame queue (default = True)

track_motion_eventsbool, optional

track motion events via Pygame queue (default = False)

Notes

(a) It is strongly suggest to avoid tracking of motions events, (track_motion_events=True), because it quickly causes an overflow in the Pygame event queue and you might consequently loose important events.

(b) Turning the mouse wheel causes button_down_events. Thus, turning the mouse wheel rather extensively causes an overflow of the Pygame event queue. You might consider turn off the default tracking of mouse button event by calling experiment.mouse.track_button_events = False.

(c) See process_quit_event for the forced quitting of experiments via mouse events.

check_button_pressed(button_number)

Return False or button id if a specific button is currently pressed.

Parameters:

button_numberint

the button number (0,1,2) to be checked

Returns:

is_pressed: boolean

check_wheel()

Check the mouse wheel.

Returns:

directionstr

“up” or “down” if mouse wheel has been recently rotated upwards or downwards otherwise it returns None.

clear()

Clear the event cue from mouse events.

get_cursor()

Get the cursor.

get_last_button_down_event(process_quit_event=True)

Get the last button down event. All earlier button down events will be removed from the queue.

Parameters:

process_quit_eventboolean, optional

if False, the current location will not be processed for mouse quitting events in the case that a button down event has been found (default = True).

Returns:

btn_idint

button number (0,1,2) or 3 for wheel up or 4 for wheel down, if quit screen mouse action has been performed, the method returns -1

get_last_button_up_event()

Get the last button up event. All earlier button up events will be removed from the queue.

Returns:

btn_idint

button number (0,1,2) if quit screen mouse action has been performed, the method returns -1

hide_cursor(track_button_events=False, track_motion_events=False)

Hide the cursor.

Parameters:

track_button_eventsbool, optional

tracking button events (default = False)

track_motion_eventsbool, optional

tracking motion events (default = False)

property is_cursor_visible

Getter for is_cursor_visible

property logging

Getter for logging.

property position

Getter for position.

property pressed_buttons

Getter for pressed_buttons.

static process_quit_event(click_position=None, event_detected_function=None, quit_confirmed_function=None, quit_denied_function=None)

Check if mouse exit action has been performed.

If quit corner location is has been defined via Mouse.set_quit_corner_location() (i.e. 0, 1, 2 or 3), clicking quickly three times (i.e., within 1 second) in one of the corners of the screen forces the experiment to quit.

The function is called automatically by all mouse get event and wait methods (similar to Keyboard.process_control_keys). If no mouse functions are called by your program, this function can be polled to ensure quitting experiment by mouse.

Parameters:

click_positiontuple of int (x,y), optional

clicked location to be processed. If not defined, the Pygame event queue will be checked for mouse down events and the current position is taken

event_detected_functionfunction, optional

function to be called when key event is detected.

quit_confirmed_functionfunction, optional

function to be called if quitting has been confirmed.

quit_denied_functionfunction, optional

function to be called if quitting has been denied.

Returns:

outbool, optional

True if exit action has been performed False otherwise

See also

set_quit_corner_location

set_cursor(size, hotspot, xormasks, andmasks)

Set the cursor.

Parameters:

size(int, int)

size of the cursor

hotspot(int, int)

position of the hotspot (0,0 is top left)

xormasklist

sequence of bytes with cursor xor data masks

andmasklist

sequence of bytes with cursor bitmask data

set_logging(onoff)

Set logging of this object on or off

Parameters:

onoffbool

set logging on (True) or off (False)

See also

expyriment.design.Experiment.set_log_level

static set_quit_corner_location(corner, corner_rect_size=(None, None))

Activate the possibility to quit experiment using a mouse event.

Defines the corner on which the user has to click to elicit a quit dialog.

If quit corner location has been defined, clicking quickly three times (i.e., within 1 second) in the specified corner forces experiment to quit.

To switch off the detection of mouse quit events, please call Mouse.set_quit_corner_location(corner=None).

Changing the corner and rect_size always affects all mouse instances.

Parameters:

corner: int or None

location code (0,1, 2 or 3) of the quit corner; the default value under Android is 1, otherwise None; see also the notes below.

corner_rect_size = tuple (int, int), optional

size of the field (rect) that detects the quit action in one corner of the screen; default = (30, 30)

Notes

Mouse quit events are especially useful for experiments on devices without hardware keyboard, such as tablet PCs or smartphones.

Corner location codes:

0 = upper left corner,  1 = upper right corner   (0) (1)
2 = lower right corner, 3 = lower left corner    (3) (2)
otherwise the detection of mouse quit events is deactivated

The detection of mouse quit events is activated by default under Android.

show_cursor(track_button_events=True, track_motion_events=False)

Show the cursor.

Parameters:

track_button_eventsbool, optional

tracking button events (default = True)

track_motion_eventsbool, optional

tracking motion events (default = False)

property track_button_events

Getter for track_button_events.

property track_motion_events

Getter for track_motion_events.

Switch on/off the buffering of motion events in the Pygame event queue.

Notes

It is strongly suggest to avoid tracking of motions events, (track_motion_events=True), because it quickly causes an overflow in the Pygame event queue and you might consequently loose important events.

wait_event(wait_button=True, wait_motion=True, buttons=None, duration=None, wait_for_buttonup=False, callback_function=None, process_control_events=True, low_performance=False)

Wait for a mouse event (i.e., motion, button press or wheel event).

Button id coding:

• None for no mouse button event or

• 0,1,2 for left. middle and right button or

• 3 for wheel up or

• 4 for wheel down (wheel works only for keydown events).

Parameters:

wait_buttonbool, optional

set ‘False’ to ignore for a button presses (default=True)

wait_motionbool, optional

set ‘False’ to ignore for a mouse motions (default=True)

buttonsint or list, optional

a specific button or list of buttons to wait for

durationint, optional

the maximal time to wait in ms

wait_for_buttonupbool, optional

if True it waits for button-up default=False)

callback_functionfunction, optional

function to repeatedly execute during waiting loop

process_control_eventsbool, optional

process io.keyboard.process_control_keys() and io.mouse.process_quit_event() (default = True)

low_performancebool, optional

reduce CPU performance (and allow potential threads to run) while waiting at the cost of less timing accuracy (default = False)

Returns:

event_idint

id of the event that quit waiting

movebool

True if a motion occurred

pos(int, int)

mouse position (tuple)

rtint

reaction time

See also

expyriment.design.Experiment.register_wait_callback_function

Notes

This will also by default process control events (quit and pause). Thus, keyboard events will be cleared from the cue and cannot be received by a Keyboard().check() anymore!

wait_motion(duration=None, callback_function=None, process_control_events=True, low_performance=False)

Wait for a mouse motion.

Parameters:

durationint, optional

maximal time to wait in ms

callback_functionfunction, optional

function to repeatedly execute during waiting loop

process_control_eventsbool, optional

process io.keyboard.process_control_keys() and io.mouse.process_quit_event() (default = false)

low_performancebool, optional

reduce CPU performance (and allow potential threads to run) while waiting at the cost of less timing accuracy (default = False)

Returns:

pos(int, int)

mouse position (tuple)

rtint

reaction time

wait_press(buttons=None, duration=None, wait_for_buttonup=False, callback_function=None, process_control_events=True, low_performance=False)

Wait for a mouse button press or mouse wheel event.

Parameters:

buttonsint or list, optional

a specific button or list of buttons to wait for

durationint, optional

maximal time to wait in ms

wait_for_buttonupbool, optional

if True it waits for button-up

callback_functionfunction, optional

function to repeatedly execute during waiting loop

process_control_eventsbool, optional

process io.keyboard.process_control_keys() and io.mouse.process_quit_event() (default = false)

low_performancebool, optional

reduce CPU performance (and allow potential threads to run) while waiting at the cost of less timing accuracy (default = False)

Returns:

event_idint

id of the event that quit waiting

pos(int, int)

mouse position (tuple)

rtint

reaction time

Notes

button id coding

• None for no mouse button event or

• 0,1,2 for left. middle and right button or

• 3 for wheel up or

• 4 for wheel down (wheel works only for keydown events).