File indexing completed on 2025-02-02 14:20:09
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 2006-2007 Sebastian Trueg <trueg@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef KRATINGWIDGET_H 0009 #define KRATINGWIDGET_H 0010 0011 #include <QFrame> 0012 #include <memory> 0013 0014 #include <kwidgetsaddons_export.h> 0015 0016 /** 0017 * \class KRatingWidget kratingwidget.h KRatingWidget 0018 * 0019 * \brief Displays a rating value as a row of pixmaps. 0020 * 0021 * The KRatingWidget displays a range of stars or other arbitrary 0022 * pixmaps and allows the user to select a certain number by mouse. 0023 * 0024 * \sa KRatingPainter 0025 * 0026 * \author Sebastian Trueg <trueg@kde.org> 0027 */ 0028 class KWIDGETSADDONS_EXPORT KRatingWidget : public QFrame 0029 { 0030 Q_OBJECT 0031 Q_PROPERTY(int rating READ rating WRITE setRating) 0032 Q_PROPERTY(int maxRating READ maxRating WRITE setMaxRating) 0033 Q_PROPERTY(Qt::Alignment alignment READ alignment WRITE setAlignment) 0034 Q_PROPERTY(bool halfStepsEnabled READ halfStepsEnabled WRITE setHalfStepsEnabled) 0035 Q_PROPERTY(int spacing READ spacing WRITE setSpacing) 0036 Q_PROPERTY(QIcon icon READ icon WRITE setIcon) 0037 0038 public: 0039 /** 0040 * Creates a new rating widget. 0041 */ 0042 explicit KRatingWidget(QWidget *parent = nullptr); 0043 0044 /** 0045 * Destructor 0046 */ 0047 ~KRatingWidget() override; 0048 0049 #if KWIDGETSADDONS_BUILD_DEPRECATED_SINCE(5, 85) 0050 /** 0051 * \return The current rating. 0052 */ 0053 unsigned int rating() const; 0054 #else 0055 /** 0056 * \return The current rating. 0057 */ 0058 int rating() const; 0059 #endif 0060 0061 /** 0062 * \return the maximum possible rating. 0063 */ 0064 int maxRating() const; 0065 0066 /** 0067 * The alignment of the stars. 0068 * 0069 * \sa setAlignment 0070 */ 0071 Qt::Alignment alignment() const; 0072 0073 /** 0074 * The layout direction. If RTL the stars 0075 * representing the rating value will be drawn from the 0076 * right. 0077 * 0078 * \sa setLayoutDirection 0079 */ 0080 Qt::LayoutDirection layoutDirection() const; 0081 0082 /** 0083 * The spacing between the rating stars. 0084 * 0085 * \sa setSpacing 0086 */ 0087 int spacing() const; 0088 0089 QSize sizeHint() const override; 0090 0091 /** 0092 * If half steps are enabled one star equals to 2 rating 0093 * points and uneven rating values result in half-stars being 0094 * drawn. 0095 * 0096 * \sa setHalfStepsEnabled 0097 */ 0098 bool halfStepsEnabled() const; 0099 0100 /** 0101 * The icon used to draw a star. In case a custom pixmap has been set 0102 * this value is ignored. 0103 * 0104 * \sa setIcon, setCustomPixmap 0105 */ 0106 QIcon icon() const; 0107 0108 Q_SIGNALS: 0109 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 85) 0110 /** 0111 * @deprecated Since 5.85, use ratingChanged(int) instead 0112 */ 0113 KWIDGETSADDONS_DEPRECATED_VERSION(5, 85, "use ratingChanged(int) instead") 0114 void ratingChanged(unsigned int rating); // clazy:exclude=overloaded-signal 0115 #endif 0116 0117 /** 0118 * This signal is emitted when the rating is changed. 0119 */ 0120 void ratingChanged(int rating); // clazy:exclude=overloaded-signal 0121 0122 public Q_SLOTS: 0123 /** 0124 * Set the current rating. Calling this method will trigger the 0125 * ratingChanged signal if @p rating is different from the previous rating. 0126 */ 0127 void setRating(int rating); 0128 0129 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0) 0130 /** 0131 * \deprecated Since 5.0, use setRating(int rating) 0132 */ 0133 KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KRatingWidget::setRating(int)") 0134 void setRating(unsigned int rating); 0135 #endif 0136 0137 /** 0138 * Set the maximum allowed rating value. The default is 10 which means 0139 * that a rating from 1 to 10 is selectable. If \a max is uneven steps 0140 * are automatically only allowed full. 0141 */ 0142 void setMaxRating(int max); 0143 0144 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0) 0145 /** 0146 * \deprecated Since 5.0, use setMaxRating( int max ) 0147 */ 0148 KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KRatingWidget::setMaxRating(int)") 0149 void setMaxRating(unsigned int max); 0150 #endif 0151 0152 /** 0153 * If half steps are enabled (the default) then 0154 * one rating step corresponds to half a star. 0155 */ 0156 void setHalfStepsEnabled(bool enabled); 0157 0158 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0) 0159 /** 0160 * \deprecated Since 5.0, use setHalfStepsEnabled(bool). 0161 */ 0162 KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KRatingWidget::setHalfStepsEnabled(bool)") 0163 void setOnlyPaintFullSteps(bool); 0164 #endif 0165 0166 /** 0167 * Set the spacing between the pixmaps. The default is 0. 0168 */ 0169 void setSpacing(int); 0170 0171 /** 0172 * The alignment of the stars in the drawing rect. 0173 * All alignment flags are supported. 0174 */ 0175 void setAlignment(Qt::Alignment align); 0176 0177 /** 0178 * LTR or RTL 0179 */ 0180 void setLayoutDirection(Qt::LayoutDirection direction); 0181 0182 /** 0183 * Set a custom icon. Defaults to "rating". 0184 */ 0185 void setIcon(const QIcon &icon); 0186 0187 /** 0188 * Set a custom pixmap. 0189 */ 0190 void setCustomPixmap(const QPixmap &pixmap); 0191 0192 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0) 0193 /** 0194 * Set the pixap to be used to display a rating step. 0195 * By default the "rating" pixmap is loaded. 0196 * 0197 * \deprecated Since 5.0, use setCustomPixmap() 0198 */ 0199 KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KRatingWidget::setCustomPixmap(const QPixmap&)") 0200 void setPixmap(const QPixmap &); 0201 #endif 0202 0203 /** 0204 * Set the recommended size of the pixmaps. This is 0205 * only used for the sizeHint. The actual size is always 0206 * dependent on the size of the widget itself. 0207 */ 0208 void setPixmapSize(int size); 0209 0210 protected: 0211 void mousePressEvent(QMouseEvent *e) override; 0212 void mouseMoveEvent(QMouseEvent *e) override; 0213 void leaveEvent(QEvent *e) override; 0214 void paintEvent(QPaintEvent *e) override; 0215 void resizeEvent(QResizeEvent *e) override; 0216 0217 private: 0218 std::unique_ptr<class KRatingWidgetPrivate> const d; 0219 }; 0220 0221 #endif