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_KEYBOARD_H
7 #define WAYLAND_KEYBOARD_H
8 
9 #include <QObject>
10 
11 #include <KWayland/Client/kwaylandclient_export.h>
12 
13 struct wl_keyboard;
14 
15 namespace KWayland
16 {
17 namespace Client
18 {
19 class Surface;
20 
21 /**
22  * @short Wrapper for the wl_keyboard interface.
23  *
24  * This class is a convenient wrapper for the wl_keyboard interface.
25  *
26  * To create an instance use Seat::createKeyboard.
27  *
28  * @see Seat
29  **/
30 class KWAYLANDCLIENT_EXPORT Keyboard : public QObject
31 {
32     Q_OBJECT
33 public:
34     enum class KeyState {
35         Released,
36         Pressed,
37     };
38     explicit Keyboard(QObject *parent = nullptr);
39     ~Keyboard() override;
40 
41     /**
42      * @returns @c true if managing a wl_keyboard.
43      **/
44     bool isValid() const;
45     /**
46      * Setup this Keyboard to manage the @p keyboard.
47      * When using Seat::createKeyboard there is no need to call this
48      * method.
49      **/
50     void setup(wl_keyboard *keyboard);
51     /**
52      * Releases the wl_keyboard interface.
53      * After the interface has been released the Keyboard instance is no
54      * longer valid and can be setup with another wl_keyboard interface.
55      *
56      * This method is automatically invoked when the Seat which created this
57      * Keyboard gets released.
58      **/
59     void release();
60     /**
61      * Destroys the data held by this Keyboard.
62      * This method is supposed to be used when the connection to the Wayland
63      * server goes away. If the connection is not valid anymore, it's not
64      * possible to call release anymore as that calls into the Wayland
65      * connection and the call would fail. This method cleans up the data, so
66      * that the instance can be deleted or set up to a new wl_keyboard interface
67      * once there is a new connection available.
68      *
69      * This method is automatically invoked when the Seat which created this
70      * Keyboard gets destroyed.
71      *
72      * @see release
73      **/
74     void destroy();
75 
76     /**
77      * @returns The Surface the Keyboard is on, may be @c null.
78      **/
79     Surface *enteredSurface() const;
80     /**
81      * @overload
82      **/
83     Surface *enteredSurface();
84 
85     /**
86      * @returns Whether key repeat is enabled on this keyboard
87      * @see keyRepeatRate
88      * @see keyRepeatDelay
89      * @see keyRepeatChanged
90      * @since 5.5
91      **/
92     bool isKeyRepeatEnabled() const;
93     /**
94      * @returns the key repeat rate in characters per second.
95      * @see isKeyRepeatEnabled
96      * @see keyRepeatDelay
97      * @see keyRepeatChanged
98      * @since 5.5
99      **/
100     qint32 keyRepeatRate() const;
101     /**
102      * @returns the delay in millisecond for key repeat after a press.
103      * @see isKeyRepeatEnabled
104      * @see keyRepeatRate
105      * @see keyRepeatChanged
106      * @since 5.5
107      **/
108     qint32 keyRepeatDelay() const;
109 
110     operator wl_keyboard *();
111     operator wl_keyboard *() const;
112 
113 Q_SIGNALS:
114     /**
115      * Notification that this seat's Keyboard is focused on a certain surface.
116      *
117      * @param serial The serial for this enter
118      **/
119     void entered(quint32 serial);
120     /**
121      * Notification that this seat's Keyboard is no longer focused on a certain surface.
122      *
123      * The leave notification is sent before the enter notification for the new focus.
124      *
125      * @param serial The serial of this enter
126      **/
127     void left(quint32 serial);
128     /**
129      * This signal provides a file descriptor to the client which can
130      * be memory-mapped to provide a keyboard mapping description.
131      *
132      * The signal is only emitted if the keymap format is libxkbcommon compatible.
133      *
134      * @param fd file descriptor of the keymap
135      * @param size The size of the keymap
136      **/
137     void keymapChanged(int fd, quint32 size);
138     /**
139      * A key was pressed or released.
140      * The time argument is a timestamp with millisecond granularity, with an undefined base.
141      * @param key The key which was pressed
142      * @param state Whether the key got @c Released or @c Pressed
143      * @param time The timestamp
144      **/
145     void keyChanged(quint32 key, KWayland::Client::Keyboard::KeyState state, quint32 time);
146     /**
147      * Notifies clients that the modifier and/or group state has changed,
148      * and it should update its local state.
149      **/
150     void modifiersChanged(quint32 depressed, quint32 latched, quint32 locked, quint32 group);
151     /**
152      * Emitted whenever information on key repeat changed.
153      * @see isKeyRepeatEnabled
154      * @see keyRepeatRate
155      * @see keyRepeatDelay
156      * @since 5.5
157      **/
158     void keyRepeatChanged();
159 
160 private:
161     class Private;
162     QScopedPointer<Private> d;
163 };
164 
165 }
166 }
167 
168 Q_DECLARE_METATYPE(KWayland::Client::Keyboard::KeyState)
169 
170 #endif
171