The QWSCalibratedMouseHandler class provides mouse calibration and noise reduction in Qt for Embedded Linux. More...

#include <qmouse_qws.h>

Inheritance diagram for QWSCalibratedMouseHandler:

Public Functions
virtual void	calibrate (const QWSPointerCalibrationData *)
	Updates the calibration parameters based on coordinate mapping of the given data. More...

virtual void	clearCalibration ()
	Clears the current calibration, i.e., makes the mouse driver return mouse events in raw device coordinates instead of screen coordinates. More...

virtual void	getCalibration (QWSPointerCalibrationData *) const
	Fills cd with the device coordinates corresponding to the given screen coordinates. More...

	QWSCalibratedMouseHandler (const QString &driver=QString(), const QString &device=QString())

Public Functions inherited from QWSMouseHandler
void	limitToScreen (QPoint &pt)
	Ensures that the given position is within the screen's boundaries, changing the position if necessary. More...

void	mouseChanged (const QPoint &pos, int bstate, int wheel=0)
	Notifies the system of a new mouse event. More...

const QPoint &	pos () const
	Returns the current mouse position. More...

	QWSMouseHandler (const QString &driver=QString(), const QString &device=QString())
	Constructs a mouse driver. More...

virtual void	resume ()=0
	Implement this function to resume reading and handling mouse events, e. More...

void	setScreen (const QScreen *screen)
	Sets the screen for this mouse driver to be the given screen. More...

virtual void	suspend ()=0
	Implement this function to suspend reading and handling of mouse events, e. More...

virtual	~QWSMouseHandler ()
	Destroys this mouse driver. More...

Protected Functions
void	readCalibration ()
	Reads previously written calibration parameters which are stored in `/etc/pointercal` (separated by whitespace and in alphabetical order). More...

bool	sendFiltered (const QPoint &, int button)
	Notifies the system of a new mouse event after applying a noise reduction filter. More...

void	setFilterSize (int)
	Sets the size of the filter used in noise reduction to the given size. More...

QPoint	transform (const QPoint &)
	Transforms the given position from device coordinates to screen coordinates, and returns the transformed position. More...

void	writeCalibration ()
	Saves the current calibration parameters in `/etc/pointercal` (separated by whitespace and in alphabetical order). More...

Properties
int	a

int	b

int	c

int	currSample

int	d

int	e

int	f

int	numSamples

int	s

QPolygon	samples

Additional Inherited Members
Protected Variables inherited from QWSMouseHandler
QWSMouseHandlerPrivate *	d_ptr

QPoint &	mousePos

Detailed Description

The QWSCalibratedMouseHandler class provides mouse calibration and noise reduction in Qt for Embedded Linux.

Note that this class is only available in Qt for Embedded Linux.

Qt for Embedded Linux provides ready-made drivers for several mouse protocols, see the Qt for Embedded Linux Pointer Handling{pointer handling} documentation for details. In general, custom mouse drivers can be implemented by subclassing the QWSMouseHandler class. But when the system device does not have a fixed mapping between device and screen coordinates and/or produces noisy events (e.g., a touchscreen), you should derive from the QWSCalibratedMouseHandler class instead to take advantage of its calibration functionality. As always, you must also create a mouse driver plugin (derived from QMouseDriverPlugin); the implementation of the QMouseDriverFactory class will then automatically detect the plugin, and load the driver into the server application at run-time using Qt's How to Create Qt Plugins{plugin system}.

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 QWSPointerCalibrationData 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. Use the clearCalibration() function to make the mouse driver return mouse events in raw device coordinates and not in screen coordinates.

The calibration parameters are recalculated whenever calibrate() is called, and they can be stored using the writeCalibration() function. Previously written parameters can be retrieved at any time using the readCalibration() function (calibration parameters are always read when the class is instantiated). Note that the calibration parameters is written to and read from the file currently specified by the POINTERCAL_FILE environment variable; the default file is /etc/pointercal.

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, {Mouse Calibration Example}

Definition at line 92 of file qmouse_qws.h.

Constructors and Destructors

◆ QWSCalibratedMouseHandler()

QWSCalibratedMouseHandler::QWSCalibratedMouseHandler	(	const QString &	driver = `QString()`,
		const QString &	device = `QString()`
	)

explicit

Warning: This function is not part of the public interface.

Definition at line 382 of file qmouse_qws.cpp.

     : samples(5), currSample(0), numSamples(0)
 {
     clearCalibration();
     readCalibration();
 }

Functions

