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 | |
28 | class 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 | */ |
46 | class KDEUI_EXPORT KModifierKeyInfo : public QObject |
47 | { |
48 | Q_OBJECT |
49 | |
50 | public: |
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 | |
132 | Q_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 | |
184 | private: |
185 | Q_DISABLE_COPY(KModifierKeyInfo) |
186 | KModifierKeyInfoProvider * const p; // krazy:exclude=dpointer |
187 | }; |
188 | |
189 | #endif |
190 | |