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 ()
 Get the number of available mouse status. More...
 
void begin (gpio_num_t clkGPIO, gpio_num_t dataGPIO)
 Initialize MouseClass specifying CLOCK and DATA GPIOs. More...
 
void begin (int PS2Port)
 Initialize MouseClass without initializing the PS/2 controller. More...
 
int deltaAvailable ()
 Get the number of mouse movements available in the queue. More...
 
bool getNextDelta (MouseDelta *delta, int timeOutMS=-1, bool requestResendOnTimeOut=false)
 Get a mouse movement from the queue. More...
 
MouseStatus getNextStatus (int timeOutMS=-1)
 Get the next status from the status queue. More...
 
PS2Device identify ()
 Identify the device attached to the PS2 port. More...
 
bool isMouseAvailable ()
 Check if mouse has been detected and correctly initialized. More...
 
bool lock (int timeOutMS)
 Get exclusive access to the device. More...
 
int & movementAcceleration ()
 Get or set mouse movement acceleration factor. More...
 
bool reset ()
 Send a Reset command to the mouse. More...
 
bool setResolution (int value)
 Set the resolution. More...
 
bool setSampleRate (int value)
 Set the maximum rate of mouse movements reporting. More...
 
bool setScaling (int value)
 Set the scaling. More...
 
void setupAbsolutePositioner (int width, int height, bool createAbsolutePositionsQueue, bool updateVGAController)
 Initialize absolute position handler. More...
 
MouseStatusstatus ()
 Get or set current mouse status. More...
 
void unlock ()
 Release device from exclusive access. More...
 
void updateAbsolutePosition (MouseDelta *delta)
 Update absolute position from the specified mouse delta event. More...
 
int & wheelAcceleration ()
 Get or set 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 ( )

Get 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 
)

Initialize 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);
Examples:
MouseOnScreen/MouseOnScreen.ino, and MouseStudio/MouseStudio.ino.

◆ begin() [2/2]

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

Initialize 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 ( )

Get the number of mouse movements available in the queue.

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

◆ getNextDelta()

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

Get a mouse movement from the queue.

Parameters
deltaPointer to MouseDelta structure to be filled with mouse movement.
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.

◆ getNextStatus()

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

Get 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

Identify 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

Check 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.

◆ lock()

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

Get 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

Get 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 ( )

Send 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

Set 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

Set 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.

◆ setScaling()

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

Set 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.

◆ setupAbsolutePositioner()

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

Initialize 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.

Example:

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

◆ status()

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

Get or set current mouse status.

Examples:
MouseOnScreen/MouseOnScreen.ino.

◆ unlock()

void fabgl::PS2DeviceClass::unlock ( )
inherited

Release device from exclusive access.

◆ updateAbsolutePosition()

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

Update 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);
  }
}

◆ wheelAcceleration()

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

Get or set 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: