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