1 | /* -*- c++ -*- */ |
2 | /* This file is part of the KDE libraries |
3 | Copyright (C) 1998 Jörg Habenicht (j.habenicht@europemail.com) |
4 | |
5 | This library is free software; you can redistribute it and/or |
6 | modify it under the terms of the GNU Library General Public |
7 | License as published by the Free Software Foundation; either |
8 | version 2 of the License, or (at your option) any later version. |
9 | |
10 | This library is distributed in the hope that it will be useful, |
11 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | Library General Public License for more details. |
14 | |
15 | You should have received a copy of the GNU Library General Public License |
16 | along with this library; see the file COPYING.LIB. If not, write to |
17 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
18 | Boston, MA 02110-1301, USA. |
19 | */ |
20 | |
21 | #ifndef KRULER_H |
22 | #define KRULER_H |
23 | |
24 | #include <kdeui_export.h> |
25 | |
26 | #include <QtGui/QAbstractSlider> |
27 | |
28 | /** |
29 | * A ruler widget. |
30 | * |
31 | * The vertical ruler looks similar to this: |
32 | * |
33 | *\code |
34 | * meters inches |
35 | * |
36 | * ------ <--- end mark ---> ------ |
37 | * -- - |
38 | * -- <---little mark---> -- |
39 | * -- - |
40 | * -- --- |
41 | * --- <---medium mark - |
42 | * -- -- |
43 | * -- tiny mark----> - |
44 | * -- ---- |
45 | * -- - |
46 | * ---- <-----big mark -- |
47 | * -- - |
48 | * |>-- <--ruler pointer--> |>-- |
49 | * |
50 | * \endcode |
51 | * |
52 | * There are tiny marks, little marks, medium marks, and big marks along the |
53 | * ruler. |
54 | * |
55 | * To receive mouse clicks or mouse moves, |
56 | * the class has to be overloaded. |
57 | * |
58 | * For performance reasons, the public methods don't call QWidget::repaint(). |
59 | * (Slots do, see documentation below.) |
60 | * All the changed settings will be painted once after leaving |
61 | * to the main event loop. |
62 | * For performance painting the slot methods should be used, |
63 | * they do a fast QWidget::repaint() call after changing the values. |
64 | * For setting multiple values like minValue(), maxValue(), offset() etc. |
65 | * using the public methods is recommended |
66 | * so the widget will be painted only once when entering the main event loop. |
67 | * |
68 | * \image html kruler.png "KDE Ruler Widget" |
69 | * |
70 | * @short A ruler widget. |
71 | * @author Jörg Habenicht |
72 | */ |
73 | class KDEUI_EXPORT KRuler : public QAbstractSlider |
74 | { |
75 | Q_OBJECT |
76 | Q_PROPERTY( bool showTinyMarks READ showTinyMarks WRITE setShowTinyMarks ) |
77 | Q_PROPERTY( bool showLittleMarks READ showLittleMarks WRITE setShowLittleMarks ) |
78 | Q_PROPERTY( bool showMediumMarks READ showMediumMarks WRITE setShowMediumMarks ) |
79 | Q_PROPERTY( bool showBigMarks READ showBigMarks WRITE setShowBigMarks ) |
80 | Q_PROPERTY( bool showPointer READ showPointer WRITE setShowPointer ) |
81 | Q_PROPERTY( bool showEndLabel READ showEndLabel WRITE setShowEndLabel ) |
82 | Q_PROPERTY( int tinyMarkDistance READ tinyMarkDistance WRITE setTinyMarkDistance ) |
83 | Q_PROPERTY( int littleMarkDistance READ littleMarkDistance WRITE setLittleMarkDistance ) |
84 | Q_PROPERTY( int mediumMarkDistance READ mediumMarkDistance WRITE setBigMarkDistance ) |
85 | Q_PROPERTY( int bigMarkDistance READ bigMarkDistance WRITE setBigMarkDistance ) |
86 | Q_PROPERTY( double pixelPerMark READ pixelPerMark WRITE setPixelPerMark ) |
87 | Q_PROPERTY( bool lengthFixed READ lengthFixed WRITE setLengthFixed ) |
88 | Q_PROPERTY( QString endLabel READ endLabel WRITE setEndLabel ) |
89 | Q_ENUMS( MetricStyle ) |
90 | Q_PROPERTY( int length READ length WRITE setLength ) |
91 | Q_PROPERTY( int offset READ offset ) |
92 | Q_PROPERTY( int endOffset READ endOffset ) |
93 | |
94 | public: |
95 | |
96 | /* |
97 | #define KRULER_ROTATE_TEST KRULER_ROTATE_TEST |
98 | #undef KRULER_ROTATE_TEST |
99 | #ifdef KRULER_ROTATE_TEST |
100 | double xtrans, ytrans, rotate; |
101 | # warning tmporaer variablen eingeschaltet |
102 | #endif |
103 | */ |
104 | |
105 | /** |
106 | * The types of units used. |
107 | **/ |
108 | enum MetricStyle { Custom=0, Pixel, Inch, Millimetres, Centimetres, Metres }; |
109 | |
110 | /** |
111 | * The style (or look) of the ruler. |
112 | **/ |
113 | // enum PaintStyle { Flat, Raised, Sunken }; |
114 | |
115 | /** |
116 | * Constructs a horizontal ruler. |
117 | */ |
118 | explicit KRuler(QWidget *parent=0); |
119 | /** |
120 | * Constructs a ruler with orientation @p orient. |
121 | * |
122 | * @p parent and @p f are passed to QFrame. |
123 | * The default look is a raised widget |
124 | * but may be changed with the inherited QFrame methods. |
125 | * |
126 | * @param orient Orientation of the ruler. |
127 | * @param parent Will be handed over to QFrame. |
128 | * @param f Will be handed over to QFrame. |
129 | * |
130 | **/ |
131 | explicit KRuler(Qt::Orientation orient, QWidget *parent=0, Qt::WindowFlags f=0); |
132 | |
133 | /** |
134 | * Constructs a ruler with orientation @p orient and initial width @p widgetWidth. |
135 | * |
136 | * The width sets the fixed width of the widget. This is useful if you |
137 | * want to draw the ruler bigger or smaller than the default size. |
138 | * Note: The size of the marks doesn't change. |
139 | * @p parent and @p f are passed to QFrame. |
140 | * |
141 | * @param orient Orientation of the ruler. |
142 | * @param widgetWidth Fixed width of the widget. |
143 | * @param parent Will be handed over to QFrame. |
144 | * @param f Will be handed over to QFrame. |
145 | * |
146 | */ |
147 | KRuler(Qt::Orientation orient, int widgetWidth, QWidget *parent=0, |
148 | Qt::WindowFlags f=0); |
149 | |
150 | /** |
151 | * Destructor. |
152 | */ |
153 | ~KRuler(); |
154 | |
155 | /** |
156 | * Sets the minimal value of the ruler pointer (default is 0). |
157 | * |
158 | * This method calls update() so that the widget is painted after leaving |
159 | * to the main event loop. |
160 | * |
161 | **/ |
162 | #ifndef KDE_NO_DEPRECATED |
163 | KDE_DEPRECATED void setMinValue(int); |
164 | #endif |
165 | |
166 | /** |
167 | * Returns the minimal value of the ruler pointer. |
168 | **/ |
169 | #ifndef KDE_NO_DEPRECATED |
170 | KDE_DEPRECATED int minValue() const; |
171 | #endif |
172 | |
173 | /** |
174 | * Sets the maximum value of the ruler pointer (default is 100). |
175 | * |
176 | * This method calls update() so that the widget is painted after leaving |
177 | * to the main event loop. |
178 | */ |
179 | #ifndef KDE_NO_DEPRECATED |
180 | KDE_DEPRECATED void setMaxValue(int); |
181 | #endif |
182 | |
183 | /** |
184 | * Returns the maximal value of the ruler pointer. |
185 | */ |
186 | #ifndef KDE_NO_DEPRECATED |
187 | KDE_DEPRECATED int maxValue() const; |
188 | #endif |
189 | |
190 | |
191 | /** |
192 | * Sets the distance between tiny marks. |
193 | * |
194 | * This is mostly used in the English system (inches) with distance of 1. |
195 | */ |
196 | void setTinyMarkDistance(int); |
197 | /** |
198 | * Returns the distance between tiny marks. |
199 | **/ |
200 | int tinyMarkDistance() const; |
201 | |
202 | /** |
203 | * Sets the distance between little marks. |
204 | * |
205 | * The default value is 1 in the metric system and 2 in the English (inches) system. |
206 | */ |
207 | void setLittleMarkDistance(int); |
208 | |
209 | /** |
210 | * Returns the distance between little marks. |
211 | */ |
212 | int littleMarkDistance() const; |
213 | |
214 | /** |
215 | * Sets the distance between medium marks. |
216 | * |
217 | * For English (inches) styles it defaults to twice the little mark distance. |
218 | * For metric styles it defaults to five times the little mark distance. |
219 | **/ |
220 | void setMediumMarkDistance(int); |
221 | int mediumMarkDistance() const; |
222 | |
223 | /** |
224 | * Sets distance between big marks. |
225 | * |
226 | * For English (inches) or metric styles it is twice the medium mark distance. |
227 | **/ |
228 | void setBigMarkDistance(int); |
229 | /** |
230 | * Returns the distance between big marks. |
231 | **/ |
232 | int bigMarkDistance() const; |
233 | |
234 | /** |
235 | * Shows/hides tiny marks. |
236 | **/ |
237 | void setShowTinyMarks(bool); |
238 | bool showTinyMarks() const; |
239 | /** |
240 | * Shows/hides little marks. |
241 | **/ |
242 | void setShowLittleMarks(bool); |
243 | bool showLittleMarks() const; |
244 | /** |
245 | * Shows/hides medium marks. |
246 | **/ |
247 | void setShowMediumMarks(bool); |
248 | bool showMediumMarks() const; |
249 | /** |
250 | * Shows/hides big marks. |
251 | **/ |
252 | void setShowBigMarks(bool); |
253 | bool showBigMarks() const; |
254 | /** |
255 | * Shows/hides end marks. |
256 | **/ |
257 | void setShowEndMarks(bool); |
258 | bool showEndMarks() const; |
259 | /** |
260 | * Shows/hides the pointer. |
261 | */ |
262 | void setShowPointer(bool); |
263 | bool showPointer() const; |
264 | |
265 | |
266 | void setFrameStyle(int); |
267 | |
268 | /** |
269 | * Show/hide number values of the little marks. |
270 | * |
271 | * Default is @p false. |
272 | **/ |
273 | // void setShowLittleMarkLabel(bool); |
274 | |
275 | /** |
276 | * Show/hide number values of the medium marks. |
277 | * |
278 | * Default is @p false. |
279 | **/ |
280 | // void setShowMediumMarkLabel(bool); |
281 | |
282 | /** |
283 | * Show/hide number values of the big marks. |
284 | * |
285 | * Default is @p false. |
286 | **/ |
287 | // void showBigMarkLabel(bool); |
288 | |
289 | /** |
290 | * Show/hide number values of the end marks. |
291 | * |
292 | * Default is @p false. |
293 | **/ |
294 | void setShowEndLabel(bool); |
295 | bool showEndLabel() const; |
296 | |
297 | /** |
298 | * Sets the label this is drawn at the beginning of the visible part |
299 | * of the ruler to @p label |
300 | **/ |
301 | void setEndLabel(const QString&); |
302 | QString endLabel() const; |
303 | |
304 | /** |
305 | * Sets up the necessary tasks for the provided styles. |
306 | * |
307 | * A convenience method. |
308 | **/ |
309 | void setRulerMetricStyle(KRuler::MetricStyle); |
310 | |
311 | /** |
312 | * Sets the number of pixels between two base marks. |
313 | * |
314 | * Calling this method stretches or shrinks your ruler. |
315 | * |
316 | * For pixel display ( MetricStyle) the value is 10.0 marks |
317 | * per pixel ;-) |
318 | * For English (inches) it is 9.0, and for centimetres ~2.835 -> 3.0 . |
319 | * If you want to magnify your part of display, you have to |
320 | * adjust the mark distance @p here. |
321 | * Notice: The double type is only supported to give the possibility |
322 | * of having some double values. |
323 | * It should be used with care. Using values below 10.0 |
324 | * shows visible jumps of markpositions (e.g. 2.345). |
325 | * Using whole numbers is highly recommended. |
326 | * To use @p int values use setPixelPerMark((int)your_int_value); |
327 | * default: 1 mark per 10 pixels |
328 | */ |
329 | void setPixelPerMark(double rate); |
330 | |
331 | /** |
332 | * Returns the number of pixels between two base marks. |
333 | **/ |
334 | double pixelPerMark() const; |
335 | |
336 | /** |
337 | * Sets the length of the ruler, i.e. the difference between |
338 | * the begin mark and the end mark of the ruler. |
339 | * |
340 | * Same as (width() - offset()) |
341 | * |
342 | * when the length is not locked, it gets adjusted with the |
343 | * length of the widget. |
344 | */ |
345 | void setLength(int); |
346 | int length() const; |
347 | |
348 | /** |
349 | * Locks the length of the ruler, i.e. the difference between |
350 | * the two end marks doesn't change when the widget is resized. |
351 | * |
352 | * @param fix fixes the length, if true |
353 | */ |
354 | void setLengthFixed(bool fix); |
355 | bool lengthFixed() const; |
356 | |
357 | /** |
358 | * Sets the number of pixels by which the ruler may slide up or left. |
359 | * The number of pixels moved is realive to the previous position. |
360 | * The Method makes sense for updating a ruler, which is working with |
361 | * a scrollbar. |
362 | * |
363 | * This doesn't affect the position of the ruler pointer. |
364 | * Only the visible part of the ruler is moved. |
365 | * |
366 | * @param count Number of pixel moving up or left relative to the previous position |
367 | **/ |
368 | void slideUp(int count = 1); |
369 | |
370 | /** |
371 | * Sets the number of pixels by which the ruler may slide down or right. |
372 | * The number of pixels moved is realive to the previous position. |
373 | * The Method makes sense for updating a ruler, which is working with |
374 | * a scrollbar. |
375 | * |
376 | * This doesn't affect the position of the ruler pointer. |
377 | * Only the visible part of the ruler is moved. |
378 | * |
379 | * @param count Number of pixel moving up or left relative to the previous position |
380 | **/ |
381 | void slideDown(int count = 1); |
382 | |
383 | /** |
384 | * Sets the ruler slide offset. |
385 | * |
386 | * This is like slideup() or slidedown() with an absolute offset |
387 | * from the start of the ruler. |
388 | * |
389 | * @param offset Number of pixel to move the ruler up or left from the beginning |
390 | **/ |
391 | void setOffset(int offset); |
392 | |
393 | /** |
394 | * Returns the current ruler offset. |
395 | **/ |
396 | int offset() const; |
397 | |
398 | int endOffset() const; |
399 | |
400 | public Q_SLOTS: |
401 | |
402 | /** |
403 | * Sets the pointer to a new position. |
404 | * |
405 | * The offset is NOT updated. |
406 | * QWidget::repaint() is called afterwards. |
407 | **/ |
408 | void slotNewValue(int); |
409 | |
410 | /** |
411 | * Sets the ruler marks to a new position. |
412 | * |
413 | * The pointer is NOT updated. |
414 | * QWidget::repaint() is called afterwards. |
415 | **/ |
416 | void slotNewOffset(int); |
417 | |
418 | void slotEndOffset(int); |
419 | |
420 | protected: |
421 | virtual void paintEvent(QPaintEvent *); |
422 | |
423 | private: |
424 | void init(Qt::Orientation orientation); |
425 | |
426 | private: |
427 | class KRulerPrivate; |
428 | KRulerPrivate * const d; |
429 | }; |
430 | |
431 | #endif |
432 | |