KWidgetsAddons

kruler.h
1 /* -*- c++ -*- */
2 /*
3  This file is part of the KDE libraries
4  SPDX-FileCopyrightText: 1998 Jörg Habenicht <[email protected]>
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  */
53 class 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 
73 public:
74  /**
75  * The types of units used.
76  */
77  enum MetricStyle { Custom = 0, Pixel, Inch, Millimetres, Centimetres, Metres };
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,
114 
115  /**
116  * Destructor.
117  */
118  ~KRuler();
119 
120 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0)
121  /**
122  * Sets the minimal value of the ruler pointer (default is 0).
123  *
124  * This method calls update() so that the widget is painted after leaving
125  * to the main event loop.
126  *
127  * @deprecated Since 5.0, use setMinimum(int).
128  */
129  KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KRuler::setMinimum(int)")
130  void setMinValue(int);
131 #endif
132 
133 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0)
134  /**
135  * Returns the minimal value of the ruler pointer.
136  *
137  * @deprecated Since 5.0, use minimum().
138  */
139  KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KRuler::minimum()")
140  int minValue() const;
141 #endif
142 
143 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0)
144  /**
145  * Sets the maximum value of the ruler pointer (default is 100).
146  *
147  * This method calls update() so that the widget is painted after leaving
148  * to the main event loop.
149  *
150  * @deprecated Since 5.0, use setMaximum().
151  */
152  KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KRuler::setMaximum(int)")
153  void setMaxValue(int);
154 #endif
155 
156 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0)
157  /**
158  * Returns the maximal value of the ruler pointer.
159  *
160  * @deprecated Since 5.0, use maximum().
161  */
162  KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KRuler::maximum()")
163  int maxValue() const;
164 #endif
165 
166  /**
167  * Sets the distance between tiny marks.
168  *
169  * This is mostly used in the English system (inches) with distance of 1.
170  */
171  void setTinyMarkDistance(int);
172  /**
173  * Returns the distance between tiny marks.
174  */
175  int tinyMarkDistance() const;
176 
177  /**
178  * Sets the distance between little marks.
179  *
180  * The default value is 1 in the metric system and 2 in the English (inches) system.
181  */
182  void setLittleMarkDistance(int);
183 
184  /**
185  * Returns the distance between little marks.
186  */
187  int littleMarkDistance() const;
188 
189  /**
190  * Sets the distance between medium marks.
191  *
192  * For English (inches) styles it defaults to twice the little mark distance.
193  * For metric styles it defaults to five times the little mark distance.
194  */
195  void setMediumMarkDistance(int);
196  int mediumMarkDistance() const;
197 
198  /**
199  * Sets distance between big marks.
200  *
201  * For English (inches) or metric styles it is twice the medium mark distance.
202  */
203  void setBigMarkDistance(int);
204  /**
205  * Returns the distance between big marks.
206  */
207  int bigMarkDistance() const;
208 
209  /**
210  * Shows/hides tiny marks.
211  */
212  void setShowTinyMarks(bool);
213  bool showTinyMarks() const;
214  /**
215  * Shows/hides little marks.
216  */
217  void setShowLittleMarks(bool);
218  bool showLittleMarks() const;
219  /**
220  * Shows/hides medium marks.
221  */
222  void setShowMediumMarks(bool);
223  bool showMediumMarks() const;
224  /**
225  * Shows/hides big marks.
226  */
227  void setShowBigMarks(bool);
228  bool showBigMarks() const;
229  /**
230  * Shows/hides end marks.
231  */
232  void setShowEndMarks(bool);
233  bool showEndMarks() const;
234  /**
235  * Shows/hides the pointer.
236  */
237  void setShowPointer(bool);
238  bool showPointer() const;
239 
240 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0)
241  /**
242  * Is a no-op.
243  * @deprecated Since 5.0.
244  */
245  KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "No longer a feature")
246  void setFrameStyle(int);
247 #endif
248 
249  /**
250  * Show/hide number values of the end marks.
251  *
252  * Default is @p false.
253  */
254  void setShowEndLabel(bool);
255  bool showEndLabel() const;
256 
257  /**
258  * Sets the label this is drawn at the beginning of the visible part
259  * of the ruler to @p label
260  */
261  void setEndLabel(const QString &);
262  QString endLabel() const;
263 
264  /**
265  * Sets up the necessary tasks for the provided styles.
266  *
267  * A convenience method.
268  */
269  void setRulerMetricStyle(KRuler::MetricStyle);
270 
271  /**
272  * Sets the number of pixels between two base marks.
273  *
274  * Calling this method stretches or shrinks your ruler.
275  *
276  * For pixel display ( MetricStyle) the value is 10.0 marks
277  * per pixel ;-)
278  * For English (inches) it is 9.0, and for centimetres ~2.835 -> 3.0 .
279  * If you want to magnify your part of display, you have to
280  * adjust the mark distance @p here.
281  * Notice: The double type is only supported to give the possibility
282  * of having some double values.
283  * It should be used with care. Using values below 10.0
284  * shows visible jumps of markpositions (e.g. 2.345).
285  * Using whole numbers is highly recommended.
286  * To use @p int values use setPixelPerMark((int)your_int_value);
287  * default: 1 mark per 10 pixels
288  */
289  void setPixelPerMark(double rate);
290 
291  /**
292  * Returns the number of pixels between two base marks.
293  */
294  double pixelPerMark() const;
295 
296  /**
297  * Sets the length of the ruler, i.e. the difference between
298  * the begin mark and the end mark of the ruler.
299  *
300  * Same as (width() - offset())
301  *
302  * when the length is not locked, it gets adjusted with the
303  * length of the widget.
304  */
305  void setLength(int);
306  int length() const;
307 
308  /**
309  * Locks the length of the ruler, i.e. the difference between
310  * the two end marks doesn't change when the widget is resized.
311  *
312  * @param fix fixes the length, if true
313  */
314  void setLengthFixed(bool fix);
315  bool lengthFixed() const;
316 
317  /**
318  * Sets the number of pixels by which the ruler may slide up or left.
319  * The number of pixels moved is realive to the previous position.
320  * The Method makes sense for updating a ruler, which is working with
321  * a scrollbar.
322  *
323  * This doesn't affect the position of the ruler pointer.
324  * Only the visible part of the ruler is moved.
325  *
326  * @param count Number of pixel moving up or left relative to the previous position
327  */
328  void slideUp(int count = 1);
329 
330  /**
331  * Sets the number of pixels by which the ruler may slide down or right.
332  * The number of pixels moved is realive to the previous position.
333  * The Method makes sense for updating a ruler, which is working with
334  * a scrollbar.
335  *
336  * This doesn't affect the position of the ruler pointer.
337  * Only the visible part of the ruler is moved.
338  *
339  * @param count Number of pixel moving up or left relative to the previous position
340  */
341  void slideDown(int count = 1);
342 
343  /**
344  * Sets the ruler slide offset.
345  *
346  * This is like slideup() or slidedown() with an absolute offset
347  * from the start of the ruler.
348  *
349  * @param offset Number of pixel to move the ruler up or left from the beginning
350  */
351  void setOffset(int offset);
352 
353  /**
354  * Returns the current ruler offset.
355  */
356  int offset() const;
357 
358  int endOffset() const;
359 
360 public Q_SLOTS:
361 
362  /**
363  * Sets the pointer to a new position.
364  *
365  * The offset is NOT updated.
366  * QWidget::repaint() is called afterwards.
367  */
368  void slotNewValue(int);
369 
370  /**
371  * Sets the ruler marks to a new position.
372  *
373  * The pointer is NOT updated.
374  * QWidget::repaint() is called afterwards.
375  */
376  void slotNewOffset(int);
377 
378  void slotEndOffset(int);
379 
380 protected:
381  void paintEvent(QPaintEvent *) override;
382 
383 private:
384  void initWidget(Qt::Orientation orientation);
385 
386 private:
387  std::unique_ptr<class KRulerPrivate> const d;
388 };
389 
390 #endif
Q_ENUM(...)
virtual void paintEvent(QPaintEvent *event)
A ruler widget.
Definition: kruler.h:53
Q_PROPERTY(...)
Orientation
typedef WindowFlags
MetricStyle
The types of units used.
Definition: kruler.h:77
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Mar 8 2021 22:44:10 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.