FabGL
ESP32 VGA Controller and Graphics Library
fabgl::MouseClass Class Reference

The PS2 Mouse controller class. More...

#include <mouse.h>

Inheritance diagram for fabgl::MouseClass:
Collaboration diagram for fabgl::MouseClass:

Public Member Functions

int availableStatus ()
 Gets the number of available mouse status. More...
 
void begin (gpio_num_t clkGPIO, gpio_num_t dataGPIO)
 Initializes MouseClass specifying CLOCK and DATA GPIOs. More...
 
void begin (int PS2Port)
 Initializes MouseClass without initializing the PS/2 controller. More...
 
int deltaAvailable ()
 Determines the number of mouse movements available in the queue. More...
 
bool getNextDelta (MouseDelta *delta, int timeOutMS=-1, bool requestResendOnTimeOut=false)
 Gets a mouse movement from the queue. More...
 
MouseStatus getNextStatus (int timeOutMS=-1)
 Gets the next status from the status queue. More...
 
PS2Device identify ()
 Identifies the device attached to the PS2 port. More...
 
bool isMouseAvailable ()
 Checks if mouse has been detected and correctly initialized. More...
 
bool lock (int timeOutMS)
 Gets exclusive access to the device. More...
 
int & movementAcceleration ()
 Gets or set mouse movement acceleration factor. More...
 
bool reset ()
 Sends a Reset command to the mouse. More...
 
bool setResolution (int value)
 Sets the resolution. More...
 
bool setSampleRate (int value)
 Sets the maximum rate of mouse movements reporting. More...
 
bool setScaling (int value)
 Sets the scaling. More...
 
void setUIApp (uiApp *app)
 Sets current UI app. More...
 
void setupAbsolutePositioner (int width, int height, bool createAbsolutePositionsQueue, bool updateVGAController, uiApp *app)
 Initializes absolute position handler. More...
 
MouseStatusstatus ()
 Gets or sets current mouse status. More...
 
void terminateAbsolutePositioner ()
 Terminates absolute position handler. More...
 
void unlock ()
 Releases device from exclusive access. More...
 
void updateAbsolutePosition (MouseDelta *delta)
 Updates absolute position from the specified mouse delta event. More...
 
int & wheelAcceleration ()
 Gets or sets wheel acceleration factor. More...
 

Detailed Description

The PS2 Mouse controller class.

MouseClass connects to one port of the PS2 Controller class (fabgl::PS2ControllerClass) to decode and get mouse movements.
At the moment MouseClass supports standard PS/2 mouse (X and Y axis with three buttons) and Microsoft Intellimouse compatible mouse (X and Y axis, scroll wheel with three buttons).
MouseClass allows to set movement parameters, like sample rate, resolution and scaling.
The PS2 controller uses ULP coprocessor and RTC slow memory to communicate with the PS2 device.

Applications do not need to create an instance of MouseClass because an instance named Mouse is created automatically.
Because fabgl::PS2ControllerClass supports up to two PS/2 ports, it is possible to have connected two PS/2 devices. The most common configuration is Keyboard on port 0 and Mouse on port 1. However you may have two mice connected at the same time using the Mouse instance on port 0 and creating a new one on port 1.

Example:

// Setup pins GPIO26 for CLK and GPIO27 for DATA
Mouse.begin(GPIO_NUM_26, GPIO_NUM_27);

if (Mouse.deltaAvailable()) {
  MouseDelta mouseDelta;
  Mouse.getNextDelta(&mouseDelta);

  Serial.printf("deltaX = %d  deltaY = %d  deltaZ = %d  leftBtn = %d  midBtn = %d  rightBtn = %d\n",
                mouseDelta.deltaX, mouseDelta.deltaY, mouseDelta.deltaZ,
                mouseDelta.leftButton, mouseDelta.middleButton, mouseDelta.rightButton);
}

Member Function Documentation

◆ availableStatus()

int fabgl::MouseClass::availableStatus ( )

Gets the number of available mouse status.

Mouse status contains absolute mouse position, scroll wheel delta and buttons status.
Mouse status queue is populated only when createAbsolutePositionsQueue parameter of MouseClass.setupAbsolutePositioner() is true.

Returns
Number of available mouse status.

◆ begin() [1/2]

void fabgl::MouseClass::begin ( gpio_num_t  clkGPIO,
gpio_num_t  dataGPIO 
)

Initializes MouseClass specifying CLOCK and DATA GPIOs.

