1 | /* |
2 | SPDX-FileCopyrightText: 2009 Michael Leupold <lemma@confuego.org> |
3 | |
4 | SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL |
5 | */ |
6 | |
7 | #ifndef KMODIFIERKEYINFO_H |
8 | #define KMODIFIERKEYINFO_H |
9 | |
10 | #include <kguiaddons_export.h> |
11 | |
12 | #include <QExplicitlySharedDataPointer> |
13 | #include <QObject> |
14 | |
15 | class KModifierKeyInfoProvider; |
16 | |
17 | /*! |
18 | * \class KModifierKeyInfo |
19 | * \inmodule KGuiAddons |
20 | * |
21 | * \brief Get information about the state of the keyboard's modifier keys. |
22 | * |
23 | * This class provides cross-platform information about the state of the |
24 | * keyboard's modifier keys and the mouse buttons and allows to change the |
25 | * state as well. |
26 | * |
27 | * It recognizes two states a key can be in: |
28 | * \list |
29 | * \li locked: eg. caps-locked (a.k.a. toggled) |
30 | * \li latched the key is temporarily locked but will be unlocked upon |
31 | * the next keypress. |
32 | * \endlist |
33 | * |
34 | * An application can either query the states synchronously (isKeyLatched(), |
35 | * isKeyLocked()) or connect to KModifierKeyInfo's signals to be notified about |
36 | * changes (keyLatched(), keyLocked()). |
37 | */ |
38 | class KGUIADDONS_EXPORT KModifierKeyInfo : public QObject |
39 | { |
40 | Q_OBJECT |
41 | |
42 | public: |
43 | /*! |
44 | * Default constructor |
45 | */ |
46 | explicit KModifierKeyInfo(QObject *parent = nullptr); |
47 | |
48 | ~KModifierKeyInfo() override; |
49 | |
50 | /*! |
51 | * Check if a key is known by the underlying window system and can be queried. |
52 | * |
53 | * \a key The key to check |
54 | * |
55 | * Returns \c true if the key is available, \c false if it is unknown |
56 | */ |
57 | bool knowsKey(Qt::Key key) const; |
58 | |
59 | /*! |
60 | * Get a list of known keys. |
61 | * |
62 | * Returns list of known keys of which states will be reported. |
63 | */ |
64 | const QList<Qt::Key> knownKeys() const; |
65 | |
66 | /*! |
67 | * Synchronously check if a key is pressed. |
68 | * |
69 | * \a key The key to check |
70 | * |
71 | * Returns \c true if the key is pressed, \c false if the key is not pressed or unknown. |
72 | * |
73 | * \sa isKeyLatched |
74 | * \sa isKeyLocked |
75 | * \sa keyPressed |
76 | */ |
77 | bool isKeyPressed(Qt::Key key) const; |
78 | |
79 | /*! |
80 | * Synchronously check if a key is latched. |
81 | * |
82 | * \a key The key to check |
83 | * |
84 | * Returns \c true if the key is latched, \c false if the key is not latched or unknown. |
85 | * |
86 | * \sa isKeyPressed |
87 | * \sa isKeyLocked |
88 | * \sa keyLatched |
89 | */ |
90 | bool isKeyLatched(Qt::Key key) const; |
91 | |
92 | /*! |
93 | * Set the latched state of a key. |
94 | * |
95 | * \a key The key to latch |
96 | * |
97 | * \a latched true to latch the key, false to unlatch it. |
98 | * |
99 | * Returns \c false if the key is unknown. \c true doesn't guarantee you the |
100 | * operation worked. |
101 | */ |
102 | bool setKeyLatched(Qt::Key key, bool latched); |
103 | |
104 | /*! |
105 | * Synchronously check if a key is locked. |
106 | * |
107 | * \a key The key to check |
108 | * |
109 | * Returns \c true if the key is locked, \c false if the key is not locked or unknown. |
110 | * |
111 | * \sa isKeyPressed |
112 | * \sa isKeyLatched |
113 | * \sa keyLocked |
114 | */ |
115 | bool isKeyLocked(Qt::Key key) const; |
116 | |
117 | /*! |
118 | * Set the locked state of a key. |
119 | * |
120 | * \a key The key to lock |
121 | * |
122 | * \a locked true to lock the key, false to unlock it. |
123 | * |
124 | * Return \c false if the key is unknown. \c true doesn't guarantee you the |
125 | * operation worked. |
126 | */ |
127 | bool setKeyLocked(Qt::Key key, bool locked); |
128 | |
129 | /*! |
130 | * Synchronously check if a mouse button is pressed. |
131 | * |
132 | * \a button The mouse button to check |
133 | * |
134 | * Returns \c true if the mouse button is pressed, \c false if the mouse button |
135 | * is not pressed or its state is unknown. |
136 | */ |
137 | bool isButtonPressed(Qt::MouseButton button) const; |
138 | |
139 | Q_SIGNALS: |
140 | /*! |
141 | * This signal is emitted whenever the pressed state of a key changes |
142 | * (key press or key release). |
143 | * |
144 | * \a key The key that changed state |
145 | * |
146 | * \a pressed \c true if the key is now pressed, \c false if is released. |
147 | */ |
148 | void keyPressed(Qt::Key key, bool pressed); |
149 | |
150 | /*! |
151 | * This signal is emitted whenever the latched state of a key changes. |
152 | * |
153 | * \a key The key that changed state |
154 | * |
155 | * \a latched \c true if the key is now latched, \c false if it isn't |
156 | */ |
157 | void keyLatched(Qt::Key key, bool latched); |
158 | |
159 | /*! |
160 | * This signal is emitted whenever the locked state of a key changes. |
161 | * |
162 | * \a key The key that changed state |
163 | * |
164 | * \a locked \c true if the key is now locked, \c false if it isn't |
165 | */ |
166 | void keyLocked(Qt::Key key, bool locked); |
167 | |
168 | /*! |
169 | * This signal is emitted whenever the pressed state of a mouse button |
170 | * changes (mouse button press or release). |
171 | * |
172 | * \a button The mouse button that changed state |
173 | * |
174 | * \a pressed \c true if the mouse button is now pressed, \c false if |
175 | * is released. |
176 | */ |
177 | void buttonPressed(Qt::MouseButton button, bool pressed); |
178 | |
179 | /*! |
180 | * This signal is emitted whenever a new modifier is found due to |
181 | * the keyboard mapping changing. |
182 | * |
183 | * \a key The key that was discovered |
184 | */ |
185 | void keyAdded(Qt::Key key); |
186 | |
187 | /*! |
188 | * This signal is emitted whenever a previously known modifier no |
189 | * longer exists due to the keyboard mapping changing. |
190 | * |
191 | * \a key The key that vanished |
192 | */ |
193 | void keyRemoved(Qt::Key key); |
194 | |
195 | private: |
196 | Q_DISABLE_COPY(KModifierKeyInfo) |
197 | QExplicitlySharedDataPointer<KModifierKeyInfoProvider> const p; // krazy:exclude=dpointer |
198 | }; |
199 | |
200 | #endif |
201 | |