File indexing completed on 2024-04-28 03:59:13
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 /** 0120 * Sets the distance between tiny marks. 0121 * 0122 * This is mostly used in the English system (inches) with distance of 1. 0123 */ 0124 void setTinyMarkDistance(int); 0125 /** 0126 * Returns the distance between tiny marks. 0127 */ 0128 int tinyMarkDistance() const; 0129 0130 /** 0131 * Sets the distance between little marks. 0132 * 0133 * The default value is 1 in the metric system and 2 in the English (inches) system. 0134 */ 0135 void setLittleMarkDistance(int); 0136 0137 /** 0138 * Returns the distance between little marks. 0139 */ 0140 int littleMarkDistance() const; 0141 0142 /** 0143 * Sets the distance between medium marks. 0144 * 0145 * For English (inches) styles it defaults to twice the little mark distance. 0146 * For metric styles it defaults to five times the little mark distance. 0147 */ 0148 void setMediumMarkDistance(int); 0149 int mediumMarkDistance() const; 0150 0151 /** 0152 * Sets distance between big marks. 0153 * 0154 * For English (inches) or metric styles it is twice the medium mark distance. 0155 */ 0156 void setBigMarkDistance(int); 0157 /** 0158 * Returns the distance between big marks. 0159 */ 0160 int bigMarkDistance() const; 0161 0162 /** 0163 * Shows/hides tiny marks. 0164 */ 0165 void setShowTinyMarks(bool); 0166 bool showTinyMarks() const; 0167 /** 0168 * Shows/hides little marks. 0169 */ 0170 void setShowLittleMarks(bool); 0171 bool showLittleMarks() const; 0172 /** 0173 * Shows/hides medium marks. 0174 */ 0175 void setShowMediumMarks(bool); 0176 bool showMediumMarks() const; 0177 /** 0178 * Shows/hides big marks. 0179 */ 0180 void setShowBigMarks(bool); 0181 bool showBigMarks() const; 0182 /** 0183 * Shows/hides end marks. 0184 */ 0185 void setShowEndMarks(bool); 0186 bool showEndMarks() const; 0187 /** 0188 * Shows/hides the pointer. 0189 */ 0190 void setShowPointer(bool); 0191 bool showPointer() const; 0192 0193 /** 0194 * Show/hide number values of the end marks. 0195 * 0196 * Default is @p false. 0197 */ 0198 void setShowEndLabel(bool); 0199 bool showEndLabel() const; 0200 0201 /** 0202 * Sets the label this is drawn at the beginning of the visible part 0203 * of the ruler to @p label 0204 */ 0205 void setEndLabel(const QString &); 0206 QString endLabel() const; 0207 0208 /** 0209 * Sets up the necessary tasks for the provided styles. 0210 * 0211 * A convenience method. 0212 */ 0213 void setRulerMetricStyle(KRuler::MetricStyle); 0214 0215 /** 0216 * Sets the number of pixels between two base marks. 0217 * 0218 * Calling this method stretches or shrinks your ruler. 0219 * 0220 * For pixel display ( MetricStyle) the value is 10.0 marks 0221 * per pixel ;-) 0222 * For English (inches) it is 9.0, and for centimetres ~2.835 -> 3.0 . 0223 * If you want to magnify your part of display, you have to 0224 * adjust the mark distance @p here. 0225 * Notice: The double type is only supported to give the possibility 0226 * of having some double values. 0227 * It should be used with care. Using values below 10.0 0228 * shows visible jumps of markpositions (e.g. 2.345). 0229 * Using whole numbers is highly recommended. 0230 * To use @p int values use setPixelPerMark((int)your_int_value); 0231 * default: 1 mark per 10 pixels 0232 */ 0233 void setPixelPerMark(double rate); 0234 0235 /** 0236 * Returns the number of pixels between two base marks. 0237 */ 0238 double pixelPerMark() const; 0239 0240 /** 0241 * Sets the length of the ruler, i.e. the difference between 0242 * the begin mark and the end mark of the ruler. 0243 * 0244 * Same as (width() - offset()) 0245 * 0246 * when the length is not locked, it gets adjusted with the 0247 * length of the widget. 0248 */ 0249 void setLength(int); 0250 int length() const; 0251 0252 /** 0253 * Locks the length of the ruler, i.e. the difference between 0254 * the two end marks doesn't change when the widget is resized. 0255 * 0256 * @param fix fixes the length, if true 0257 */ 0258 void setLengthFixed(bool fix); 0259 bool lengthFixed() const; 0260 0261 /** 0262 * Sets the number of pixels by which the ruler may slide up or left. 0263 * The number of pixels moved is realive to the previous position. 0264 * The Method makes sense for updating a ruler, which is working with 0265 * a scrollbar. 0266 * 0267 * This doesn't affect the position of the ruler pointer. 0268 * Only the visible part of the ruler is moved. 0269 * 0270 * @param count Number of pixel moving up or left relative to the previous position 0271 */ 0272 void slideUp(int count = 1); 0273 0274 /** 0275 * Sets the number of pixels by which the ruler may slide down or right. 0276 * The number of pixels moved is realive to the previous position. 0277 * The Method makes sense for updating a ruler, which is working with 0278 * a scrollbar. 0279 * 0280 * This doesn't affect the position of the ruler pointer. 0281 * Only the visible part of the ruler is moved. 0282 * 0283 * @param count Number of pixel moving up or left relative to the previous position 0284 */ 0285 void slideDown(int count = 1); 0286 0287 /** 0288 * Sets the ruler slide offset. 0289 * 0290 * This is like slideup() or slidedown() with an absolute offset 0291 * from the start of the ruler. 0292 * 0293 * @param offset Number of pixel to move the ruler up or left from the beginning 0294 */ 0295 void setOffset(int offset); 0296 0297 /** 0298 * Returns the current ruler offset. 0299 */ 0300 int offset() const; 0301 0302 int endOffset() const; 0303 0304 public Q_SLOTS: 0305 0306 /** 0307 * Sets the pointer to a new position. 0308 * 0309 * The offset is NOT updated. 0310 * QWidget::repaint() is called afterwards. 0311 */ 0312 void slotNewValue(int); 0313 0314 /** 0315 * Sets the ruler marks to a new position. 0316 * 0317 * The pointer is NOT updated. 0318 * QWidget::repaint() is called afterwards. 0319 */ 0320 void slotNewOffset(int); 0321 0322 void slotEndOffset(int); 0323 0324 protected: 0325 void paintEvent(QPaintEvent *) override; 0326 0327 private: 0328 KWIDGETSADDONS_NO_EXPORT void initWidget(Qt::Orientation orientation); 0329 0330 private: 0331 std::unique_ptr<class KRulerPrivate> const d; 0332 }; 0333 0334 #endif