OpenSesame videos
Python videos

Mouse functions

class mouse

The mouse class is used to collect mouse input.


# Draw a 'fixation-dot mouse cursor' until a button is clicked
my_mouse = mouse()
my_canvas = canvas()
while True:
        button, position, timestamp = my_mouse.get_click(timeout=20)
        if button is not None:
        (x,y), time = my_mouse.get_pos()
        my_canvas.fixdot(x, y)

Things to know


  • When Uniform coordinates is set to 'yes', coordinates are relative to the center of the display. That is, (0,0) is the center. This is the default as of OpenSesame 3.0.0.
  • When Uniform coordinates is set to 'no', coordinates are relative to the top-left of the display. That is, (0,0) is the top-left. This was the default in OpenSesame 2.9.X and earlier.

Button numbers

Mouse buttons are numbered as follows:

  1. Left button
  2. Middle button
  3. Right button
  4. Scroll up
  5. Scroll down

Touch screens

When working with a touch screen, a touch is registered as button 1 (left button).

Response keywords

Functions that accept **resp_args take the following keyword arguments:

  • timeout specifies a timeout value in milliseconds, or is set to None to disable the timeout.
  • buttonlist specifies a list of buttons that are accepted, or is set to None accept all keys.
  • visible indicates whether the mouse cursor becomes visible when a click is collected (True or False). To immediately change cursor visibility, use [mouse.show_cursor].
# Get a left or right button press with a timeout of 3000 ms
my_mouse = mouse()
button, time = my_mouse.get_key(buttonlist=[1,3], timeout=3000)

Response keywords only affect the current operation (except when passed to [mouse.__init__][init]). To change the behavior for all subsequent operations, set the response properties directly:

# Get two key left or right presses with a 5000 ms timeout
my_mouse = mouse()
my_mouse.keylist = [1,3]
my_mouse.timeout = 5000
button1, time1 = my_mouse.get_button()
button2, time2 = my_mouse.get_button()

Or pass the response keywords to [mouse.__init__][init]:

# Get two key left or right presses with a 5000 ms timeout
my_mouse = mouse(keylist=[1,3], timeout=5000)
button1, time1 = my_mouse.get_button()
button2, time2 = my_mouse.get_button()

function mouse.__init__(experiment, **resp_args)

Constructor to create a new mouse object. You do not generally call this constructor directly, but use the mouse() function, which is described here: /python/common/.


my_mouse = mouse(buttonlist=[1, 2], timeout=2000)


  • experiment -- The experiment object.
    • Type: experiment

Keyword dict:

  • **resp_args: Optional [response keywords] that will be used as the default for this mouse object.

function mouse.flush()

Clears all pending input, not limited to the mouse.


my_mouse = mouse()
button, position, timestamp = my_mouse.get_click()


True if a button had been clicked (i.e., if there was something to flush) and False otherwise.

  • Type: bool

function mouse.get_click(**resp_args)

Collects a mouse click.


my_mouse = mouse()
button, (x, y), timestamp = my_mouse.get_click(timeout=5000)
if button is None:
        print('A timeout occurred!')

Keyword dict:

  • **resp_args: Optional [response keywords] that will be used for this call to [mouse.get_click]. This does not affect subsequent operations.


A (button, position, timestamp) tuple. The button and position are None if a timeout occurs. Position is an (x, y) tuple in screen coordinates.

  • Type: tuple

function mouse.get_pos()

Returns the current position of the cursor.


my_mouse = mouse()
(x, y), timestamp = my_mouse.get_pos()
print('The cursor was at (%d, %d)' % (x, y))


A (position, timestamp) tuple.

  • Type: tuple

function mouse.get_pressed()

Returns the current state of the mouse buttons. A True value means the button is currently being pressed.


my_mouse = mouse()
buttons = my_mouse.get_pressed()
b1, b2, b3 = buttons
print('Currently pressed mouse buttons: (%d,%d,%d)' % (b1,b2,b3))


A (button1, button2, button3) tuple of boolean values.

  • Type: tuple.

function mouse.set_pos(pos=(0, 0))

Sets the position of the mouse cursor.

Warning: set_pos() is unreliable and will silently fail on some systems.


my_mouse = mouse()


  • pos -- An (x,y) tuple for the new mouse coordinates.
    • Type: tuple
    • Default: (0, 0)

function mouse.show_cursor(show=True)

Immediately changes the visibility of the mouse cursor.

Note: In most cases, you will want to use the visible [keyword][Response keywords], which changes the visibility during response collection, that is, while mouse.get_click() is called.


  • show -- Indicates whether the cursor is shown (True) or hidden (False).
    • Type: bool
    • Default: True
Supported by Supported by