# Mouse

## core Mouse

This manager handles the interactions between the experiment's stimuli and the mouse.

Note: the unit of Mouse is that of its associated Window.

## Constructor

#### new Mouse(options)

Source:
  - core/Mouse.js, line 21
To Do:
  - visible is not handled at the moment (mouse is always visible)

##### Parameters:

Name | Type | Description
--- | --- | ---
`options` | Object | ###### Properties
Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`name` | String |  |  | the name used when logging messages from this stimulus
`win` | Window |  |  | the associated Window
`autoLog` | boolean | <optional> | `true` | whether or not to log

### Methods

#### clickReset(buttonsopt)

Source:
  - core/Mouse.js, line 315

Reset the clocks associated to the given mouse buttons.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`buttons` | Array.number | <optional> | `[0,1,2]` | the buttons to reset (0: left, 1: center, 2: right)

#### getPos() → {Array.number}

Source:
  - core/Mouse.js, line 58

Get the current position of the mouse in mouse/Window units.

##### Returns:

the position of the mouse in mouse/Window units

Type
  Array.number

#### getPressed(getTimeopt) → {Array.number|Array.<Array.number>}

Source:
  - core/Mouse.js, line 123

Get the status of each button (pressed or released) and, optionally, the time elapsed between the last call to `clickReset` and the pressing or releasing of the buttons.

Note: clickReset is typically called at stimulus onset. When the participant presses a button, the time elapsed since the clickReset is stored internally and can be accessed any time afterwards with getPressed.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`getTime` | boolean | <optional> | `false` | whether or not to also return timestamps

##### Returns:

either an array of size 3 with the status (1 for pressed, 0 for released) of each mouse button [left, center, right], or a tuple with that array and another array of size 3 with the timestamps.

Type
  Array.number | Array.<Array.number>

#### getRel() → {Array.number}

Source:
  - core/Mouse.js, line 80

Get the position of the mouse relative to that at the last call to getRel or getPos, in mouse/Window units.

##### Returns:

the relation position of the mouse in mouse/Window units.

Type
  Array.number

#### getWheelRel() → {Array.number}

Source:
  - core/Mouse.js, line 103

Get the travel of the mouse scroll wheel since the last call to getWheelRel.

Note: Even though this method returns a [x, y] array, for most wheels/systems y is the only value that varies.

##### Returns:

the mouse scroll wheel travel

Type
  Array.number

#### isPressedIn(shape, buttonsopt, optionsopt) → {boolean}

Source:
  - core/Mouse.js, line 147

Helper method for checking whether a stimulus has had any button presses within bounds.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`shape` | object | module:visual.VisualStim |  | A type of visual stimulus or object having a `contains()` method.
`buttons` | object | number | <optional> | The target button index potentially tucked inside an object.
`options` | object | <optional> | ###### Properties
Name | Type | Attributes | Description
--- | --- | --- | ---
`shape` | object | module:visual.VisualStim | <optional> |
`buttons` | number | <optional> |

##### Returns:

Whether button pressed is contained within stimulus.

Type
  boolean

#### mouseMoved(distanceopt, resetopt) → {boolean}

Source:
  - core/Mouse.js, line 213

Determine whether the mouse has moved beyond a certain distance.

distance

- mouseMoved() or mouseMoved(undefined, false): determine whether the mouse has moved at all since the last call to `getPos`
- mouseMoved(distance: number, false): determine whether the mouse has travelled further than distance, in terms of line of sight
- mouseMoved(distance: [number,number], false): determine whether the mouse has travelled horizontally or vertically further then the given horizontal and vertical distances

reset

- mouseMoved(distance, true): reset the mouse move clock, return false
- mouseMoved(distance, 'here'): return false
- mouseMoved(distance, [x: number, y: number]: artifically set the previous mouse position to the given coordinates and determine whether the mouse moved further than the given distance

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`distance` | undefined | number | Array.number | <optional> |  | the distance to which the mouse movement is compared (see above for a full description)
`reset` | boolean | String | Array.number | <optional> | `false` | see above for a full description

##### Returns:

see above for a full description

Type
  boolean

#### mouseMoveTime() → {number}

Source:
  - core/Mouse.js, line 305

Get the amount of time elapsed since the last mouse movement.

##### Returns:

the time elapsed since the last mouse movement

Type
  number