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

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