QInputDevice Class
The QInputDevice class describes a device from which a QInputEvent originates. More...
| Header: | #include <QInputDevice> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Since: | Qt 6.0 |
| Inherits: | QObject |
| Inherited By: |
Public Types
| flags | Capabilities |
| enum class | Capability { None, Position, Area, Pressure, Velocity, …, All } |
| enum class | DeviceType { Unknown, Mouse, TouchScreen, TouchPad, Stylus, …, AllDevices } |
| flags | DeviceTypes |
Public Functions
| QInputDevice(QObject *parent = nullptr) | |
| QInputDevice(const QString &name, qint64 id, QInputDevice::DeviceType type, const QString &seatName = QString(), QObject *parent = nullptr) | |
| QRect | availableVirtualGeometry() const |
| QInputDevice::Capabilities | capabilities() const |
| bool | hasCapability(QInputDevice::Capability capability) const |
| QString | name() const |
| QString | seatName() const |
| qint64 | systemId() const |
| QInputDevice::DeviceType | type() const |
Signals
| void | availableVirtualGeometryChanged(QRect area) |
Static Public Members
| QList<const QInputDevice *> | devices() |
| const QInputDevice * | primaryKeyboard(const QString &seatName = QString()) |
| QStringList | seatNames() |
Detailed Description
Each QInputEvent contains a QInputDevice pointer to allow accessing device-specific properties like type, capabilities and seat. It is the responsibility of the platform or generic plug-ins to discover, create and register an instance of this class corresponding to each available input device, via QWindowSystemInterface::registerInputDevice(), before generating any input event referring to that device.
Applications do not need to instantiate this class, but can read the instances pointed to by QInputEvent::device() and QInputDevice::devices().
Member Type Documentation
enum class QInputDevice::Capability
flags QInputDevice::Capabilities
Indicates what kind of information the input device or its driver can provide.
| Constant | Value | Description |
|---|---|---|
QInputDevice::Capability::None | 0 | No information about input device capabilities available. |
QInputDevice::Capability::Position | 0x0001 | Indicates that position information is available, meaning that the position() family of functions in the touch points return valid points. |
QInputDevice::Capability::Area | 0x0002 | Indicates that touch area information is available, meaning that QEventPoint::ellipseDiameters() in the touch points return valid values. |
QInputDevice::Capability::Pressure | 0x0004 | Indicates that pressure information is available, meaning that QEventPoint::pressure() returns a valid value. |
QInputDevice::Capability::Velocity | 0x0008 | Indicates that velocity information is available, meaning that QEventPoint::velocity() returns a valid vector. |
QInputDevice::Capability::NormalizedPosition | 0x0020 | Indicates that the normalized position is available, meaning that QEventPoint::globalPosition() returns a valid value. |
QInputDevice::Capability::MouseEmulation | 0x0040 | Indicates that the device synthesizes mouse events. |
QInputDevice::Capability::Scroll | 0x0100 | Indicates that the device has a scroll capability. |
QInputDevice::Capability::PixelScroll (since Qt 6.2) | 0x0080 | Indicates that the device (usually a touchpad) scrolls with pixel precision. |
QInputDevice::Capability::Hover | 0x0200 | Indicates that the device has a hover capability. |
QInputDevice::Capability::Rotation | 0x0400 | Indicates that rotation information is available. |
QInputDevice::Capability::XTilt | 0x0800 | Indicates that tilt information is available for the X-axis. |
QInputDevice::Capability::YTilt | 0x1000 | Indicates that tilt information is available for the Y-axis. |
QInputDevice::Capability::TangentialPressure | 0x2000 | Indicates that tangential pressure information is available. |
QInputDevice::Capability::ZPosition | 0x4000 | Indicates that position information for the Z-axis is available. |
QInputDevice::Capability::All | 0x7FFFFFFF |
The Capabilities type is a typedef for QFlags<Capability>. It stores an OR combination of Capability values.
enum class QInputDevice::DeviceType
flags QInputDevice::DeviceTypes
This enum represents the type of device that generated a QPointerEvent.
| Constant | Value | Description |
|---|---|---|
QInputDevice::DeviceType::Unknown | 0x0000 | The device cannot be identified. |
QInputDevice::DeviceType::Mouse | 0x0001 | A mouse. |
QInputDevice::DeviceType::TouchScreen | 0x0002 | In this type of device, the touch surface and display are integrated. This means the surface and display typically have the same size, such that there is a direct relationship between the touch points' physical positions and the coordinate reported by QEventPoint. As a result, Qt allows the user to interact directly with multiple QWidgets, QGraphicsItems, or Qt Quick Items at the same time. |
QInputDevice::DeviceType::TouchPad | 0x0004 | In this type of device, the touch surface is separate from the display. There is not a direct relationship between the physical touch location and the on-screen coordinates. Instead, they are calculated relative to the current mouse position, and the user must use the touch-pad to move this reference point. Unlike touch-screens, Qt allows users to only interact with a single QWidget or QGraphicsItem at a time. |
QInputDevice::DeviceType::Stylus | 0x0010 | A pen-like device used on a graphics tablet such as a Wacom tablet, or on a touchscreen that provides a separate stylus sensing capability. |
QInputDevice::DeviceType::Airbrush | 0x0020 | A stylus with a thumbwheel to adjust tangentialPressure. |
QInputDevice::DeviceType::Puck | 0x0008 | A device that is similar to a flat mouse with a transparent circle with cross-hairs. |
QInputDevice::DeviceType::Keyboard | 0x1000 | A keyboard. |
QInputDevice::DeviceType::AllDevices | 0x7FFFFFFF | Any of the above (used as a default filter value). |
The DeviceTypes type is a typedef for QFlags<DeviceType>. It stores an OR combination of DeviceType values.
Member Function Documentation
QInputDevice::QInputDevice(QObject *parent = nullptr)
Creates a new invalid input device instance as a child of parent.
QInputDevice::QInputDevice(const QString &name, qint64 id, QInputDevice::DeviceType type, const QString &seatName = QString(), QObject *parent = nullptr)
Creates a new input device instance. The given name is normally a manufacturer-assigned model name if available, or something else identifiable; id is a platform-specific number that will be unique per device (for example the xinput ID on X11); type identifies what kind of device. On window systems that are capable of handling input from multiple users or sets of input devices at the same time (such as Wayland or X11), seatName identifies the name of the set of devices that will be used together. If the device is a child or slave device (for example one of several mice that can take turns moving the "core pointer"), the master device should be given as the parent.
The platform plugin creates, registers and continues to own each device instance; usually parent should be given for memory management purposes even if there is no master for a particular device.
By default, capabilities() are None.
QRect QInputDevice::availableVirtualGeometry() const
Returns the region within the virtual desktop that this device can access.
For example a TouchScreen input device is fixed in place upon a single physical screen, and usually calibrated so that this area is the same as QScreen::geometry(); whereas a Mouse can probably access all screens on the virtual desktop. A Wacom graphics tablet may be configured in a way that it's mapped to all screens, or only to the screen where the user prefers to create drawings, or to the window in which drawing occurs. A Stylus device that is integrated with a touchscreen may be physically limited to that screen.
If the returned rectangle is null, it means this device can access the entire virtual desktop.
Note: Getter function for property availableVirtualGeometry.
QInputDevice::Capabilities QInputDevice::capabilities() const
Returns the device capabilities.
Note: Getter function for property capabilities.
[static] QList<const QInputDevice *> QInputDevice::devices()
Returns a list of all registered input devices (keyboards and pointing devices).
Note: The list of devices is not always complete on all platforms. So far, the most-complete information is available on the X11 platform, at startup and in response to hot-plugging. Most other platforms are only able to provide generic devices of various types, only after receiving events from them; and most platforms do not tell Qt when a device is plugged in, or when it is unplugged at runtime.
Note: The returned list cannot be used to add new devices. To add a simulated touch screen for an autotest, QTest::createTouchDevice() can be used. Platform plugins should call QWindowSystemInterface::registerInputDevice() to add devices as they are discovered.
bool QInputDevice::hasCapability(QInputDevice::Capability capability) const
Returns whether the device capabilities include the given capability.
QString QInputDevice::name() const
Returns the device name.
This string may be empty. It is however useful on systems that have multiple input devices: it can be used to differentiate from which device a QPointerEvent originates.
Note: Getter function for property name.
[static] const QInputDevice *QInputDevice::primaryKeyboard(const QString &seatName = QString())
Returns the core or master keyboard on the given seat seatName.
QString QInputDevice::seatName() const
Returns the seat with which the device is associated, if known; otherwise empty.
Devices that are intended to be used together by one user may be configured to have the same seat name. That is only possible on Wayland and X11 platforms so far.
Note: Getter function for property seatName.
[static, since 6.3] QStringList QInputDevice::seatNames()
Returns a list of seat names for all registered input devices (keyboards and pointing devices).
This function was introduced in Qt 6.3.
qint64 QInputDevice::systemId() const
Returns the platform specific system ID (for example xinput ID on the X11 platform).
All platforms are expected to provide a unique system ID for each device.
Note: Getter function for property systemId.
QInputDevice::DeviceType QInputDevice::type() const
Returns the device type.
Note: Getter function for property type.
© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.