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 kruler.h KRuler
19 *
20 * A ruler widget.
21 *
22 * The vertical ruler looks similar to this:
23 *
24 *\code
25 * meters inches
26 *
27 * ------ <--- end mark ---> ------
28 * -- -
29 * -- <---little mark---> --
30 * -- -
31 * -- ---
32 * --- <---medium mark -
33 * -- --
34 * -- tiny mark----> -
35 * -- ----
36 * -- -
37 * ---- <-----big mark --
38 * -- -
39 * |>-- <--ruler pointer--> |>--
40 *
41 * \endcode
42 *
43 * There are tiny marks, little marks, medium marks, and big marks along the
44 * ruler.
45 *
46 * To receive mouse clicks or mouse moves, the class has to be overloaded.
47 *
48 * \image html kruler.png "KRuler Widget"
49 *
50 * @short A ruler widget.
51 * @author Jörg Habenicht
52 */
53class KWIDGETSADDONS_EXPORT KRuler : public QAbstractSlider
54{
55 Q_OBJECT
56 Q_PROPERTY(bool showTinyMarks READ showTinyMarks WRITE setShowTinyMarks)
57 Q_PROPERTY(bool showLittleMarks READ showLittleMarks WRITE setShowLittleMarks)
58 Q_PROPERTY(bool showMediumMarks READ showMediumMarks WRITE setShowMediumMarks)
59 Q_PROPERTY(bool showBigMarks READ showBigMarks WRITE setShowBigMarks)
60 Q_PROPERTY(bool showPointer READ showPointer WRITE setShowPointer)
61 Q_PROPERTY(bool showEndLabel READ showEndLabel WRITE setShowEndLabel)
62 Q_PROPERTY(int tinyMarkDistance READ tinyMarkDistance WRITE setTinyMarkDistance)
63 Q_PROPERTY(int littleMarkDistance READ littleMarkDistance WRITE setLittleMarkDistance)
64 Q_PROPERTY(int mediumMarkDistance READ mediumMarkDistance WRITE setBigMarkDistance)
65 Q_PROPERTY(int bigMarkDistance READ bigMarkDistance WRITE setBigMarkDistance)
66 Q_PROPERTY(double pixelPerMark READ pixelPerMark WRITE setPixelPerMark)
67 Q_PROPERTY(bool lengthFixed READ lengthFixed WRITE setLengthFixed)
68 Q_PROPERTY(QString endLabel READ endLabel WRITE setEndLabel)
69 Q_PROPERTY(int length READ length WRITE setLength)
70 Q_PROPERTY(int offset READ offset)
71 Q_PROPERTY(int endOffset READ endOffset)
72
73public:
74 /**
75 * The types of units used.
76 */
77 enum MetricStyle { Custom = 0, Pixel, Inch, Millimetres, Centimetres, Metres };
78 Q_ENUM(MetricStyle)
79
80 /**
81 * Constructs a horizontal ruler.
82 */
83 explicit KRuler(QWidget *parent = nullptr);
84 /**
85 * Constructs a ruler with orientation @p orient.
86 *
87 * @p parent and @p f are passed to QFrame.
88 * The default look is a raised widget
89 * but may be changed with the inherited QFrame methods.
90 *
91 * @param orient Orientation of the ruler.
92 * @param parent Will be handed over to QFrame.
93 * @param f Will be handed over to QFrame.
94 *
95 */
96 explicit KRuler(Qt::Orientation orient, QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags());
97
98 /**
99 * Constructs a ruler with orientation @p orient and initial width @p widgetWidth.
100 *
101 * The width sets the fixed width of the widget. This is useful if you
102 * want to draw the ruler bigger or smaller than the default size.
103 * @note The size of the marks doesn't change.
104 * @p parent and @p f are passed to QFrame.
105 *
106 * @param orient Orientation of the ruler.
107 * @param widgetWidth Fixed width of the widget.
108 * @param parent Will be handed over to QFrame.
109 * @param f Will be handed over to QFrame.
110 *
111 */
112 KRuler(Qt::Orientation orient, int widgetWidth, QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags());
113
114 /**
115 * Destructor.
116 */
117 ~KRuler() override;
118
119 /**
120 * Sets the distance between tiny marks.
121 *
122 * This is mostly used in the English system (inches) with distance of 1.
123 */
124 void setTinyMarkDistance(int);
125 /**
126 * Returns the distance between tiny marks.
127 */
128 int tinyMarkDistance() const;
129
130 /**
131 * Sets the distance between little marks.
132 *
133 * The default value is 1 in the metric system and 2 in the English (inches) system.
134 */
135 void setLittleMarkDistance(int);
136
137 /**
138 * Returns the distance between little marks.
139 */
140 int littleMarkDistance() const;
141
142 /**
143 * Sets the distance between medium marks.
144 *
145 * For English (inches) styles it defaults to twice the little mark distance.
146 * For metric styles it defaults to five times the little mark distance.
147 */
148 void setMediumMarkDistance(int);
149 int mediumMarkDistance() const;
150
151 /**
152 * Sets distance between big marks.
153 *
154 * For English (inches) or metric styles it is twice the medium mark distance.
155 */
156 void setBigMarkDistance(int);
157 /**
158 * Returns the distance between big marks.
159 */
160 int bigMarkDistance() const;
161
162 /**
163 * Shows/hides tiny marks.
164 */
165 void setShowTinyMarks(bool);
166 bool showTinyMarks() const;
167 /**
168 * Shows/hides little marks.
169 */
170 void setShowLittleMarks(bool);
171 bool showLittleMarks() const;
172 /**
173 * Shows/hides medium marks.
174 */
175 void setShowMediumMarks(bool);
176 bool showMediumMarks() const;
177 /**
178 * Shows/hides big marks.
179 */
180 void setShowBigMarks(bool);
181 bool showBigMarks() const;
182 /**
183 * Shows/hides end marks.
184 */
185 void setShowEndMarks(bool);
186 bool showEndMarks() const;
187 /**
188 * Shows/hides the pointer.
189 */
190 void setShowPointer(bool);
191 bool showPointer() const;
192
193 /**
194 * Show/hide number values of the end marks.
195 *
196 * Default is @p false.
197 */
198 void setShowEndLabel(bool);
199 bool showEndLabel() const;
200
201 /**
202 * Sets the label this is drawn at the beginning of the visible part
203 * of the ruler to @p label
204 */
205 void setEndLabel(const QString &);
206 QString endLabel() const;
207
208 /**
209 * Sets up the necessary tasks for the provided styles.
210 *
211 * A convenience method.
212 */
213 void setRulerMetricStyle(KRuler::MetricStyle);
214
215 /**
216 * Sets the number of pixels between two base marks.
217 *
218 * Calling this method stretches or shrinks your ruler.
219 *
220 * For pixel display ( MetricStyle) the value is 10.0 marks
221 * per pixel ;-)
222 * For English (inches) it is 9.0, and for centimetres ~2.835 -> 3.0 .
223 * If you want to magnify your part of display, you have to
224 * adjust the mark distance @p here.
225 * Notice: The double type is only supported to give the possibility
226 * of having some double values.
227 * It should be used with care. Using values below 10.0
228 * shows visible jumps of markpositions (e.g. 2.345).
229 * Using whole numbers is highly recommended.
230 * To use @p int values use setPixelPerMark((int)your_int_value);
231 * default: 1 mark per 10 pixels
232 */
233 void setPixelPerMark(double rate);
234
235 /**
236 * Returns the number of pixels between two base marks.
237 */
238 double pixelPerMark() const;
239
240 /**
241 * Sets the length of the ruler, i.e. the difference between
242 * the begin mark and the end mark of the ruler.
243 *
244 * Same as (width() - offset())
245 *
246 * when the length is not locked, it gets adjusted with the
247 * length of the widget.
248 */
249 void setLength(int);
250 int length() const;
251
252 /**
253 * Locks the length of the ruler, i.e. the difference between
254 * the two end marks doesn't change when the widget is resized.
255 *
256 * @param fix fixes the length, if true
257 */
258 void setLengthFixed(bool fix);
259 bool lengthFixed() const;
260
261 /**
262 * Sets the number of pixels by which the ruler may slide up or left.
263 * The number of pixels moved is realive to the previous position.
264 * The Method makes sense for updating a ruler, which is working with
265 * a scrollbar.
266 *
267 * This doesn't affect the position of the ruler pointer.
268 * Only the visible part of the ruler is moved.
269 *
270 * @param count Number of pixel moving up or left relative to the previous position
271 */
272 void slideUp(int count = 1);
273
274 /**
275 * Sets the number of pixels by which the ruler may slide down or right.
276 * The number of pixels moved is realive to the previous position.
277 * The Method makes sense for updating a ruler, which is working with
278 * a scrollbar.
279 *
280 * This doesn't affect the position of the ruler pointer.
281 * Only the visible part of the ruler is moved.
282 *
283 * @param count Number of pixel moving up or left relative to the previous position
284 */
285 void slideDown(int count = 1);
286
287 /**
288 * Sets the ruler slide offset.
289 *
290 * This is like slideup() or slidedown() with an absolute offset
291 * from the start of the ruler.
292 *
293 * @param offset Number of pixel to move the ruler up or left from the beginning
294 */
295 void setOffset(int offset);
296
297 /**
298 * Returns the current ruler offset.
299 */
300 int offset() const;
301
302 int endOffset() const;
303
304public Q_SLOTS:
305
306 /**
307 * Sets the pointer to a new position.
308 *
309 * The offset is NOT updated.
310 * QWidget::repaint() is called afterwards.
311 */
312 void slotNewValue(int);
313
314 /**
315 * Sets the ruler marks to a new position.
316 *
317 * The pointer is NOT updated.
318 * QWidget::repaint() is called afterwards.
319 */
320 void slotNewOffset(int);
321
322 void slotEndOffset(int);
323
324protected:
325 void paintEvent(QPaintEvent *) override;
326
327private:
328 KWIDGETSADDONS_NO_EXPORT void initWidget(Qt::Orientation orientation);
329
330private:
331 std::unique_ptr<class KRulerPrivate> const d;
332};
333
334#endif
335

source code of kwidgetsaddons/src/kruler.h