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