1 /********************************************************************
2 Copyright 2014  Martin Gräßlin <mgraesslin@kde.org>
3 
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) version 3, or any
8 later version accepted by the membership of KDE e.V. (or its
9 successor approved by the membership of KDE e.V.), which shall
10 act as a proxy defined in Section 6 of version 3 of the license.
11 
12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15 Lesser General Public License for more details.
16 
17 You should have received a copy of the GNU Lesser General Public
18 License along with this library.  If not, see <http://www.gnu.org/licenses/>.
19 *********************************************************************/
20 #ifndef WAYLAND_POINTER_H
21 #define WAYLAND_POINTER_H
22 
23 #include <QObject>
24 #include <QPoint>
25 // STD
26 #include <Wrapland/Client/wraplandclient_export.h>
27 #include <memory>
28 
29 struct wl_pointer;
30 
31 namespace Wrapland
32 {
33 namespace Client
34 {
35 
36 class Surface;
37 
38 /**
39  * @short Wrapper for the wl_pointer interface.
40  *
41  * This class is a convenient wrapper for the wl_pointer interface.
42  *
43  * To create an instance use Seat::createPointer.
44  *
45  * @see Seat
46  **/
47 class WRAPLANDCLIENT_EXPORT Pointer : public QObject
48 {
49     Q_OBJECT
50 public:
51     enum class ButtonState {
52         Released,
53         Pressed,
54     };
55     enum class Axis {
56         Vertical,
57         Horizontal,
58     };
59     enum class AxisSource {
60         Wheel,
61         Finger,
62         Continuous,
63         WheelTilt,
64     };
65     explicit Pointer(QObject* parent = nullptr);
66     virtual ~Pointer();
67 
68     /**
69      * @returns @c true if managing a wl_pointer.
70      **/
71     bool isValid() const;
72     /**
73      * Setup this Pointer to manage the @p pointer.
74      * When using Seat::createPointer there is no need to call this
75      * method.
76      **/
77     void setup(wl_pointer* pointer);
78     /**
79      * Releases the wl_pointer interface.
80      * After the interface has been released the Pointer instance is no
81      * longer valid and can be setup with another wl_pointer interface.
82      *
83      * This method is automatically invoked when the Seat which created this
84      * Pointer gets released.
85      **/
86     void release();
87 
88     /**
89      * Sets the cursor image for this Pointer.
90      *
91      * This has only an effect if a Surface of the same client is focused.
92      *
93      * @param surface The Surface pointing to the image data, if @c null the cursor will be hidden
94      * @param hotspot The hotspot of the cursor image
95      * @see hideCursor
96      * @since 5.3
97      **/
98     void setCursor(Surface* surface, const QPoint& hotspot = QPoint());
99     /**
100      * Hides the cursor. Same as calling setCursor with @c null for surface.
101      * @see setCursor
102      * @since 5.3
103      **/
104     void hideCursor();
105 
106     /**
107      * @returns The Surface the Pointer is on, may be @c null.
108      **/
109     Surface* enteredSurface() const;
110     /**
111      * @overload
112      **/
113     Surface* enteredSurface();
114 
115     operator wl_pointer*();
116     operator wl_pointer*() const;
117 
118 Q_SIGNALS:
119     /**
120      * Notification that this seat's pointer is focused on a certain surface.
121      *
122      * When an seat's focus enters a surface, the pointer image is undefined
123      * and a client should respond to this event by setting an appropriate pointer
124      * image with the set_cursor request.
125      *
126      * @param serial The serial for this enter
127      * @param relativeToSurface Coordinates relative to the upper-left corner of the Surface.
128      **/
129     void entered(quint32 serial, const QPointF& relativeToSurface);
130     /**
131      * Notification that this seat's pointer is no longer focused on a certain surface.
132      *
133      * The leave notification is sent before the enter notification for the new focus.
134      *
135      * @param serial The serial of this leave event
136      **/
137     void left(quint32 serial);
138     /**
139      * Notification of pointer location change.
140      *
141      * @param relativeToSurface  Coordinates relative to the upper-left corner of the entered
142      * Surface.
143      * @param time timestamp with millisecond granularity
144      **/
145     void motion(const QPointF& relativeToSurface, quint32 time);
146     /**
147      * Mouse button click and release notifications.
148      *
149      * The location of the click is given by the last motion or enter event.
150      *
151      * @param serial The serial of this button state change
152      * @param time timestamp with millisecond granularity, with an undefined base.
153      * @param button The button which got changed
154      * @param state @c Released or @c Pressed
155      **/
156     void buttonStateChanged(quint32 serial,
157                             quint32 time,
158                             quint32 button,
159                             Wrapland::Client::Pointer::ButtonState state);
160     /**
161      * Scroll and other axis notifications.
162      *
163      * @param time timestamp with millisecond granularity
164      * @param axis @c Vertical or @c Horizontal
165      * @param delta
166      **/
167     void axisChanged(quint32 time, Wrapland::Client::Pointer::Axis axis, qreal delta);
168     /**
169      * Indicates the source of scroll and other axes.
170      *
171      * @since 0.0.559
172      **/
173     void axisSourceChanged(Wrapland::Client::Pointer::AxisSource source);
174     /**
175      * Discrete step information for scroll and other axes.
176      *
177      * @since 0.0.559
178      **/
179     void axisDiscreteChanged(Wrapland::Client::Pointer::Axis axis, qint32 discreteDelta);
180     /**
181      * Stop notification for scroll and other axes.
182      *
183      * @since 0.0.559
184      **/
185     void axisStopped(quint32 time, Wrapland::Client::Pointer::Axis axis);
186 
187     /**
188      * Indicates the end of a set of events that logically belong together.
189      * A client is expected to accumulate the data in all events within the
190      * frame before proceeding.
191      * @since 0.0.545
192      **/
193     void frame();
194 
195 private:
196     class Private;
197     std::unique_ptr<Private> d;
198 };
199 
200 }
201 }
202 
203 Q_DECLARE_METATYPE(Wrapland::Client::Pointer::ButtonState)
204 Q_DECLARE_METATYPE(Wrapland::Client::Pointer::Axis)
205 Q_DECLARE_METATYPE(Wrapland::Client::Pointer::AxisSource)
206 
207 #endif
208