File indexing completed on 2025-02-02 14:20:09
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 2007-2008 Sebastian Trueg <trueg@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef KRATINGPAINTER_H 0009 #define KRATINGPAINTER_H 0010 0011 #include <kwidgetsaddons_export.h> 0012 0013 #include <Qt> 0014 #include <memory> 0015 0016 class QIcon; 0017 class QPixmap; 0018 class QPainter; 0019 class QPoint; 0020 class QRect; 0021 0022 /** 0023 * \class KRatingPainter kratingpainter.h KRatingPainter 0024 * 0025 * \brief Utility class that draws a row of stars for a rating value. 0026 * 0027 * The KRatingPainter also allows to determine a rating value from 0028 * a position in the draw area. it supports all different alignments 0029 * and custom icons. 0030 * 0031 * For showing a rating in a widget see KRatingWidget. 0032 * 0033 * \author Sebastian Trueg <trueg@kde.org> 0034 * 0035 * \since 4.1 0036 */ 0037 class KWIDGETSADDONS_EXPORT KRatingPainter 0038 { 0039 public: 0040 /** 0041 * Create a new KRatingPainter. 0042 * For most cases the static methods paintRating and getRatingFromPosition 0043 * should be sufficient. 0044 */ 0045 KRatingPainter(); 0046 0047 /** 0048 * Destructor 0049 */ 0050 ~KRatingPainter(); 0051 0052 KRatingPainter(const KRatingPainter &) = delete; 0053 KRatingPainter &operator=(const KRatingPainter &) = delete; 0054 0055 /** 0056 * The maximum rating, i.e. how many stars are drawn 0057 * in total. 0058 * 0059 * \sa setMaxRating 0060 */ 0061 int maxRating() const; 0062 0063 /** 0064 * If half steps are enabled one star equals to 2 rating 0065 * points and uneven rating values result in half-stars being 0066 * drawn. 0067 * 0068 * \sa setHalfStepsEnabled 0069 */ 0070 bool halfStepsEnabled() const; 0071 0072 /** 0073 * The alignment of the stars. 0074 * 0075 * \sa setAlignment 0076 */ 0077 Qt::Alignment alignment() const; 0078 0079 /** 0080 * The layout direction. If RTL the stars 0081 * representing the rating value will be drawn from the 0082 * right. 0083 * 0084 * \sa setLayoutDirection 0085 */ 0086 Qt::LayoutDirection layoutDirection() const; 0087 0088 /** 0089 * The icon used to draw a star. In case a custom pixmap has been set 0090 * this value is ignored. 0091 * 0092 * \sa setIcon, setCustomPixmap 0093 */ 0094 QIcon icon() const; 0095 0096 /** 0097 * The rating can be painted in a disabled state where no color 0098 * is used and hover ratings are ignored. 0099 * 0100 * \sa setEnabled 0101 */ 0102 bool isEnabled() const; 0103 0104 /** 0105 * The custom pixmap set to draw a star. If no custom 0106 * pixmap has been set, an invalid pixmap is returned. 0107 * 0108 * \sa setCustomPixmap 0109 */ 0110 QPixmap customPixmap() const; 0111 0112 /** 0113 * The spacing between rating pixmaps. 0114 * 0115 * \sa setSpacing 0116 */ 0117 int spacing() const; 0118 0119 /** 0120 * The maximum rating. Defaults to 10. 0121 */ 0122 void setMaxRating(int max); 0123 0124 /** 0125 * If half steps are enabled (the default) then 0126 * one rating step corresponds to half a star. 0127 */ 0128 void setHalfStepsEnabled(bool enabled); 0129 0130 /** 0131 * The alignment of the stars in the drawing rect. 0132 * All alignment flags are supported. 0133 */ 0134 void setAlignment(Qt::Alignment align); 0135 0136 /** 0137 * LTR or RTL 0138 */ 0139 void setLayoutDirection(Qt::LayoutDirection direction); 0140 0141 /** 0142 * Set a custom icon. Defaults to "rating". 0143 */ 0144 void setIcon(const QIcon &icon); 0145 0146 /** 0147 * Enable or disable the rating. Default is enabled. 0148 */ 0149 void setEnabled(bool enabled); 0150 0151 /** 0152 * Set a custom pixmap. 0153 */ 0154 void setCustomPixmap(const QPixmap &pixmap); 0155 0156 /** 0157 * Set the spacing between rating pixmaps. Be aware that 0158 * for justified horizontal alignment this values may be 0159 * ignored. 0160 */ 0161 void setSpacing(int spacing); 0162 0163 /** 0164 * Draw the rating. 0165 * 0166 * \param painter The painter to draw the rating to. 0167 * \param rect The geometry of the rating. The alignment of the rating is used relative 0168 * to this value. 0169 * \param rating The actual rating value to draw. 0170 * \param hoverRating The hover rating indicates the position the user hovers the mouse 0171 * pointer at. This will provide visual feedback about the new rating 0172 * if the user would actually click as well as the difference to the 0173 * current rating. 0174 */ 0175 void paint(QPainter *painter, const QRect &rect, int rating, int hoverRating = -1) const; 0176 0177 /** 0178 * Calculate the rating value from mouse position pos. 0179 * 0180 * \return The rating corresponding to pos or -1 if pos is 0181 * outside of the configured rect. 0182 */ 0183 int ratingFromPosition(const QRect &rect, const QPoint &pos) const; 0184 0185 /** 0186 * Convenience method that paints a rating into the given rect. 0187 * 0188 * LayoutDirection is read from QPainter. 0189 * 0190 * \param align can be aligned vertically and horizontally. Using Qt::AlignJustify will insert spacing 0191 * between the stars. 0192 */ 0193 static void paintRating(QPainter *p, const QRect &rect, Qt::Alignment align, int rating, int hoverRating = -1); 0194 0195 /** 0196 * Get the rating that would be selected if the user clicked position pos 0197 * within rect if the rating has been drawn with paintRating() using the same 0198 * rect and align values. 0199 * 0200 * \return The new rating or -1 if pos is outside of the rating area. 0201 */ 0202 static int getRatingFromPosition(const QRect &rect, Qt::Alignment align, Qt::LayoutDirection direction, const QPoint &pos); 0203 0204 private: 0205 std::unique_ptr<class KRatingPainterPrivate> const d; 0206 }; 0207 0208 #endif