1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2007-2008 Sebastian Trueg <trueg@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KRATINGPAINTER_H
9#define KRATINGPAINTER_H
10
11#include <kwidgetsaddons_export.h>
12
13#include <Qt>
14#include <memory>
15
16class QIcon;
17class QPixmap;
18class QPainter;
19class QPoint;
20class QRect;
21
22/*!
23 * \class KRatingPainter
24 * \inmodule KWidgetsAddons
25 *
26 * \brief Utility class that draws a row of stars for a rating value.
27 *
28 * The KRatingPainter also allows to determine a rating value from
29 * a position in the draw area. it supports all different alignments
30 * and custom icons.
31 *
32 * For showing a rating in a widget see KRatingWidget.
33 *
34 * \since 4.1
35 */
36class KWIDGETSADDONS_EXPORT KRatingPainter
37{
38public:
39 /*!
40 * Create a new KRatingPainter.
41 * For most cases the static methods paintRating and getRatingFromPosition
42 * should be sufficient.
43 */
44 KRatingPainter();
45
46 ~KRatingPainter();
47
48 KRatingPainter(const KRatingPainter &) = delete;
49 KRatingPainter &operator=(const KRatingPainter &) = delete;
50
51 /*!
52 * The maximum rating, i.e. how many stars are drawn
53 * in total.
54 *
55 * \sa setMaxRating
56 */
57 int maxRating() const;
58
59 /*!
60 * If half steps are enabled one star equals to 2 rating
61 * points and uneven rating values result in half-stars being
62 * drawn.
63 *
64 * \sa setHalfStepsEnabled
65 */
66 bool halfStepsEnabled() const;
67
68 /*!
69 * The alignment of the stars.
70 *
71 * \sa setAlignment
72 */
73 Qt::Alignment alignment() const;
74
75 /*!
76 * The layout direction. If RTL the stars
77 * representing the rating value will be drawn from the
78 * right.
79 *
80 * \sa setLayoutDirection
81 */
82 Qt::LayoutDirection layoutDirection() const;
83
84 /*!
85 * The icon used to draw a star. In case a custom pixmap has been set
86 * this value is ignored.
87 *
88 * \sa setIcon, setCustomPixmap
89 */
90 QIcon icon() const;
91
92 /*!
93 * The rating can be painted in a disabled state where no color
94 * is used and hover ratings are ignored.
95 *
96 * \sa setEnabled
97 */
98 bool isEnabled() const;
99
100 /*!
101 * The custom pixmap set to draw a star. If no custom
102 * pixmap has been set, an invalid pixmap is returned.
103 *
104 * \sa setCustomPixmap
105 */
106 QPixmap customPixmap() const;
107
108 /*!
109 * The spacing between rating pixmaps.
110 *
111 * \sa setSpacing
112 */
113 int spacing() const;
114
115 /*!
116 * The maximum rating. Defaults to 10.
117 */
118 void setMaxRating(int max);
119
120 /*!
121 * If half steps are enabled (the default) then
122 * one rating step corresponds to half a star.
123 */
124 void setHalfStepsEnabled(bool enabled);
125
126 /*!
127 * The alignment of the stars in the drawing rect.
128 * All alignment flags are supported.
129 */
130 void setAlignment(Qt::Alignment align);
131
132 /*!
133 * LTR or RTL
134 */
135 void setLayoutDirection(Qt::LayoutDirection direction);
136
137 /*!
138 * Set a custom icon. Defaults to "rating".
139 */
140 void setIcon(const QIcon &icon);
141
142 /*!
143 * Enable or disable the rating. Default is enabled.
144 */
145 void setEnabled(bool enabled);
146
147 /*!
148 * Set a custom pixmap.
149 */
150 void setCustomPixmap(const QPixmap &pixmap);
151
152 /*!
153 * Set the spacing between rating pixmaps. Be aware that
154 * for justified horizontal alignment this values may be
155 * ignored.
156 */
157 void setSpacing(int spacing);
158
159 /*!
160 * Draw the rating.
161 *
162 * \a painter The painter to draw the rating to.
163 *
164 * \a rect The geometry of the rating. The alignment of the rating is used relative
165 * to this value.
166 *
167 * \a rating The actual rating value to draw.
168 *
169 * \a hoverRating The hover rating indicates the position the user hovers the mouse
170 * pointer at. This will provide visual feedback about the new rating
171 * if the user would actually click as well as the difference to the
172 * current rating.
173 */
174 void paint(QPainter *painter, const QRect &rect, int rating, int hoverRating = -1) const;
175
176 /*!
177 * Calculate the rating value from mouse position pos.
178 *
179 * Returns the rating corresponding to pos or -1 if pos is
180 * outside of the configured rect.
181 */
182 int ratingFromPosition(const QRect &rect, const QPoint &pos) const;
183
184 /*!
185 * Convenience method that paints a rating into the given rect.
186 *
187 * LayoutDirection is read from QPainter.
188 *
189 * \a align can be aligned vertically and horizontally. Using Qt::AlignJustify will insert spacing
190 * between the stars.
191 */
192 static void paintRating(QPainter *p, const QRect &rect, Qt::Alignment align, int rating, int hoverRating = -1);
193
194 /*!
195 * Get the rating that would be selected if the user clicked position pos
196 * within rect if the rating has been drawn with paintRating() using the same
197 * rect and align values.
198 *
199 * \return The new rating or -1 if pos is outside of the rating area.
200 */
201 static int getRatingFromPosition(const QRect &rect, Qt::Alignment align, Qt::LayoutDirection direction, const QPoint &pos);
202
203private:
204 std::unique_ptr<class KRatingPainterPrivate> const d;
205};
206
207#endif
208

source code of kwidgetsaddons/src/kratingpainter.h