1/*
2 SPDX-FileCopyrightText: 2014 Martin Gräßlin <mgraesslin@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5*/
6#ifndef WAYLAND_POINTER_H
7#define WAYLAND_POINTER_H
8
9#include <QObject>
10#include <QPoint>
11
12#include "KWayland/Client/kwaylandclient_export.h"
13
14struct wl_pointer;
15
16namespace KWayland
17{
18namespace Client
19{
20class Surface;
21
22/**
23 * @short Wrapper for the wl_pointer interface.
24 *
25 * This class is a convenient wrapper for the wl_pointer interface.
26 *
27 * To create an instance use Seat::createPointer.
28 *
29 * @see Seat
30 **/
31class KWAYLANDCLIENT_EXPORT Pointer : public QObject
32{
33 Q_OBJECT
34public:
35 enum class ButtonState {
36 Released,
37 Pressed,
38 };
39 enum class Axis {
40 Vertical,
41 Horizontal,
42 };
43 enum class AxisSource {
44 Wheel,
45 Finger,
46 Continuous,
47 WheelTilt,
48 };
49 explicit Pointer(QObject *parent = nullptr);
50 ~Pointer() override;
51
52 /**
53 * @returns @c true if managing a wl_pointer.
54 **/
55 bool isValid() const;
56 /**
57 * Setup this Pointer to manage the @p pointer.
58 * When using Seat::createPointer there is no need to call this
59 * method.
60 **/
61 void setup(wl_pointer *pointer);
62 /**
63 * Releases the wl_pointer interface.
64 * After the interface has been released the Pointer instance is no
65 * longer valid and can be setup with another wl_pointer interface.
66 *
67 * This method is automatically invoked when the Seat which created this
68 * Pointer gets released.
69 **/
70 void release();
71 /**
72 * Destroys the data held by this Pointer.
73 * This method is supposed to be used when the connection to the Wayland
74 * server goes away. If the connection is not valid anymore, it's not
75 * possible to call release anymore as that calls into the Wayland
76 * connection and the call would fail. This method cleans up the data, so
77 * that the instance can be deleted or set up to a new wl_pointer interface
78 * once there is a new connection available.
79 *
80 * This method is automatically invoked when the Seat which created this
81 * Pointer gets destroyed.
82 *
83 * @see release
84 **/
85 void destroy();
86
87 /**
88 * Sets the cursor image for this Pointer.
89 *
90 * This has only an effect if a Surface of the same client is focused.
91 *
92 * @param surface The Surface pointing to the image data, if @c null the cursor will be hidden
93 * @param hotspot The hotspot of the cursor image
94 * @see hideCursor
95 * @since 5.3
96 **/
97 void setCursor(Surface *surface, const QPoint &hotspot = QPoint());
98 /**
99 * Hides the cursor. Same as calling setCursor with @c null for surface.
100 * @see setCursor
101 * @since 5.3
102 **/
103 void hideCursor();
104
105 /**
106 * @returns The Surface the Pointer is on, may be @c null.
107 **/
108 Surface *enteredSurface() const;
109 /**
110 * @overload
111 **/
112 Surface *enteredSurface();
113
114 operator wl_pointer *();
115 operator wl_pointer *() const;
116
117Q_SIGNALS:
118 /**
119 * Notification that this seat's pointer is focused on a certain surface.
120 *
121 * When an seat's focus enters a surface, the pointer image is undefined
122 * and a client should respond to this event by setting an appropriate pointer
123 * image with the set_cursor request.
124 *
125 * @param serial The serial for this enter
126 * @param relativeToSurface Coordinates relative to the upper-left corner of the Surface.
127 **/
128 void entered(quint32 serial, const QPointF &relativeToSurface);
129 /**
130 * Notification that this seat's pointer is no longer focused on a certain surface.
131 *
132 * The leave notification is sent before the enter notification for the new focus.
133 *
134 * @param serial The serial of this leave event
135 **/
136 void left(quint32 serial);
137 /**
138 * Notification of pointer location change.
139 *
140 * @param relativeToSurface Coordinates relative to the upper-left corner of the entered Surface.
141 * @param time timestamp with millisecond granularity
142 **/
143 void motion(const QPointF &relativeToSurface, quint32 time);
144 /**
145 * Mouse button click and release notifications.
146 *
147 * The location of the click is given by the last motion or enter event.
148 *
149 * @param serial The serial of this button state change
150 * @param time timestamp with millisecond granularity, with an undefined base.
151 * @param button The button which got changed
152 * @param state @c Released or @c Pressed
153 **/
154 void buttonStateChanged(quint32 serial, quint32 time, quint32 button, KWayland::Client::Pointer::ButtonState state);
155 /**
156 * Scroll and other axis notifications.
157 *
158 * @param time timestamp with millisecond granularity
159 * @param axis @c Vertical or @c Horizontal
160 * @param delta
161 **/
162 void axisChanged(quint32 time, KWayland::Client::Pointer::Axis axis, qreal delta);
163 /**
164 * Indicates the source of scroll and other axes.
165 *
166 * @since 5.59
167 **/
168 void axisSourceChanged(KWayland::Client::Pointer::AxisSource source);
169 /**
170 * Discrete step information for scroll and other axes.
171 *
172 * @since 5.59
173 **/
174 void axisDiscreteChanged(KWayland::Client::Pointer::Axis axis, qint32 discreteDelta);
175 /**
176 * Stop notification for scroll and other axes.
177 *
178 * @since 5.59
179 **/
180 void axisStopped(quint32 time, KWayland::Client::Pointer::Axis axis);
181
182 /**
183 * Indicates the end of a set of events that logically belong together.
184 * A client is expected to accumulate the data in all events within the
185 * frame before proceeding.
186 * @since 5.45
187 **/
188 void frame();
189
190private:
191 class Private;
192 QScopedPointer<Private> d;
193};
194
195}
196}
197
198Q_DECLARE_METATYPE(KWayland::Client::Pointer::ButtonState)
199Q_DECLARE_METATYPE(KWayland::Client::Pointer::Axis)
200Q_DECLARE_METATYPE(KWayland::Client::Pointer::AxisSource)
201
202#endif
203

source code of kwayland/src/client/pointer.h