Add mouse device support

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 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 function to get the status of the mouse device.

Paddleboat_MouseStatus Paddleboat_getMouseStatus()

Use the 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;
}

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.