Use the following functions to add mouse device support to your game using the
Game Controller library. We use the term mouse devices here to describe
traditional mice, as well as trackpads or trackballs.

## Add a mouse status callback

The Game Controller library uses a mouse status callback to notify a game when a
mouse is connected or disconnected. It supports only one mouse status callback
at a time.

- To register a mouse status callback or replace any previously registered callback with a new callback function, call the [`Paddleboat_setMouseStatusCallback`](https://developer.android.com/reference/games/game-controller/group/paddleboat#paddleboat_setmousestatuscallback) function.
- To remove any currently registered callback, pass `NULL` or `nullptr` in the `statusCallback` parameter.
- The `userData` parameter is an optional pointer to user defined data. The `userData` parameter will be passed to the callback function. This pointer is retained internally until changed by another call to `Paddleboat_setMouseStatusCallback`.

    void Paddleboat_setMouseStatusCallback(Paddleboat_MouseStatusCallback
      statusCallback, void *userData)

The function signature of the mouse status callback function is:  

    typedef void (*Paddleboat_MouseStatusCallback)(const Paddleboat_MouseStatus
      mouseStatus, void *userData)

The `mouseStatus` enum parameter has three possible values:

- `PADDLEBOAT_MOUSE_NONE`: No mouse device is currently connected.
- `PADDLEBOAT_MOUSE_CONTROLLER_EMULATED`: A connected controller is simulating a mouse.
- `PADDLEBOAT_MOUSE_PHYSICAL`: One or more physical mouse devices are connected. (These devices include a mouse, touchpad, trackball, or other similar devices.)

The `userData` parameter contains the `userData` pointer specified in the last
call to `Paddleboat_setMouseStatusCallback`. `userData` may be NULL or
`nullptr`.

Not all controllers simulate a mouse. Controllers may simulate a mouse using one
of the analog sticks or with an integrated touchpad.

The Game Controller library only reports data from a singular mouse device.
Physical mouse devices take priority over virtual controller mouse devices. If a
physical mouse is connected, it takes over from any previously active virtual
controller mouse.

## Read mouse data

Call the [`Paddleboat_getMouseStatus`](https://developer.android.com/reference/games/game-controller/group/paddleboat#paddleboat_getmousestatus) function to get the status of the mouse device.  

    Paddleboat_MouseStatus Paddleboat_getMouseStatus()

Use the [`Paddleboat_getMouseData`](https://developer.android.com/reference/games/game-controller/group/paddleboat#paddleboat_getmousedata)
function to get the current mouse data. This function returns
`PADDLEBOAT_NO_ERROR` if data is successfully read, otherwise an
appropriate error code is returned.  

    bool Paddleboat_getMouseData(Paddleboat_Mouse_Data *mouseData)

The `Paddleboat_Mouse_Data` structure contains information about:

- The most recent mouse input event timestamp
- The current pointer position
- Status of mouse buttons
- Status of mouse wheels

    struct Paddleboat_Mouse_Data {
        uint64_t timestamp;
        uint32_t buttonsDown;
        int32_t mouseScrollDeltaH;
        int32_t mouseScrollDeltaV;
        float mouseX;
        float mouseY;
    }

| Structure member | Description |
|---|---|
| `timestamp` | Timestamp of the most recent mouse input event. The timestamp value is in microseconds since. clock epoch. |
| `buttonsDown` | Bitfield, each bit starting from bit 0 signifies a button down state if set. |
| `mouseX` `mouseY` | Mouse position in pixel coordinates. Position coordinates have a range of `0.0` to the screen width and height. |
| `mouseScrollDeltaH` `mouseScrollDeltaV` | A count of cumulative mouse scroll wheel events : since the previous call to `Paddleboat_getMouseData`. These values are not guaranteed to be precise, only to give an indication of scroll wheel activity in a particular direction. Most mice have a one scroll wheel, which is reported in `mouseScrollDeltaV`. If a mouse has a side scroll wheel, it is is reported in `mouseScrollDeltaH`. These values are reset to `0` internally after a call to `Paddleboat_getMouseData`. |

The Game Controller library defines bitmask constants for mouse buttons in the
`paddleboat.h` interface header file:  

    enum Paddleboat_Mouse_Buttons {
        PADDLEBOAT_MOUSE_BUTTON_LEFT = (1U << 0),
        PADDLEBOAT_MOUSE_BUTTON_RIGHT = (1U << 1),
        PADDLEBOAT_MOUSE_BUTTON_MIDDLE = (1U << 2),
        PADDLEBOAT_MOUSE_BUTTON_BACK = (1U << 3),
        PADDLEBOAT_MOUSE_BUTTON_FORWARD = (1U << 4),
        PADDLEBOAT_MOUSE_BUTTON_6 = (1U << 5),
        PADDLEBOAT_MOUSE_BUTTON_7 = (1U << 6),
        PADDLEBOAT_MOUSE_BUTTON_8 = (1U << 7)
    };

### Physical versus virtual mouse devices

A `Paddleboat_MouseStatus` of `PADDLEBOAT_MOUSE_CONTROLLER_EMULATED` indicates
that a physical mouse device is absent and the Game Controller library is
simulating a virtual mouse using a connected controller. The lowest connected
controller index with the `PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE` flag set is
used as the virtual mouse. Virtual mouse devices are only guaranteed to report
`mouseX` and `mouseY` coordinates. Virtual mouse devices may report presses from
a single (left) mouse button, but this is not guaranteed.