A reset command (MouseClass.reset() method) is automatically sent to the mouse.
This method also initializes the PS2ControllerClass to use port 0 only.

Parameters
clkGPIOThe GPIO number of Clock line
dataGPIOThe GPIO number of Data line

Example:

// Setup pins GPIO26 for CLK and GPIO27 for DATA
Mouse.begin(GPIO_NUM_26, GPIO_NUM_27);

◆ begin() [2/2]

void fabgl::MouseClass::begin ( int  PS2Port)

Initializes MouseClass without initializing the PS/2 controller.

A reset command (MouseClass.reset() method) is automatically sent to the mouse.
This method does not initialize the PS2ControllerClass.

Parameters
PS2PortThe PS/2 port to use (0 or 1).

Example:

// Setup pins GPIO26 for CLK and GPIO27 for DATA on port 0
PS2Controller.begin(GPIO_NUM_26, GPIO_NUM_27); // clk, dat
Mouse.begin(0); // port 0

◆ deltaAvailable()

int fabgl::MouseClass::deltaAvailable ( )

Determines the number of mouse movements available in the queue.

Returns
The number of mouse movements (deltas) available to read.
Examples:
MouseStudio/MouseStudio.ino, and SpaceInvaders/SpaceInvaders.ino.

◆ getNextDelta()

bool fabgl::MouseClass::getNextDelta ( MouseDelta delta,
int  timeOutMS = -1,
bool  requestResendOnTimeOut = false 
)

Gets a mouse movement from the queue.

