.. _iohub_mouse:

########################
The ioHub Mouse Device
########################

**Platforms:** Windows, macOS, Linux

.. autoclass:: psychopy.iohub.devices.mouse.Mouse
    :members: getPosition, setPosition, getEvents, clearEvents, getPositionAndDelta, getScroll, setScroll
    :member-order: bysource

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.

.. autoclass:: psychopy.iohub.devices.mouse.MouseMoveEvent(object)

    .. attribute:: time

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

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

    .. attribute:: y_position

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

    .. attribute:: scroll_x

        Horizontal scroll wheel absolute position when the event occurred.
        macOS only. Always 0 on other OS's.

    .. attribute:: scroll_y

        Vertical scroll wheel absolute position when the event occurred.

    .. attribute:: modifiers

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

    .. attribute:: 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.

    .. attribute:: window_id

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

    .. attribute:: 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.

    .. attribute:: 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.
    
.. autoclass:: psychopy.iohub.devices.mouse.MouseDragEvent(object)

    .. attribute:: time

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

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

    .. attribute:: button_state

        1 if a mouse button press caused the event, 0 if button was released.
        
    .. attribute:: 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.

    .. attribute:: pressed_buttons

        All currently pressed button id's logically OR'ed together.
        
    .. attribute:: y_position

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

    .. attribute:: scroll_x

        Horizontal scroll wheel absolute position when the event occurred.
        macOS only. Always 0 on other OS's.

    .. attribute:: scroll_y

        Vertical scroll wheel absolute position when the event occurred.

    .. attribute:: modifiers

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

    .. attribute:: 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.

    .. attribute:: window_id

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

    .. attribute:: 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.

    .. attribute:: 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.
        
.. autoclass:: psychopy.iohub.devices.mouse.MouseButtonPressEvent(object)

    .. attribute:: time

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

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

    .. attribute:: button_state

        1 if a mouse button press caused the event, 0 if button was released.
        
    .. attribute:: 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.

    .. attribute:: pressed_buttons

        All currently pressed button id's logically OR'ed together.
        
    .. attribute:: y_position

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

    .. attribute:: scroll_x

        Horizontal scroll wheel absolute position when the event occurred.
        macOS only. Always 0 on other OS's.

    .. attribute:: scroll_y

        Vertical scroll wheel absolute position when the event occurred.

    .. attribute:: modifiers

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

    .. attribute:: 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.

    .. attribute:: window_id

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

    .. attribute:: 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.

    .. attribute:: 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.
        
.. autoclass:: psychopy.iohub.devices.mouse.MouseButtonReleaseEvent(object)

    .. attribute:: time

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

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

    .. attribute:: button_state

        1 if a mouse button press caused the event, 0 if button was released.
        
    .. attribute:: 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.

    .. attribute:: pressed_buttons

        All currently pressed button id's logically OR'ed together.
        
    .. attribute:: y_position

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

    .. attribute:: scroll_x

        Horizontal scroll wheel absolute position when the event occurred.
        macOS only. Always 0 on other OS's.

    .. attribute:: scroll_y

        Vertical scroll wheel absolute position when the event occurred.

    .. attribute:: modifiers

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

    .. attribute:: 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.

    .. attribute:: window_id

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

    .. attribute:: 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.

    .. attribute:: 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.
        
.. autoclass:: psychopy.iohub.devices.mouse.MouseScrollEvent(object)

    .. attribute:: time

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

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

    .. attribute:: button_state

        1 if a mouse button press caused the event, 0 if button was released.
        
    .. attribute:: 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.

    .. attribute:: pressed_buttons

        All currently pressed button id's logically OR'ed together.
        
    .. attribute:: y_position

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

    .. attribute:: scroll_x

        Horizontal scroll wheel absolute position when the event occurred.
        macOS only. Always 0 on other OS's.

    .. attribute:: scroll_dx

        Horizontal scroll wheel position change when the event occurred.
        macOS only. Always 0 on other OS's.

    .. attribute:: scroll_y

        Vertical scroll wheel absolute position when the event occurred.

    .. attribute:: scroll_dy

        Vertical scroll wheel position change when the event occurred.

    .. attribute:: modifiers

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

    .. attribute:: 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.

    .. attribute:: window_id

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

    .. attribute:: 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.

    .. attribute:: 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.
        