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 */
73class 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
94public:
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
400public 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
420protected:
421 virtual void paintEvent(QPaintEvent *);
422
423private:
424 void init(Qt::Orientation orientation);
425
426private:
427 class KRulerPrivate;
428 KRulerPrivate * const d;
429};
430
431#endif
432