Parameters
deltaPointer to MouseDelta structure to be filled with mouse movement. May be nullptr if not required (in this case only Status().buttons is updated.
timeOutMSTimeout in milliseconds. -1 means no timeout (infinite time).
requestResendOnTimeOutIf true and timeout has expired then asks the mouse to resend the mouse movement.
Returns
True if the mouse movement structure has been filled. False when there is no data in the queue.

Example:

MouseDelta mouseDelta;
Mouse.getNextDelta(&mouseDelta);
Examples:
MouseStudio/MouseStudio.ino, and SpaceInvaders/SpaceInvaders.ino.

◆ getNextStatus()

MouseStatus fabgl::MouseClass::getNextStatus ( int  timeOutMS = -1)

Gets the next status from the status queue.

Mouse status contains absolute mouse position, scroll wheel delta and buttons status.
Mouse status queue is populated only when createAbsolutePositionsQueue parameter of MouseClass.setupAbsolutePositioner() is true.

Parameters
timeOutMSTimeout in milliseconds to wait for a new status. -1 = wait forever.
Returns
The next status in queue.

Example:

// wait for events from mouse and draw a pixel at the mouse position if left button is down
MouseStatus status = Mouse.getNextStatus();
if (status.buttons.left) {
  Canvas.setPenColor(Color::BrightRed);
  Canvas.setPixel(status.X, status.Y);
}
Examples:
MouseOnScreen/MouseOnScreen.ino.

◆ identify()

PS2Device fabgl::PS2DeviceClass::identify ( )
inlineinherited

Identifies the device attached to the PS2 port.

Returns
The identification ID sent by keyboard.
Examples:
KeyboardStudio/KeyboardStudio.ino, and MouseStudio/MouseStudio.ino.

◆ isMouseAvailable()

bool fabgl::MouseClass::isMouseAvailable ( )
inline

Checks if mouse has been detected and correctly initialized.

isMouseAvailable() returns a valid value only after MouseClass.begin() or MouseClass.reset() has been called.

Returns
True if the mouse is correctly initialized.
Examples:
MouseStudio/MouseStudio.ino, and SpaceInvaders/SpaceInvaders.ino.

◆ lock()

bool fabgl::PS2DeviceClass::lock ( int  timeOutMS)
inherited

Gets exclusive access to the device.

Parameters
timeOutMSTimeout in milliseconds to wait before fail.
Returns
True if the device has been locked.

◆ movementAcceleration()

int& fabgl::MouseClass::movementAcceleration ( )
inline

Gets or set mouse movement acceleration factor.

Mouse movement acceleration is calculated in MouseClass.updateAbsolutePosition() and depends by the acceleration factor and time of call.
Lower values generate little acceleration, high values generate a lot of acceleration.
Suggested range is 0 ... 2000. Default value is 180.

◆ reset()

bool fabgl::MouseClass::reset ( )

Sends a Reset command to the mouse.

Returns
True if the mouse is correctly initialized.
Examples:
MouseStudio/MouseStudio.ino.

◆ setResolution()

bool fabgl::MouseClass::setResolution ( int  value)
inline

Sets the resolution.

Resolution is the amount by which the movement counters are incremented/decremented measured as counts per millimeter.
The default resolution is 4 counts/mm.

Parameters
valueResolution encoded as follows: 0 = 1 count/mm (25 dpi), 1 = 2 counts/mm (50 dpi), 2 = 4 counts/mm (100 dpi), 3 = 8 counts/mm (200 dpi).
Returns
True if command has been successfully delivered to the mouse.
Examples:
MouseStudio/MouseStudio.ino.

◆ setSampleRate()

bool fabgl::MouseClass::setSampleRate ( int  value)
inline

Sets the maximum rate of mouse movements reporting.

The default sample rate is 60 samples/sec.

Parameters
valueSample rate as samples per second. Valid values: 10, 20, 40, 60, 80, 100, and 200.
Returns
True if command has been successfully delivered to the mouse.
Examples:
MouseStudio/MouseStudio.ino, and SpaceInvaders/SpaceInvaders.ino.

◆ setScaling()

bool fabgl::MouseClass::setScaling ( int  value)
inline

Sets the scaling.

The default scaling is 1:1.

Parameters
valueScaling encoded as follows: 1 = 1:1, 2 = 1:2.
Returns
True if command has been successfully delivered to the mouse.
Examples:
MouseStudio/MouseStudio.ino.

◆ setUIApp()

void fabgl::MouseClass::setUIApp ( uiApp app)
inline

Sets current UI app.

Parameters
appThe UI app where to send mouse events

◆ setupAbsolutePositioner()

void fabgl::MouseClass::setupAbsolutePositioner ( int  width,
int  height,
bool  createAbsolutePositionsQueue,
bool  updateVGAController,
uiApp app 
)

Initializes absolute position handler.

Use this method to specify the absolute mouse area inside the rectangle (0, 0) to (width - 1, height - 1).
Optinally this method creates a queue that stores absolute positions generated by updateAbsolutePosition().
This method must be called one time to initialize absolute positioning.

Parameters
widthAbsolute mouse area width. Mouse can travel from 0 up to width - 1.
heightAbsolute mouse area height. Mouse can travel from 0 up to height - 1.
createAbsolutePositionsQueueIf true a queue of absolute positions is created.
updateVGAControllerIf true VGA controller mouse pointer is automatically updated.
appOptional fabgl::uiApp where to send mouse events.

Example:

Mouse.setupAbsolutePositioner(Canvas.getWidth(), Canvas.getHeight(), true, true, nullptr);
Examples:
MouseOnScreen/MouseOnScreen.ino, and SpaceInvaders/SpaceInvaders.ino.

◆ status()

MouseStatus& fabgl::MouseClass::status ( )
inline

Gets or sets current mouse status.

Examples:
MouseOnScreen/MouseOnScreen.ino, and SpaceInvaders/SpaceInvaders.ino.

◆ terminateAbsolutePositioner()

void fabgl::MouseClass::terminateAbsolutePositioner ( )

Terminates absolute position handler.

◆ unlock()

void fabgl::PS2DeviceClass::unlock ( )
inherited

Releases device from exclusive access.

◆ updateAbsolutePosition()

void fabgl::MouseClass::updateAbsolutePosition ( MouseDelta delta)

Updates absolute position from the specified mouse delta event.

This method updates absolute mouse position, mouse wheel and buttons status.
In order to improve quality of acceleration it is important to call updateAbsolutePosition() often and at constant frequency.
updateAbsolutePosition() is automatically executed when updateVGAController or createAbsolutePositionsQueue parameters of MouseClass.setupAbsolutePositioner() is true.

Parameters
deltaMouse event to process.

Example:

// move a sprite (previously defined) at mouse absolute position
void loop() {
  MouseDelta delta;
  if (getNextDelta(&delta)) {
    Mouse.updateAbsolutePosition(&delta);
    mouseSprite.moveTo(Mouse.position().X, Mouse.position().Y);
  }
}
Examples:
SpaceInvaders/SpaceInvaders.ino.

◆ wheelAcceleration()

int& fabgl::MouseClass::wheelAcceleration ( )
inline

Gets or sets wheel acceleration factor.

Wheel acceleration is calculated in MouseClass.updateAbsolutePosition() and depends by the acceleration factor and time of call.
Lower values generate little acceleration, high values generate a lot of acceleration.
Suggested range is 0 ... 100000. Default value is 60000.


The documentation for this class was generated from the following files: