File indexing completed on 2025-02-16 13:11:50
0001 /* -*- c++ -*- */ 0002 /* 0003 This file is part of the KDE libraries 0004 SPDX-FileCopyrightText: 1998 Jörg Habenicht <j.habenicht@europemail.com> 0005 0006 SPDX-License-Identifier: LGPL-2.0-or-later 0007 */ 0008 0009 #ifndef KRULER_H 0010 #define KRULER_H 0011 0012 #include <kwidgetsaddons_export.h> 0013 0014 #include <QAbstractSlider> 0015 #include <memory> 0016 0017 /** 0018 * @class KRuler kruler.h KRuler 0019 * 0020 * A ruler widget. 0021 * 0022 * The vertical ruler looks similar to this: 0023 * 0024 *\code 0025 * meters inches 0026 * 0027 * ------ <--- end mark ---> ------ 0028 * -- - 0029 * -- <---little mark---> -- 0030 * -- - 0031 * -- --- 0032 * --- <---medium mark - 0033 * -- -- 0034 * -- tiny mark----> - 0035 * -- ---- 0036 * -- - 0037 * ---- <-----big mark -- 0038 * -- - 0039 * |>-- <--ruler pointer--> |>-- 0040 * 0041 * \endcode 0042 * 0043 * There are tiny marks, little marks, medium marks, and big marks along the 0044 * ruler. 0045 * 0046 * To receive mouse clicks or mouse moves, the class has to be overloaded. 0047 * 0048 * \image html kruler.png "KRuler Widget" 0049 * 0050 * @short A ruler widget. 0051 * @author Jörg Habenicht 0052 */ 0053 class KWIDGETSADDONS_EXPORT KRuler : public QAbstractSlider 0054 { 0055 Q_OBJECT 0056 Q_PROPERTY(bool showTinyMarks READ showTinyMarks WRITE setShowTinyMarks) 0057 Q_PROPERTY(bool showLittleMarks READ showLittleMarks WRITE setShowLittleMarks) 0058 Q_PROPERTY(bool showMediumMarks READ showMediumMarks WRITE setShowMediumMarks) 0059 Q_PROPERTY(bool showBigMarks READ showBigMarks WRITE setShowBigMarks) 0060 Q_PROPERTY(bool showPointer READ showPointer WRITE setShowPointer) 0061 Q_PROPERTY(bool showEndLabel READ showEndLabel WRITE setShowEndLabel) 0062 Q_PROPERTY(int tinyMarkDistance READ tinyMarkDistance WRITE setTinyMarkDistance) 0063 Q_PROPERTY(int littleMarkDistance READ littleMarkDistance WRITE setLittleMarkDistance) 0064 Q_PROPERTY(int mediumMarkDistance READ mediumMarkDistance WRITE setBigMarkDistance) 0065 Q_PROPERTY(int bigMarkDistance READ bigMarkDistance WRITE setBigMarkDistance) 0066 Q_PROPERTY(double pixelPerMark READ pixelPerMark WRITE setPixelPerMark) 0067 Q_PROPERTY(bool lengthFixed READ lengthFixed WRITE setLengthFixed) 0068 Q_PROPERTY(QString endLabel READ endLabel WRITE setEndLabel) 0069 Q_PROPERTY(int length READ length WRITE setLength) 0070 Q_PROPERTY(int offset READ offset) 0071 Q_PROPERTY(int endOffset READ endOffset) 0072 0073 public: 0074 /** 0075 * The types of units used. 0076 */ 0077 enum MetricStyle { Custom = 0, Pixel, Inch, Millimetres, Centimetres, Metres }; 0078 Q_ENUM(MetricStyle) 0079 0080 /** 0081 * Constructs a horizontal ruler. 0082 */ 0083 explicit KRuler(QWidget *parent = nullptr); 0084 /** 0085 * Constructs a ruler with orientation @p orient. 0086 * 0087 * @p parent and @p f are passed to QFrame. 0088 * The default look is a raised widget 0089 * but may be changed with the inherited QFrame methods. 0090 * 0091 * @param orient Orientation of the ruler. 0092 * @param parent Will be handed over to QFrame. 0093 * @param f Will be handed over to QFrame. 0094 * 0095 */ 0096 explicit KRuler(Qt::Orientation orient, QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags()); 0097 0098 /** 0099 * Constructs a ruler with orientation @p orient and initial width @p widgetWidth. 0100 * 0101 * The width sets the fixed width of the widget. This is useful if you 0102 * want to draw the ruler bigger or smaller than the default size. 0103 * @note The size of the marks doesn't change. 0104 * @p parent and @p f are passed to QFrame. 0105 * 0106 * @param orient Orientation of the ruler. 0107 * @param widgetWidth Fixed width of the widget. 0108 * @param parent Will be handed over to QFrame. 0109 * @param f Will be handed over to QFrame. 0110 * 0111 */ 0112 KRuler(Qt::Orientation orient, int widgetWidth, QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags()); 0113 0114 /** 0115 * Destructor. 0116 */ 0117 ~KRuler() override; 0118 0119 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0) 0120 /** 0121 * Sets the minimal value of the ruler pointer (default is 0). 0122 * 0123 * This method calls update() so that the widget is painted after leaving 0124 * to the main event loop. 0125 * 0126 * @deprecated Since 5.0, use setMinimum(int). 0127 */ 0128 KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KRuler::setMinimum(int)") 0129 void setMinValue(int); 0130 #endif 0131 0132 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0) 0133 /** 0134 * Returns the minimal value of the ruler pointer. 0135 * 0136 * @deprecated Since 5.0, use minimum(). 0137 */ 0138 KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KRuler::minimum()") 0139 int minValue() const; 0140 #endif 0141 0142 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0) 0143 /** 0144 * Sets the maximum value of the ruler pointer (default is 100). 0145 * 0146 * This method calls update() so that the widget is painted after leaving 0147 * to the main event loop. 0148 * 0149 * @deprecated Since 5.0, use setMaximum(). 0150 */ 0151 KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KRuler::setMaximum(int)") 0152 void setMaxValue(int); 0153 #endif 0154 0155 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0) 0156 /** 0157 * Returns the maximal value of the ruler pointer. 0158 * 0159 * @deprecated Since 5.0, use maximum(). 0160 */ 0161 KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KRuler::maximum()") 0162 int maxValue() const; 0163 #endif 0164 0165 /** 0166 * Sets the distance between tiny marks. 0167 * 0168 * This is mostly used in the English system (inches) with distance of 1. 0169 */ 0170 void setTinyMarkDistance(int); 0171 /** 0172 * Returns the distance between tiny marks. 0173 */ 0174 int tinyMarkDistance() const; 0175 0176 /** 0177 * Sets the distance between little marks. 0178 * 0179 * The default value is 1 in the metric system and 2 in the English (inches) system. 0180 */ 0181 void setLittleMarkDistance(int); 0182 0183 /** 0184 * Returns the distance between little marks. 0185 */ 0186 int littleMarkDistance() const; 0187 0188 /** 0189 * Sets the distance between medium marks. 0190 * 0191 * For English (inches) styles it defaults to twice the little mark distance. 0192 * For metric styles it defaults to five times the little mark distance. 0193 */ 0194 void setMediumMarkDistance(int); 0195 int mediumMarkDistance() const; 0196 0197 /** 0198 * Sets distance between big marks. 0199 * 0200 * For English (inches) or metric styles it is twice the medium mark distance. 0201 */ 0202 void setBigMarkDistance(int); 0203 /** 0204 * Returns the distance between big marks. 0205 */ 0206 int bigMarkDistance() const; 0207 0208 /** 0209 * Shows/hides tiny marks. 0210 */ 0211 void setShowTinyMarks(bool); 0212 bool showTinyMarks() const; 0213 /** 0214 * Shows/hides little marks. 0215 */ 0216 void setShowLittleMarks(bool); 0217 bool showLittleMarks() const; 0218 /** 0219 * Shows/hides medium marks. 0220 */ 0221 void setShowMediumMarks(bool); 0222 bool showMediumMarks() const; 0223 /** 0224 * Shows/hides big marks. 0225 */ 0226 void setShowBigMarks(bool); 0227 bool showBigMarks() const; 0228 /** 0229 * Shows/hides end marks. 0230 */ 0231 void setShowEndMarks(bool); 0232 bool showEndMarks() const; 0233 /** 0234 * Shows/hides the pointer. 0235 */ 0236 void setShowPointer(bool); 0237 bool showPointer() const; 0238 0239 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0) 0240 /** 0241 * Is a no-op. 0242 * @deprecated Since 5.0. 0243 */ 0244 KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "No longer a feature") 0245 void setFrameStyle(int); 0246 #endif 0247 0248 /** 0249 * Show/hide number values of the end marks. 0250 * 0251 * Default is @p false. 0252 */ 0253 void setShowEndLabel(bool); 0254 bool showEndLabel() const; 0255 0256 /** 0257 * Sets the label this is drawn at the beginning of the visible part 0258 * of the ruler to @p label 0259 */ 0260 void setEndLabel(const QString &); 0261 QString endLabel() const; 0262 0263 /** 0264 * Sets up the necessary tasks for the provided styles. 0265 * 0266 * A convenience method. 0267 */ 0268 void setRulerMetricStyle(KRuler::MetricStyle); 0269 0270 /** 0271 * Sets the number of pixels between two base marks. 0272 * 0273 * Calling this method stretches or shrinks your ruler. 0274 * 0275 * For pixel display ( MetricStyle) the value is 10.0 marks 0276 * per pixel ;-) 0277 * For English (inches) it is 9.0, and for centimetres ~2.835 -> 3.0 . 0278 * If you want to magnify your part of display, you have to 0279 * adjust the mark distance @p here. 0280 * Notice: The double type is only supported to give the possibility 0281 * of having some double values. 0282 * It should be used with care. Using values below 10.0 0283 * shows visible jumps of markpositions (e.g. 2.345). 0284 * Using whole numbers is highly recommended. 0285 * To use @p int values use setPixelPerMark((int)your_int_value); 0286 * default: 1 mark per 10 pixels 0287 */ 0288 void setPixelPerMark(double rate); 0289 0290 /** 0291 * Returns the number of pixels between two base marks. 0292 */ 0293 double pixelPerMark() const; 0294 0295 /** 0296 * Sets the length of the ruler, i.e. the difference between 0297 * the begin mark and the end mark of the ruler. 0298 * 0299 * Same as (width() - offset()) 0300 * 0301 * when the length is not locked, it gets adjusted with the 0302 * length of the widget. 0303 */ 0304 void setLength(int); 0305 int length() const; 0306 0307 /** 0308 * Locks the length of the ruler, i.e. the difference between 0309 * the two end marks doesn't change when the widget is resized. 0310 * 0311 * @param fix fixes the length, if true 0312 */ 0313 void setLengthFixed(bool fix); 0314 bool lengthFixed() const; 0315 0316 /** 0317 * Sets the number of pixels by which the ruler may slide up or left. 0318 * The number of pixels moved is realive to the previous position. 0319 * The Method makes sense for updating a ruler, which is working with 0320 * a scrollbar. 0321 * 0322 * This doesn't affect the position of the ruler pointer. 0323 * Only the visible part of the ruler is moved. 0324 * 0325 * @param count Number of pixel moving up or left relative to the previous position 0326 */ 0327 void slideUp(int count = 1); 0328 0329 /** 0330 * Sets the number of pixels by which the ruler may slide down or right. 0331 * The number of pixels moved is realive to the previous position. 0332 * The Method makes sense for updating a ruler, which is working with 0333 * a scrollbar. 0334 * 0335 * This doesn't affect the position of the ruler pointer. 0336 * Only the visible part of the ruler is moved. 0337 * 0338 * @param count Number of pixel moving up or left relative to the previous position 0339 */ 0340 void slideDown(int count = 1); 0341 0342 /** 0343 * Sets the ruler slide offset. 0344 * 0345 * This is like slideup() or slidedown() with an absolute offset 0346 * from the start of the ruler. 0347 * 0348 * @param offset Number of pixel to move the ruler up or left from the beginning 0349 */ 0350 void setOffset(int offset); 0351 0352 /** 0353 * Returns the current ruler offset. 0354 */ 0355 int offset() const; 0356 0357 int endOffset() const; 0358 0359 public Q_SLOTS: 0360 0361 /** 0362 * Sets the pointer to a new position. 0363 * 0364 * The offset is NOT updated. 0365 * QWidget::repaint() is called afterwards. 0366 */ 0367 void slotNewValue(int); 0368 0369 /** 0370 * Sets the ruler marks to a new position. 0371 * 0372 * The pointer is NOT updated. 0373 * QWidget::repaint() is called afterwards. 0374 */ 0375 void slotNewOffset(int); 0376 0377 void slotEndOffset(int); 0378 0379 protected: 0380 void paintEvent(QPaintEvent *) override; 0381 0382 private: 0383 KWIDGETSADDONS_NO_EXPORT void initWidget(Qt::Orientation orientation); 0384 0385 private: 0386 std::unique_ptr<class KRulerPrivate> const d; 0387 }; 0388 0389 #endif