1 | /* This file is part of the KDE libraries |
2 | Copyright (C) 2006,2007 Andreas Hartmetz (ahartmetz@gmail.com) |
3 | |
4 | This library is free software; you can redistribute it and/or |
5 | modify it under the terms of the GNU Library General Public |
6 | License as published by the Free Software Foundation; either |
7 | version 2 of the License, or (at your option) any later version. |
8 | |
9 | This library is distributed in the hope that it will be useful, |
10 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | Library General Public License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to |
16 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
17 | Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef KGESTURE_H |
21 | #define KGESTURE_H |
22 | |
23 | #include <kdeui_export.h> |
24 | |
25 | #include <QtCore/QString> |
26 | #include <QtGui/QPolygon> |
27 | |
28 | /* |
29 | kinds of gestures: |
30 | -shapes like triangle, right angle, line |
31 | -"rocker" (i.e. two mouse button) gestures |
32 | */ |
33 | |
34 | |
35 | class KShapeGesturePrivate; |
36 | //TODO: implement operator== for special situations like in KKeyChooser. |
37 | class KDEUI_EXPORT KShapeGesture |
38 | { |
39 | public: |
40 | /** |
41 | * Create a new invalid shape gesture. |
42 | */ |
43 | KShapeGesture(); |
44 | |
45 | /** |
46 | * Creates a new gesture consisting of given shape. |
47 | * If the gesture belongs to a KAction, and the user draws approximately the same shape |
48 | * on the screen while holding down the right mouse button, the action will trigger. |
49 | * @p shape must be a "reasonable" polygon. It must contain at least two points |
50 | * and it should contain at most 50 for performance reasons. No two consecutive points |
51 | * are allowed to be at the same position. |
52 | * @param shape shape to draw to trigger this gesture |
53 | */ |
54 | KShapeGesture(const QPolygon &shape); |
55 | |
56 | /** |
57 | * Creates a new gesture from a string description. |
58 | * @param description create gesture according to this |
59 | */ |
60 | KShapeGesture(const QString &description); |
61 | |
62 | /** |
63 | * Copies the given gesture. |
64 | * @param other gesture to copy |
65 | */ |
66 | KShapeGesture(const KShapeGesture &other); |
67 | |
68 | /** |
69 | * Destructor. |
70 | */ |
71 | ~KShapeGesture(); |
72 | |
73 | /** |
74 | * Set the shape to draw to trigger this gesture. |
75 | */ |
76 | void setShape(const QPolygon &shape); |
77 | |
78 | /** |
79 | * set a user-visible name for this gesture's shape, like "triangle" or "line". |
80 | */ |
81 | void setShapeName(const QString &friendlyName); |
82 | |
83 | /** |
84 | * Return the user-visible name for this gesture's shape, like "triangle" or "line". |
85 | */ |
86 | QString shapeName() const; |
87 | |
88 | /** |
89 | * Return true if this gesture is valid. |
90 | * |
91 | */ |
92 | bool isValid() const; |
93 | |
94 | /** |
95 | * Return a string representation of this gesture. |
96 | * Return empty string if invalid. |
97 | * This function is mainly for use with config files. |
98 | * |
99 | * @see shapeName() |
100 | */ |
101 | QString toString() const; |
102 | |
103 | /** |
104 | * Return an idealized SVG image of this gesture. |
105 | * Return an empty image if invalid. |
106 | * @param attributes SVG attributes to apply to the SVG "path" element that |
107 | * makes up the drawing of the gesture. By default, only a 'fill="none"' |
108 | * attribute will be set. |
109 | */ |
110 | QByteArray toSvg(const QString &attributes = QString()) const; |
111 | |
112 | /** |
113 | * Return a difference measurement betwenn this gesture and the @p other |
114 | * gesture. Abort comparison if difference is larger than @p abortThreshold |
115 | * and return a very large difference in that case. |
116 | * Usual return values range from x to y //TODO: fill in x and y |
117 | */ |
118 | float distance(const KShapeGesture &other, float abortThreshold) const; |
119 | |
120 | /** |
121 | * Set this gesture to the other gesture. |
122 | */ |
123 | KShapeGesture &operator=(const KShapeGesture &other); |
124 | |
125 | /** |
126 | * Return whether this gesture is equal to the other gesture. |
127 | */ |
128 | bool operator==(const KShapeGesture &other) const; |
129 | |
130 | /** |
131 | * Return the opposite of operator==() |
132 | */ |
133 | bool operator!=(const KShapeGesture &other) const; |
134 | |
135 | /** |
136 | * Return an opaque value for use in hash tables |
137 | */ |
138 | uint hashable() const; |
139 | |
140 | private: |
141 | KShapeGesturePrivate * const d; |
142 | }; |
143 | |
144 | uint qHash(int); |
145 | inline uint qHash(const KShapeGesture &key) |
146 | { |
147 | return qHash(key.hashable()); |
148 | } |
149 | |
150 | class KRockerGesturePrivate; |
151 | |
152 | class KDEUI_EXPORT KRockerGesture |
153 | { |
154 | public: |
155 | /** |
156 | * Create a new invalid rocker gesture. |
157 | */ |
158 | KRockerGesture(); |
159 | |
160 | /** |
161 | * Creates a new gesture consisting of given buttons. |
162 | * @param description create gesture according to this |
163 | */ |
164 | KRockerGesture(enum Qt::MouseButton hold, enum Qt::MouseButton thenPush); |
165 | |
166 | /** |
167 | * Creates a new gesture from a string description. |
168 | * @param description create gesture according to this |
169 | */ |
170 | KRockerGesture(const QString &description); |
171 | |
172 | /** |
173 | * Copies the given gesture. |
174 | * @param other gesture to copy |
175 | */ |
176 | KRockerGesture(const KRockerGesture &other); |
177 | |
178 | /** |
179 | * Destructor. |
180 | */ |
181 | ~KRockerGesture(); |
182 | |
183 | /** |
184 | * set button combination to trigger |
185 | */ |
186 | void setButtons(Qt::MouseButton hold, Qt::MouseButton thenPush); |
187 | |
188 | /** |
189 | * Write the button combination to hold and thenPush |
190 | */ |
191 | void getButtons(Qt::MouseButton *hold, Qt::MouseButton *thenPush) const; |
192 | |
193 | /** |
194 | * Return a user-friendly name of the button combination. |
195 | */ |
196 | QString rockerName() const; |
197 | |
198 | /** |
199 | * Return a user-friendly name for the mouse button button |
200 | */ |
201 | static QString mouseButtonName(Qt::MouseButton button); |
202 | |
203 | /** |
204 | * Return true if this gesture is valid. |
205 | */ |
206 | bool isValid() const; |
207 | |
208 | /** |
209 | * Return a string representation of this gesture. |
210 | * Return an empty string if invalid. |
211 | * This function is mainly for use with config files. |
212 | * |
213 | * @see rockerName() |
214 | */ |
215 | QString toString() const; |
216 | |
217 | /** |
218 | * Set this gesture to the other gesture. |
219 | */ |
220 | KRockerGesture &operator=(const KRockerGesture &other); |
221 | |
222 | /** |
223 | * Return whether this gesture is equal to the other gesture. |
224 | */ |
225 | bool operator==(const KRockerGesture &other) const; |
226 | |
227 | /** |
228 | * Return the opposite of operator==() |
229 | */ |
230 | bool operator!=(const KRockerGesture &other) const; |
231 | |
232 | /** |
233 | * Return an opaque value for use in hash tables |
234 | */ |
235 | uint hashable() const; |
236 | |
237 | private: |
238 | KRockerGesturePrivate * const d; |
239 | }; |
240 | |
241 | inline uint qHash(const KRockerGesture &key) |
242 | { |
243 | return qHash(key.hashable()); |
244 | } |
245 | |
246 | //KGESTURE_H |
247 | #endif |
248 | |