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
15class 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 */
38class KGUIADDONS_EXPORT KModifierKeyInfo : public QObject
39{
40 Q_OBJECT
41
42public:
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
139Q_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
195private:
196 Q_DISABLE_COPY(KModifierKeyInfo)
197 QExplicitlySharedDataPointer<KModifierKeyInfoProvider> const p; // krazy:exclude=dpointer
198};
199
200#endif
201

source code of kguiaddons/src/util/kmodifierkeyinfo.h