◆ calibrate()

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 that object to the mouse driver using this function.

See also: clearCalibration(), transform()

Reimplemented from QWSMouseHandler.

Reimplemented in QIntMouseHandler, and QWSTslibMouseHandler.

Definition at line 526 of file qmouse_qws.cpp.

Referenced by QIntMouseHandler::calibrate().

 {
     // Algorithm derived from
     // "How To Calibrate Touch Screens" by Carlos E. Vidales,
     // printed in Embedded Systems Programming, Vol. 15 no 6, June 2002
     // URL: http://www.embedded.com/showArticle.jhtml?articleID=9900629
 
     const QPoint pd0 = data->devPoints[QWSPointerCalibrationData::TopLeft];
     const QPoint pd1 = data->devPoints[QWSPointerCalibrationData::TopRight];
     const QPoint pd2 = data->devPoints[QWSPointerCalibrationData::BottomRight];
     const QPoint p0 = data->screenPoints[QWSPointerCalibrationData::TopLeft];
     const QPoint p1 = data->screenPoints[QWSPointerCalibrationData::TopRight];
     const QPoint p2 = data->screenPoints[QWSPointerCalibrationData::BottomRight];
 
     const qint64 xd0 = pd0.x();
     const qint64 xd1 = pd1.x();
     const qint64 xd2 = pd2.x();
     const qint64 yd0 = pd0.y();
     const qint64 yd1 = pd1.y();
     const qint64 yd2 = pd2.y();
     const qint64 x0 = p0.x();
     const qint64 x1 = p1.x();
     const qint64 x2 = p2.x();
     const qint64 y0 = p0.y();
     const qint64 y1 = p1.y();
     const qint64 y2 = p2.y();
 
     qint64 scale = ((xd0 - xd2)*(yd1 - yd2) - (xd1 - xd2)*(yd0 - yd2));
     int shift = 0;
     qint64 absScale = qAbs(scale);
     // use maximum 16 bit precision to reduce risk of integer overflow
     if (absScale > (1 << 16)) {
         shift = ilog2(absScale >> 16) + 1;
         scale >>= shift;
     }
 
     s = scale;
     a = ((x0 - x2)*(yd1 - yd2) - (x1 - x2)*(yd0 - yd2)) >> shift;
     b = ((xd0 - xd2)*(x1 - x2) - (x0 - x2)*(xd1 - xd2)) >> shift;
     c = (yd0*(xd2*x1 - xd1*x2) + yd1*(xd0*x2 - xd2*x0) + yd2*(xd1*x0 - xd0*x1)) >> shift;
     d = ((y0 - y2)*(yd1 - yd2) - (y1 - y2)*(yd0 - yd2)) >> shift;
     e = ((xd0 - xd2)*(y1 - y2) - (y0 - y2)*(xd1 - xd2)) >> shift;
     f = (yd0*(xd2*y1 - xd1*y2) + yd1*(xd0*y2 - xd2*y0) + yd2*(xd1*y0 - xd0*y1)) >> shift;
 
     writeCalibration();
 }

◆ clearCalibration()

void QWSCalibratedMouseHandler::clearCalibration ( )

virtual

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

See also: calibrate()

Reimplemented from QWSMouseHandler.

Reimplemented in QIntMouseHandler, and QWSTslibMouseHandler.

Definition at line 416 of file qmouse_qws.cpp.

Referenced by QIntMouseHandler::clearCalibration(), QWSCalibratedMouseHandler(), and readCalibration().

 {
     a = 1;
     b = 0;
     c = 0;
     d = 0;
     e = 1;
     f = 0;
     s = 1;
 }

◆ getCalibration()

void QWSCalibratedMouseHandler::getCalibration ( QWSPointerCalibrationData * cd ) const

virtual

Fills cd with the device coordinates corresponding to the given screen coordinates.

Warning: This function is not part of the public interface.

Reimplemented from QWSMouseHandler.

Definition at line 395 of file qmouse_qws.cpp.

 {
     const qint64 scale = qint64(a) * qint64(e) - qint64(b) * qint64(d);
     const qint64 xOff = qint64(b) * qint64(f) - qint64(c) * qint64(e);
     const qint64 yOff = qint64(c) * qint64(d) - qint64(a) * qint64(f);
     for (int i = 0; i <= QWSPointerCalibrationData::LastLocation; ++i) {
         const qint64 sX = cd->screenPoints[i].x();
         const qint64 sY = cd->screenPoints[i].y();
         const qint64 dX = (s*(e*sX - b*sY) + xOff) / scale;
         const qint64 dY = (s*(a*sY - d*sX) + yOff) / scale;
         cd->devPoints[i] = QPoint(dX, dY);
     }
 }

