1 /* 2 This file is part of the KDE libraries 3 SPDX-FileCopyrightText: 2006-2007 Sebastian Trueg <trueg@kde.org> 4 5 SPDX-License-Identifier: LGPL-2.0-or-later 6 */ 7 8 #ifndef KRATINGWIDGET_H 9 #define KRATINGWIDGET_H 10 11 #include <QFrame> 12 #include <memory> 13 14 #include <kwidgetsaddons_export.h> 15 16 /** 17 * \class KRatingWidget kratingwidget.h KRatingWidget 18 * 19 * \brief Displays a rating value as a row of pixmaps. 20 * 21 * The KRatingWidget displays a range of stars or other arbitrary 22 * pixmaps and allows the user to select a certain number by mouse. 23 * 24 * \sa KRatingPainter 25 * 26 * \author Sebastian Trueg <trueg@kde.org> 27 */ 28 class KWIDGETSADDONS_EXPORT KRatingWidget : public QFrame 29 { 30 Q_OBJECT 31 Q_PROPERTY(int rating READ rating WRITE setRating) 32 Q_PROPERTY(int maxRating READ maxRating WRITE setMaxRating) 33 Q_PROPERTY(Qt::Alignment alignment READ alignment WRITE setAlignment) 34 Q_PROPERTY(bool halfStepsEnabled READ halfStepsEnabled WRITE setHalfStepsEnabled) 35 Q_PROPERTY(int spacing READ spacing WRITE setSpacing) 36 Q_PROPERTY(QIcon icon READ icon WRITE setIcon) 37 38 public: 39 /** 40 * Creates a new rating widget. 41 */ 42 explicit KRatingWidget(QWidget *parent = nullptr); 43 44 /** 45 * Destructor 46 */ 47 ~KRatingWidget() override; 48 49 #if KWIDGETSADDONS_BUILD_DEPRECATED_SINCE(5, 85) 50 /** 51 * \return The current rating. 52 */ 53 unsigned int rating() const; 54 #else 55 /** 56 * \return The current rating. 57 */ 58 int rating() const; 59 #endif 60 61 /** 62 * \return the maximum possible rating. 63 */ 64 int maxRating() const; 65 66 /** 67 * The alignment of the stars. 68 * 69 * \sa setAlignment 70 */ 71 Qt::Alignment alignment() const; 72 73 /** 74 * The layout direction. If RTL the stars 75 * representing the rating value will be drawn from the 76 * right. 77 * 78 * \sa setLayoutDirection 79 */ 80 Qt::LayoutDirection layoutDirection() const; 81 82 /** 83 * The spacing between the rating stars. 84 * 85 * \sa setSpacing 86 */ 87 int spacing() const; 88 89 QSize sizeHint() const override; 90 91 /** 92 * If half steps are enabled one star equals to 2 rating 93 * points and uneven rating values result in half-stars being 94 * drawn. 95 * 96 * \sa setHalfStepsEnabled 97 */ 98 bool halfStepsEnabled() const; 99 100 /** 101 * The icon used to draw a star. In case a custom pixmap has been set 102 * this value is ignored. 103 * 104 * \sa setIcon, setCustomPixmap 105 */ 106 QIcon icon() const; 107 108 Q_SIGNALS: 109 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 85) 110 /** 111 * @deprecated Since 5.85, use ratingChanged(int) instead 112 */ 113 KWIDGETSADDONS_DEPRECATED_VERSION(5, 85, "use ratingChanged(int) instead") 114 void ratingChanged(unsigned int rating); // clazy:exclude=overloaded-signal 115 #endif 116 117 /** 118 * This signal is emitted when the rating is changed. 119 */ 120 void ratingChanged(int rating); // clazy:exclude=overloaded-signal 121 122 public Q_SLOTS: 123 /** 124 * Set the current rating. Calling this method will trigger the 125 * ratingChanged signal if @p rating is different from the previous rating. 126 */ 127 void setRating(int rating); 128 129 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0) 130 /** 131 * \deprecated Since 5.0, use setRating(int rating) 132 */ 133 KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KRatingWidget::setRating(int)") 134 void setRating(unsigned int rating); 135 #endif 136 137 /** 138 * Set the maximum allowed rating value. The default is 10 which means 139 * that a rating from 1 to 10 is selectable. If \a max is uneven steps 140 * are automatically only allowed full. 141 */ 142 void setMaxRating(int max); 143 144 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0) 145 /** 146 * \deprecated Since 5.0, use setMaxRating( int max ) 147 */ 148 KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KRatingWidget::setMaxRating(int)") 149 void setMaxRating(unsigned int max); 150 #endif 151 152 /** 153 * If half steps are enabled (the default) then 154 * one rating step corresponds to half a star. 155 */ 156 void setHalfStepsEnabled(bool enabled); 157 158 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0) 159 /** 160 * \deprecated Since 5.0, use setHalfStepsEnabled(bool). 161 */ 162 KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KRatingWidget::setHalfStepsEnabled(bool)") 163 void setOnlyPaintFullSteps(bool); 164 #endif 165 166 /** 167 * Set the spacing between the pixmaps. The default is 0. 168 */ 169 void setSpacing(int); 170 171 /** 172 * The alignment of the stars in the drawing rect. 173 * All alignment flags are supported. 174 */ 175 void setAlignment(Qt::Alignment align); 176 177 /** 178 * LTR or RTL 179 */ 180 void setLayoutDirection(Qt::LayoutDirection direction); 181 182 /** 183 * Set a custom icon. Defaults to "rating". 184 */ 185 void setIcon(const QIcon &icon); 186 187 /** 188 * Set a custom pixmap. 189 */ 190 void setCustomPixmap(const QPixmap &pixmap); 191 192 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0) 193 /** 194 * Set the pixap to be used to display a rating step. 195 * By default the "rating" pixmap is loaded. 196 * 197 * \deprecated Since 5.0, use setCustomPixmap() 198 */ 199 KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KRatingWidget::setCustomPixmap(const QPixmap&)") 200 void setPixmap(const QPixmap &); 201 #endif 202 203 /** 204 * Set the recommended size of the pixmaps. This is 205 * only used for the sizeHint. The actual size is always 206 * dependent on the size of the widget itself. 207 */ 208 void setPixmapSize(int size); 209 210 protected: 211 void mousePressEvent(QMouseEvent *e) override; 212 void mouseMoveEvent(QMouseEvent *e) override; 213 void leaveEvent(QEvent *e) override; 214 void paintEvent(QPaintEvent *e) override; 215 void resizeEvent(QResizeEvent *e) override; 216 217 private: 218 std::unique_ptr<class KRatingWidgetPrivate> const d; 219 }; 220 221 #endif 222