From 178a1548f3ae87c8fdde1bf5d0e71ed4e4252253 Mon Sep 17 00:00:00 2001 From: Shawn Rutledge Date: Mon, 23 Jun 2014 14:50:47 +0200 Subject: QTabletEvent documentation improvements Recent patches have added new functionality, and other aspects of the documentation have been outdated for some time. Task-number: QTBUG-39458 Change-Id: Ib7013eee091ff443971485133a58785d9284bc3d Reviewed-by: Jerome Pasion --- src/gui/kernel/qevent.cpp | 93 +++++++++++++++++++++++++++++------------------ 1 file changed, 58 insertions(+), 35 deletions(-) (limited to 'src/gui') diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp index fc05720a39..6dfccec834 100644 --- a/src/gui/kernel/qevent.cpp +++ b/src/gui/kernel/qevent.cpp @@ -1189,7 +1189,7 @@ Qt::FocusReason QFocusEvent::reason() const The event contains a region() that needs to be updated, and a rect() that is the bounding rectangle of that region. Both are - provided because many widgets can't make much use of region(), + provided because many widgets cannot make much use of region(), and rect() can be much faster than region().boundingRect(). \section1 Automatic Clipping @@ -1981,40 +1981,63 @@ QVariant QInputMethodQueryEvent::value(Qt::InputMethodQuery query) const \ingroup events - Tablet Events are generated from a Wacom tablet. Most of the time you will - want to deal with events from the tablet as if they were events from a - mouse; for example, you would retrieve the cursor position with x(), y(), - pos(), globalX(), globalY(), and globalPos(). In some situations you may - wish to retrieve the extra information provided by the tablet device - driver; for example, you might want to do subpixeling with higher - resolution coordinates or you may want to adjust color brightness based on - pressure. QTabletEvent allows you to read the pressure(), the xTilt(), and - yTilt(), as well as the type of device being used with device() (see - \l{TabletDevice}). It can also give you the minimum and maximum values for - each device's pressure and high resolution coordinates. - - A tablet event contains a special accept flag that indicates whether the - receiver wants the event. You should call QTabletEvent::accept() if you - handle the tablet event; otherwise it will be sent to the parent widget. - The exception are TabletEnterProximity and TabletLeaveProximity events, - these are only sent to QApplication and don't check whether or not they are - accepted. - - The QWidget::setEnabled() function can be used to enable or - disable mouse and keyboard events for a widget. - - The event handler QWidget::tabletEvent() receives all three types of - tablet events. Qt will first send a tabletEvent then, if it is not - accepted, it will send a mouse event. This allows applications that - don't utilize tablets to use a tablet like a mouse, while also - enabling those who want to use both tablets and mouses differently. + \e{Tablet events} are generated from tablet peripherals such as Wacom + tablets and various other brands, and electromagnetic stylus devices + included with some types of tablet computers. (It is not the same as + \l QTouchEvent which a touchscreen generates, even when a passive stylus is + used on a touchscreen.) + + Tablet events are similar to mouse events; for example, the \l x(), \l y(), + \l pos(), \l globalX(), \l globalY(), and \l globalPos() accessors provide + the cursor position, and you can see which \l buttons() are pressed + (pressing the stylus tip against the tablet surface is equivalent to a left + mouse button). But tablet events also pass through some extra information + that the tablet device driver provides; for example, you might want to do + subpixel rendering with higher resolution coordinates (\l hiResGlobalX() + and \l hiResGlobalY()), adjust color brightness based on the \l pressure() + of the tool against the tablet surface, use different brushes depending on + the type of tool in use (\l device()), modulate the brush shape in some way + according to the X-axis and Y-axis tilt of the tool with respect to the + tablet surface (\l xTilt() and \l yTilt()), and use a virtual eraser + instead of a brush if the user switches to the other end of a double-ended + stylus (\l pointerType()). + + Every event contains an accept flag that indicates whether the receiver + wants the event. You should call QTabletEvent::accept() if you handle the + tablet event; otherwise it will be sent to the parent widget. The exception + are TabletEnterProximity and TabletLeaveProximity events: these are only + sent to QApplication and do not check whether or not they are accepted. + + The QWidget::setEnabled() function can be used to enable or disable + mouse, tablet and keyboard events for a widget. + + The event handler QWidget::tabletEvent() receives TabletPress, + TabletRelease and TabletMove events. Qt will first send a + tablet event, then if it is not accepted by any widget, it will send a + mouse event. This allows users of applications that are not designed for + tablets to use a tablet like a mouse. However high-resolution drawing + applications should handle the tablet events, because they can occur at a + higher frequency, which is a benefit for smooth and accurate drawing. + If the tablet events are rejected, the synthetic mouse events may be + compressed for efficiency. + + New in Qt 5.4: QTabletEvent includes all information available from the + device, including \l QTabletEvent::buttons(). Previously it was not + possible to accept all tablet events and also know which stylus buttons + were pressed. + + Note that pressing the stylus button while the stylus hovers over the + tablet will generate a button press on some types of tablets, while on + other types it will be necessary to press the stylus against the tablet + surface in order to register the simultaneous stylus button press. \section1 Notes for X11 Users - Qt uses the following hard-coded names to identify tablet - devices from the xorg.conf file on X11 (apart from IRIX): - 'stylus', 'pen', and 'eraser'. If the devices have other names, - they will not be picked up Qt. + If the tablet is configured in xorg.conf to use the Wacom driver, there + will be separate XInput "devices" for the stylus, eraser, and (optionally) + cursor and touchpad. Qt recognizes these by their names. Otherwise, if the + tablet is configured to use the evdev driver, there will be only one device + and applications may not be able to distinguish the stylus from the eraser. */ /*! @@ -2226,7 +2249,7 @@ Qt::MouseButtons QTabletEvent::buttons() const \fn qreal QTabletEvent::rotation() const Returns the rotation of the current device in degress. This is usually - given by a 4D Mouse. If the device doesn't support rotation this value is + given by a 4D Mouse. If the device does not support rotation this value is always 0.0. */ @@ -3130,7 +3153,7 @@ QActionEvent::~QActionEvent() If spontaneous() is true, the event originated outside the application. In this case, the user hid the window using the window manager controls, either by iconifying the window or by - switching to another virtual desktop where the window isn't + switching to another virtual desktop where the window is not visible. The window will become hidden but not withdrawn. If the window was iconified, QWidget::isMinimized() returns \c true. @@ -3696,7 +3719,7 @@ QDebug operator<<(QDebug dbg, const QEvent *e) { \ingroup events \inmodule QtGui - Normally you don't need to use this class directly; QShortcut + Normally you do not need to use this class directly; QShortcut provides a higher-level interface to handle shortcut keys. \sa QShortcut -- cgit v1.2.3