Home · All Classes · Main Classes · Grouped Classes · Modules · Functions

QWSCalibratedMouseHandler Class Reference
^{[QtGui module]}

The QWSCalibratedMouseHandler class implements a mouse driver providing calibration and noise reduction. More...

#include <QWSCalibratedMouseHandler>

Inherits QWSMouseHandler.

Inherited by QWSTslibMouseHandler.

• List of all members, including inherited members

Public Functions

• virtual void calibrate ( const QWSPointerCalibrationData * data )
• virtual void clearCalibration ()

• 7 public functions inherited from QWSMouseHandler

Protected Functions

• void readCalibration ()
• bool sendFiltered ( const QPoint & position, int state )
• void setFilterSize ( int size )
• QPoint transform ( const QPoint & position )
• void writeCalibration ()

Detailed Description

The QWSCalibratedMouseHandler class implements a mouse driver providing calibration and noise reduction.

A mouse driver handles events from system devices and generates mouse events. Custom mouse drivers can be added by subclassing the QMouseDriverPlugin class, using the QMouseDriverFactory class to dynamically load the driver into the application.

Derive from the QWSCalibratedMouseHandler class when the system device does not have a fixed mapping between device and screen coordinates and/or produces noisy events, e.g. a touchscreen.

QWSCalibratedMouseHandler provides an implementation of the calibrate() function to update the calibration parameters based on coordinate mapping of the given calibration data. The calibration data is represented by an QWSCalibrationData object. The linear transformation between device coordinates and screen coordinates is performed by calling the transform() function explicitly on the points passed to the QWSMouseHandler::mouseChanged() function.

The calibration parameters are recalculated whenever calibrate() is called. They can be saved using the writeCalibration() function, and are stored in /etc/pointercal (separated by whitespace and in alphabetical order). The calibration parameters are read when the class is instantiated, but previously written parameters can be retrieved at any time using the readCalibration() function. Use the clearCalibration() function to make the mouse handler return mouse events in raw device coordinates and not in screen coordinates.

To achieve noise reduction, QWSCalibratedMouseHandler provides the sendFiltered() function. Use this function instead of mouseChanged() whenever a mouse event occurs. The filter's size can be manipulated using the setFilterSize() function.

See also QWSMouseHandler, QWSPointerCalibrationData, and Mouse Calibration Example.

Member Function Documentation

void QWSCalibratedMouseHandler::calibrate ( const QWSPointerCalibrationData * data )   [virtual]

Updates the calibration parameters based on coordinate mapping of the given data.

Create an instance of the QWSPointerCalibrationData class, fill in the device and screen coordinates and pass the object to the mouse handler using this function.

Reimplemented from QWSMouseHandler.

See also clearCalibration() and transform().

void QWSCalibratedMouseHandler::clearCalibration ()   [virtual]

Clears the current calibration, i.e. makes the mouse handler return mouse events in raw device coordinates instead of screen coordinates.

Reimplemented from QWSMouseHandler.

See also calibrate().

void QWSCalibratedMouseHandler::readCalibration ()   [protected]

Reads previously written calibration parameters which are stored in /etc/pointercal (separated by whitespace and in alphabetical order).

See also writeCalibration().

bool QWSCalibratedMouseHandler::sendFiltered ( const QPoint & position, int state )   [protected]

Notifies the system of a new mouse event after applying a noise reduction filter. Returns true if the filtering process is successful; otherwise returns false. Note that if the filtering process failes, the system is not notified about the event.

The given position is the global position of the mouse. The state parameter is a bitmask of the Qt::MouseButton enum's values indicating which mouse buttons are pressed.

The sendFiltered() function reduces noice by calculating an average position from a collection of mouse event positions, and then call the mouseChanged() function with the new position. The number of positions that is used is determined by the filter size.

See also mouseChanged() and setFilterSize().

void QWSCalibratedMouseHandler::setFilterSize ( int size )   [protected]

Sets the size of the filter used in noise reduction to the given size.

The sendFiltered() function reduces noice by calculating an average position from a collection of mouse event positions. The filter size determines the number of positions that forms the basis for the calculations.

See also sendFiltered().

QPoint QWSCalibratedMouseHandler::transform ( const QPoint & position )   [protected]

Transforms the given position from device coordinates to screen coordinates, and returns the transformed position.

Typically, the transform() function is called explicitly on the points passed to the QWSMouseHandler::mouseChanged() function.

This implementation is a linear transformation using 7 parameters (a, b, c, d, e, f and s) to transform the device coordinates (Xd, Yd) into screen coordinates (Xs, Ys) using the following equations:

    s*Xs = a*Xd + b*Yd + c
    s*Ys = d*Xd + e*Yd + f

See also mouseChanged().

void QWSCalibratedMouseHandler::writeCalibration ()   [protected]

Saves the current calibration parameters in /etc/pointercal (separated by whitespace and in alphabetical order). You can override the default /etc/pointercal by defining an environment variable POINTERCAL_FILE with a different file to use.

See also readCalibration().