FabGL
ESP32 Display Controller and Graphics Library
fabgl::Mouse Class Reference

The PS2 Mouse controller class. More...

#include <mouse.h>

Inheritance diagram for fabgl::Mouse:
Collaboration diagram for fabgl::Mouse:

Public Member Functions

int availableStatus ()
 Gets the number of available mouse status. More...
 
void begin (gpio_num_t clkGPIO, gpio_num_t dataGPIO)
 Initializes Mouse specifying CLOCK and DATA GPIOs. More...
 
void begin (int PS2Port)
 Initializes Mouse 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...
 
PS2DeviceType 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, DisplayController *updateDisplayController=nullptr, uiApp *app=nullptr)
 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.

Mouse class connects to one port of the PS2 Controller class (fabgl::PS2Controller) to decode and get mouse movements.
At the moment Mouse class 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).
Mouse class 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.

Because fabgl::PS2Controller 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
fabgl::Mouse Mouse;
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::Mouse::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 Mouse.setupAbsolutePositioner() is true.

Returns
Number of available mouse status.

◆ begin() [1/2]

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

Initializes Mouse specifying CLOCK and DATA GPIOs.

A reset command (Mouse.reset() method) is automatically sent to the mouse.
This method also initializes the PS2Controller 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:
Others/MouseStudio/MouseStudio.ino.

◆ begin() [2/2]

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

Initializes Mouse without initializing the PS/2 controller.

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

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::Mouse::deltaAvailable ( )

Determines the number of mouse movements available in the queue.

Returns
The number of mouse movements (deltas) available to read.

◆ getNextDelta()

bool fabgl::Mouse::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);

◆ getNextStatus()

MouseStatus fabgl::Mouse::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 Mouse.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:
VGA/MouseOnScreen/MouseOnScreen.ino.

◆ identify()

PS2DeviceType fabgl::PS2Device::identify ( )
inlineinherited

Identifies the device attached to the PS2 port.

Returns
The identification ID sent by keyboard.

◆ isMouseAvailable()

bool fabgl::Mouse::isMouseAvailable ( )
inline

Checks if mouse has been detected and correctly initialized.

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

Returns
True if the mouse is correctly initialized.

◆ lock()

bool fabgl::PS2Device::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::Mouse::movementAcceleration ( )
inline

Gets or set mouse movement acceleration factor.

Mouse movement acceleration is calculated in Mouse.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::Mouse::reset ( )

Sends a Reset command to the mouse.

Returns
True if the mouse is correctly initialized.

◆ setResolution()

bool fabgl::Mouse::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.

◆ setSampleRate()

bool fabgl::Mouse::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:
VGA/SpaceInvaders/SpaceInvaders.ino.

◆ setScaling()

bool fabgl::Mouse::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.

◆ setUIApp()

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

Sets current UI app.

Parameters
appThe UI app where to send mouse events

◆ setupAbsolutePositioner()

void fabgl::Mouse::setupAbsolutePositioner ( int  width,
int  height,
bool  createAbsolutePositionsQueue,
DisplayController updateDisplayController = nullptr,
uiApp app = nullptr 
)

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.
updateDisplayControllerIf specified (not nullptr) display controller mouse pointer is automatically updated.
appOptional fabgl::uiApp where to send mouse events.

Example:

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

◆ status()

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

Gets or sets current mouse status.

Examples:
VGA/MouseOnScreen/MouseOnScreen.ino.

◆ terminateAbsolutePositioner()

void fabgl::Mouse::terminateAbsolutePositioner ( )

Terminates absolute position handler.

◆ unlock()

void fabgl::PS2Device::unlock ( )
inherited

Releases device from exclusive access.

◆ updateAbsolutePosition()

void fabgl::Mouse::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 updateDisplayController or createAbsolutePositionsQueue parameters of Mouse.setupAbsolutePositioner() is set.

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::Mouse::wheelAcceleration ( )
inline

Gets or sets wheel acceleration factor.

Wheel acceleration is calculated in Mouse.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: