Detailed Description
The QWSMouseHandler class is a base class for mouse drivers in Qtopia Core.
Note that this class is only available in Qtopia Core.
Qtopia Core provides ready-made drivers for several mouse protocols, see the pointer handling documentation for details. Custom mouse drivers can be implemented by subclassing the QWSMouseHandler class and creating a mouse driver plugin (derived from QMouseDriverPlugin). Qtopia Core's implementation of the QMouseDriverFactory class will automatically detect the plugin, and load the driver into the server application at runtime using Qt's plugin system.
The mouse driver receives mouse events from the system device and encapsulates each event with an instance of the QWSEvent class which it then passes to the server application (the server is responsible for propagating the event to the appropriate client). To receive mouse events, a QWSMouseHandler object will usually create a QSocketNotifier object for the given device. The QSocketNotifier class provides support for monitoring activity on a file descriptor. When the socket notifier receives data, it will call the mouse driver's mouseChanged() function to send the event to the Qtopia Core server application for relaying to clients.
If you are creating a driver for a device that needs calibration or noise reduction, such as a touchscreen, use the QWSCalibratedMouseHandler subclass instead to take advantage of the calibrate() and clearCalibration() functions. The Mouse Calibration example demonstrates how to write a simple program using the mechanisms provided by the QWSMouseHandler class to calibrate a mouse driver.
Note that when deriving from the QWSMouseHandler class, the resume() and suspend() functions must be reimplemented to control the flow of mouse input, i.e., the default implementation does nothing. Reimplementations of these functions typically call the QSocketNotifier::setEnabled() function to enable or disable the socket notifier, respectively.
In addition, QWSMouseHandler provides the setScreen() function that allows you to specify a screen for your mouse driver and the limitToScreen() function that ensures that a given position is within this screen's boundaries (changing the position if necessary). Finally, QWSMouseHandler provides the pos() function returning the current mouse position.
See also QMouseDriverPlugin, QMouseDriverFactory, and Qtopia Core Pointer Handling.
Member Function Documentation
QWSMouseHandler::QWSMouseHandler ( const QString & driver = QString(), const QString & device = QString() )
Constructs a mouse driver. The driver and device arguments are passed by the QWS_MOUSE_PROTO environment variable.
Call the QWSServer::setMouseHandler() function to make the newly created mouse driver, the primary driver. Note that the primary driver is controlled by the system, i.e., the system will delete it upon exit.
QWSMouseHandler::~QWSMouseHandler () [virtual]
Destroys this mouse driver.
Do not call this function if this driver is the primary mouse driver, i.e., if QWSServer::setMouseHandler() function has been called passing this driver as argument. The primary mouse driver is deleted by the system.
void QWSMouseHandler::calibrate ( const QWSPointerCalibrationData * data ) [virtual]
This virtual function allows subclasses of QWSMouseHandler to set the calibration information passed in the given data. Note that the default implementation does nothing.
See also QWSCalibratedMouseHandler::calibrate() and clearCalibration().
void QWSMouseHandler::clearCalibration () [virtual]
This virtual function allows subclasses of QWSMouseHandler to clear the calibration information. Note that the default implementation does nothing.
See also QWSCalibratedMouseHandler::clearCalibration() and calibrate().
void QWSMouseHandler::getCalibration ( QWSPointerCalibrationData * data ) const [virtual]
This virtual function allows subclasses of QWSMouseHandler to fill in the device coordinates in data with values that correspond to screen coordinates that are already in data. Note that the default implementation does nothing.
void QWSMouseHandler::limitToScreen ( QPoint & position )
Ensures that the given position is within the screen's boundaries, changing the position if necessary.
See also pos() and setScreen().
void QWSMouseHandler::mouseChanged ( const QPoint & position, int state, int wheel = 0 )
Notifies the system of a new mouse event.
This function updates the current mouse position and sends the event to the Qtopia Core server application for delivery to the correct widget. Note that a custom mouse driver must call this function whenever it wants to deliver a new mouse event.
The given position is the global position of the mouse cursor. The state parameter is a bitmask of the Qt::MouseButton enum's values, indicating which mouse buttons are pressed. The wheel parameter is the delta value of the mouse wheel as returned by QWheelEvent::delta().
See also pos().
const QPoint & QWSMouseHandler::pos () const
Returns the current mouse position.
See also mouseChanged() and limitToScreen().
void QWSMouseHandler::resume () [pure virtual]
Implement this function to resume reading and handling mouse events, e.g., call the QSocketNotifier::setEnabled() function to enable the socket notifier.
See also suspend().
void QWSMouseHandler::setScreen ( const QScreen * screen )
Sets the screen for this mouse driver to be the given screen.
This function was introduced in Qt 4.2.
See also limitToScreen().
void QWSMouseHandler::suspend () [pure virtual]
Implement this function to suspend reading and handling of mouse events, e.g., call the QSocketNotifier::setEnabled() function to disable the socket notifier.
See also resume().
