# Mouse

Class · extends [`EventHandler`](https://api.playcanvas.com/engine/classes/EventHandler.md) · category: Input Devices

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/platform/input/mouse.js#L36

Manages mouse input by tracking button states and dispatching events. Extends [EventHandler](https://api.playcanvas.com/engine/classes/EventHandler.md)
to fire `mousedown`, `mouseup`, `mousemove` and `mousewheel` events (see [MouseEvent](https://api.playcanvas.com/engine/classes/MouseEvent.md)).

Allows the state of mouse buttons to be queried to check if they are currently pressed or were
pressed/released since the last update. Provides methods to enable/disable pointer lock for
raw mouse movement input and control over the context menu. The class automatically clears
button states when the window loses focus or the document becomes hidden, without firing
`mouseup` events. The Mouse instance must be attached to a DOM element before it can detect
mouse events.

The first unlocked mouse movement after creation, detachment or focus loss establishes a new
position and reports zero movement delta. Movement outside the target also invalidates the
position, so re-entry reports zero delta. Pointer-locked movement uses the browser's relative
movement deltas.

Your application's Mouse instance is managed and accessible via [AppBase#mouse](https://api.playcanvas.com/engine/classes/AppBase.md#mouse).

For pointer-lock-aware, frame-accumulated input deltas rather than raw events, see
[KeyboardMouseSource](https://api.playcanvas.com/engine/classes/KeyboardMouseSource.md), [GamepadSource](https://api.playcanvas.com/engine/classes/GamepadSource.md) and [MultiTouchSource](https://api.playcanvas.com/engine/classes/MultiTouchSource.md), which feed
[InputController](https://api.playcanvas.com/engine/classes/InputController.md)s such as [OrbitController](https://api.playcanvas.com/engine/classes/OrbitController.md), [FlyController](https://api.playcanvas.com/engine/classes/FlyController.md) and
[FocusController](https://api.playcanvas.com/engine/classes/FocusController.md).

## Constructors

### constructor

```ts
new Mouse(element?: Element)
```

Create a new Mouse instance.

**Parameters**

- `element` (`Element`, optional): The Element that the mouse events are attached to.

## Methods

### attach

```ts
attach(element: Element): void
```

Attach mouse events to an Element. If already attached, this changes the target element
while preserving current and previous button states, unlike [Keyboard#attach](https://api.playcanvas.com/engine/classes/Keyboard.md#attach).

**Parameters**

- `element` (`Element`): The DOM element to attach the mouse to.

### detach

```ts
detach(): void
```

Remove mouse events from the element that it is attached to and clear current and previous
button states. The previous mouse position is also invalidated so the next unlocked movement
reports zero delta. This does not fire `mouseup` events.

### disableContextMenu

```ts
disableContextMenu(): void
```

Disable the context menu usually activated with right-click.

### disablePointerLock

```ts
disablePointerLock(success?: LockMouseCallback): void
```

Return control of the mouse cursor to the user.

**Parameters**

- `success` ([`LockMouseCallback`](https://api.playcanvas.com/engine/types/LockMouseCallback.md), optional): Function called when the mouse lock is disabled.

### enableContextMenu

```ts
enableContextMenu(): void
```

Enable the context menu usually activated with right-click. This option is active by
default.

### enablePointerLock

```ts
enablePointerLock(success?: LockMouseCallback, error?: LockMouseCallback): void
```

Request that the browser hides the mouse cursor and locks the mouse to the element. Allowing
raw access to mouse movement input without risking the mouse exiting the element. Notes:

- In some browsers this will only work when the browser is running in fullscreen mode. See
[Fullscreen API](https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API) for
more details.
- Enabling pointer lock can only be initiated by a user action e.g. in the event handler for
a mouse or keyboard input.

**Parameters**

- `success` ([`LockMouseCallback`](https://api.playcanvas.com/engine/types/LockMouseCallback.md), optional): Function called if the request for mouse lock is
  successful.
- `error` ([`LockMouseCallback`](https://api.playcanvas.com/engine/types/LockMouseCallback.md), optional): Function called if the request for mouse lock is
  unsuccessful.

### isPressed

```ts
isPressed(button: number): boolean
```

Returns true if the mouse button is currently pressed.

**Parameters**

- `button` (`number`): The mouse button to test. Can be:

  - [MOUSEBUTTON_LEFT](https://api.playcanvas.com/engine/variables/MOUSEBUTTON_LEFT.md)
  - [MOUSEBUTTON_MIDDLE](https://api.playcanvas.com/engine/variables/MOUSEBUTTON_MIDDLE.md)
  - [MOUSEBUTTON_RIGHT](https://api.playcanvas.com/engine/variables/MOUSEBUTTON_RIGHT.md)

**Returns** `boolean`: True if the mouse button is current pressed.

### update

```ts
update(): void
```

Update method, should be called once per frame.

### wasPressed

```ts
wasPressed(button: number): boolean
```

Returns true if the mouse button was pressed this frame (since the last call to update).

**Parameters**

- `button` (`number`): The mouse button to test. Can be:

  - [MOUSEBUTTON_LEFT](https://api.playcanvas.com/engine/variables/MOUSEBUTTON_LEFT.md)
  - [MOUSEBUTTON_MIDDLE](https://api.playcanvas.com/engine/variables/MOUSEBUTTON_MIDDLE.md)
  - [MOUSEBUTTON_RIGHT](https://api.playcanvas.com/engine/variables/MOUSEBUTTON_RIGHT.md)

**Returns** `boolean`: True if the mouse button was pressed since the last update.

### wasReleased

```ts
wasReleased(button: number): boolean
```

Returns true if the mouse button was released this frame (since the last call to update).

**Parameters**

- `button` (`number`): The mouse button to test. Can be:

  - [MOUSEBUTTON_LEFT](https://api.playcanvas.com/engine/variables/MOUSEBUTTON_LEFT.md)
  - [MOUSEBUTTON_MIDDLE](https://api.playcanvas.com/engine/variables/MOUSEBUTTON_MIDDLE.md)
  - [MOUSEBUTTON_RIGHT](https://api.playcanvas.com/engine/variables/MOUSEBUTTON_RIGHT.md)

**Returns** `boolean`: True if the mouse button was released since the last update.

### isPointerLocked

```ts
static isPointerLocked(): boolean
```

Check if the mouse pointer has been locked, using [enablePointerLock](https://api.playcanvas.com/engine/classes/Mouse.md#enablepointerlock).

**Returns** `boolean`: True if locked.

## Events

### EVENT_MOUSEDOWN

```ts
static EVENT_MOUSEDOWN: string = 'mousedown'
```

Fired when a mouse button is pressed. The handler is passed a [MouseEvent](https://api.playcanvas.com/engine/classes/MouseEvent.md).

**Example**

```ts
app.mouse.on('mousedown', (e) => {
    console.log(`The ${e.button} button was pressed at position: ${e.x}, ${e.y}`);
});
```

### EVENT_MOUSEMOVE

```ts
static EVENT_MOUSEMOVE: string = 'mousemove'
```

Fired when the mouse is moved. The handler is passed a [MouseEvent](https://api.playcanvas.com/engine/classes/MouseEvent.md).

**Example**

```ts
app.mouse.on('mousemove', (e) => {
    console.log(`Current mouse position is: ${e.x}, ${e.y}`);
});
```

### EVENT_MOUSEUP

```ts
static EVENT_MOUSEUP: string = 'mouseup'
```

Fired when a mouse button is released. The handler is passed a [MouseEvent](https://api.playcanvas.com/engine/classes/MouseEvent.md).

**Example**

```ts
app.mouse.on('mouseup', (e) => {
    console.log(`The ${e.button} button was released at position: ${e.x}, ${e.y}`);
});
```

### EVENT_MOUSEWHEEL

```ts
static EVENT_MOUSEWHEEL: string = 'mousewheel'
```

Fired when a mouse wheel is moved. The handler is passed a [MouseEvent](https://api.playcanvas.com/engine/classes/MouseEvent.md).

**Example**

```ts
app.mouse.on('mousewheel', (e) => {
    console.log(`The mouse wheel was moved by ${e.wheelDelta}`);
});
```

## Inherited from [EventHandler](https://api.playcanvas.com/engine/classes/EventHandler.md)

- `fire(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any): EventHandler`
- `hasEvent(name: string): boolean`
- `off(name?: string, callback?: HandleEventCallback, scope?: any): EventHandler`
- `on(name: string, callback: HandleEventCallback, scope?: any): EventHandle`
- `once(name: string, callback: HandleEventCallback, scope?: any): EventHandle`