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

source code of kwidgetsaddons/src/kruler.h