◆ readCalibration()

void QWSCalibratedMouseHandler::readCalibration ( )

protected

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

You can override the default /etc/pointercal by specifying another file using the POINTERCAL_FILE environment variable.

See also: writeCalibration()

Definition at line 469 of file qmouse_qws.cpp.

Referenced by QWSCalibratedMouseHandler().

 {
     QString calFile = QString::fromLocal8Bit(qgetenv("POINTERCAL_FILE"));
     if (calFile.isEmpty())
         calFile = QLatin1String("/etc/pointercal");
 
 #ifndef QT_NO_TEXTSTREAM
     QFile file(calFile);
     if (file.open(QIODevice::ReadOnly)) {
         QTextStream t(&file);
         t >> a >> b >> c >> d >> e >> f >> s;
         if (s == 0 || t.status() != QTextStream::Ok) {
             qCritical("Corrupt calibration data");
             clearCalibration();
         }
     } else
 #endif
     {
         qDebug() << "Could not read calibration:" <<calFile;
     }
 }

◆ sendFiltered()

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 noice is reduced by calculating an average position from a collection of mouse event positions and then calling the mouseChanged() function with the new position. The number of positions that is used is determined by the filter size.

See also: mouseChanged(), setFilterSize()

Definition at line 639 of file qmouse_qws.cpp.

Referenced by QIntMouseHandler::readMouseData(), and QWSTslibMouseHandlerPrivate::readMouseData().

 {
     if (!button) {
         if (numSamples >= samples.count())
             mouseChanged(transform(position), 0);
         currSample = 0;
         numSamples = 0;
         return true;
     }
 
     bool sent = false;
     samples[currSample] = position;
     numSamples++;
     if (numSamples >= samples.count()) {
 
         int ignore = -1;
         if (samples.count() > 2) { // throw away the "worst" sample
             int maxd = 0;
             for (int i = 0; i < samples.count(); i++) {
                 int d = (mousePos - samples[i]).manhattanLength();
                 if (d > maxd) {
                     maxd = d;
                     ignore = i;
                 }
             }
         }
 
         // average the rest
         QPoint pos(0, 0);
         int numAveraged = 0;
         for (int i = 0; i < samples.count(); i++) {
             if (ignore == i)
                 continue;
             pos += samples[i];
             ++numAveraged;
         }
         if (numAveraged)
             pos /= numAveraged;
 
         mouseChanged(transform(pos), button);
         sent = true;
     }
     currSample++;
     if (currSample >= samples.count())
         currSample = 0;
 
     return sent;
 }

◆ 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 these calculations.

See also: sendFiltered()

Definition at line 610 of file qmouse_qws.cpp.

 {
     samples.resize(qMax(1, size));
     numSamples = 0;
     currSample = 0;
 }

◆ transform()

QPoint QWSCalibratedMouseHandler::transform ( const QPoint & position )

protected

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

This function is typically 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()

Definition at line 589 of file qmouse_qws.cpp.

Referenced by QIntMouseHandler::QIntMouseHandler(), QWSLinuxInputMousePrivate::readMouseData(), QIntMouseHandler::readMouseData(), QWSLinuxTPMouseHandlerPrivate::readMouseData(), and sendFiltered().

 {
     QPoint tp;
 
     tp.setX((a * position.x() + b * position.y() + c) / s);
     tp.setY((d * position.x() + e * position.y() + f) / s);
 
     return tp;
 }

◆ writeCalibration()

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 specifying another file using the POINTERCAL_FILE environment variable.

See also: readCalibration()

Definition at line 437 of file qmouse_qws.cpp.

Referenced by calibrate().

 {
     QString calFile;
     calFile = QString::fromLocal8Bit(qgetenv("POINTERCAL_FILE"));
     if (calFile.isEmpty())
         calFile = QLatin1String("/etc/pointercal");
 
 #ifndef QT_NO_TEXTSTREAM
     QFile file(calFile);
     if (file.open(QIODevice::WriteOnly)) {
         QTextStream t(&file);
         t << a << ' ' << b << ' ' << c << ' ';
         t << d << ' ' << e << ' ' << f << ' ' << s << endl;
     } else
 #endif
     {
         qCritical("QWSCalibratedMouseHandler::writeCalibration: "
                   "Could not save calibration into %s", qPrintable(calFile));
     }
 }