expyriment.io.Mouse¶

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

A class implementing a mouse input.

Calling expyriment.control.intialize(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, quit_click_rect_size=None)¶

Initialize a mouse input.

Parameters:

show_cursor : bool, optional

shows mouse cursor (default = True)

track_button_events : bool, optional

track button events via Pygame queue (default = True)

track_motion_events : bool, 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) 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_number : int

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

Returns:

is_pressed: boolean

check_wheel()¶

Check the mouse wheel.

Returns:

direction : str

“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_event : boolean, 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_id : int

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_id : int

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_events : bool, optional

tracking button events (default = False)

track_motion_events : bool, optional

tracking motion events (default = False)

is_cursor_visible¶: Getter for is_cursor_visible

logging¶: Getter for logging.

position¶: Getter for position.

pressed_buttons¶: Getter for pressed_buttons.

static process_quit_event(click_position=None)¶

Check if mouse exit action has been performed

If Mouse.quit_rect_location is defined (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.

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

Parameters:

click_position : tuple 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

Returns:

out : bool, optional

True if exit action has been performed False otherwise

Notes

To switch on or off the detection of mouse quit events, please use the static class property quit_rect_location (see below).

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

Static class properties:

Mouse.quit_rect_location = int, optional
    Location of the quit click action field or None.

    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.

    Default value under Android is 1, otherwise None

Mouse.quit_click_rect_size = tuple (int, int)
    size of the field (rect) that detects the quit action by
    triple clicking in one corner of the screen. (default = (30, 30))

Changing the static class properties affects always all mouse instances.

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)

xormask : list

sequence of bytes with cursor xor data masks

andmask : list

sequence of bytes with cursor bitmask data

set_logging(onoff)¶

Set logging of this object on or off

Parameters:

onoff : bool

set logging on (True) or off (False)

Notes

See also design.experiment.set_log_level fur further information about event logging.

show_cursor(track_button_events=True, track_motion_events=False)¶

Show the cursor.

Parameters:

track_button_events : bool, optional

tracking button events (default = True)

track_motion_events : bool, optional

tracking motion events (default = False)

track_button_events¶: Getter for track_button_events.

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)¶

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_button : bool, optional

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

wait_motion : bool, optional

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

buttons : int or list, optional

a specific button or list of buttons to wait for

duration : int, optional

the maximal time to wait in ms

wait_for_buttonup : bool, optional

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

callback_function : function, optional

function to repeatedly execute during waiting loop

process_control_events : bool, optional

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

Returns:

event_id : int

id of the event that quited waiting

move : bool

True if a motion occured

pos : (int, int)

mouse position (tuple)

rt : int

reaction time