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
35class KShapeGesturePrivate;
36//TODO: implement operator== for special situations like in KKeyChooser.
37class KDEUI_EXPORT KShapeGesture
38{
39public:
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
140private:
141 KShapeGesturePrivate * const d;
142};
143
144uint qHash(int);
145inline uint qHash(const KShapeGesture &key)
146{
147 return qHash(key.hashable());
148}
149
150class KRockerGesturePrivate;
151
152class KDEUI_EXPORT KRockerGesture
153{
154public:
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
237private:
238 KRockerGesturePrivate * const d;
239};
240
241inline uint qHash(const KRockerGesture &key)
242{
243 return qHash(key.hashable());
244}
245
246//KGESTURE_H
247#endif
248