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
18 * \inmodule KWidgetsAddons
19 *
20 * \brief Displays a rating value as a row of pixmaps.
21 *
22 * The KRatingWidget displays a range of stars or other arbitrary
23 * pixmaps and allows the user to select a certain number by mouse.
24 *
25 * \sa KRatingPainter
26 */
27class KWIDGETSADDONS_EXPORT KRatingWidget : public QFrame
28{
29 Q_OBJECT
30
31 /*!
32 * \property KRatingWidget::rating
33 */
34 Q_PROPERTY(int rating READ rating WRITE setRating)
35
36 /*!
37 * \property KRatingWidget::maxRating
38 */
39 Q_PROPERTY(int maxRating READ maxRating WRITE setMaxRating)
40
41 /*!
42 * \property KRatingWidget::alignment
43 */
44 Q_PROPERTY(Qt::Alignment alignment READ alignment WRITE setAlignment)
45
46 /*!
47 * \property KRatingWidget::halfStepsEnabled
48 */
49 Q_PROPERTY(bool halfStepsEnabled READ halfStepsEnabled WRITE setHalfStepsEnabled)
50
51 /*!
52 * \property KRatingWidget::spacing
53 */
54 Q_PROPERTY(int spacing READ spacing WRITE setSpacing)
55
56 /*!
57 * \property KRatingWidget::icon
58 */
59 Q_PROPERTY(QIcon icon READ icon WRITE setIcon)
60
61public:
62 /*!
63 * Creates a new rating widget.
64 */
65 explicit KRatingWidget(QWidget *parent = nullptr);
66
67 ~KRatingWidget() override;
68
69 /*!
70 * Returns the current rating.
71 */
72 int rating() const;
73
74 /*!
75 * Returns the maximum possible rating.
76 */
77 int maxRating() const;
78
79 /*!
80 * The alignment of the stars.
81 *
82 * \sa setAlignment
83 */
84 Qt::Alignment alignment() const;
85
86 /*!
87 * The layout direction.
88 *
89 * If RTL the stars
90 * representing the rating value will be drawn from the
91 * right.
92 *
93 * \sa setLayoutDirection
94 */
95 Qt::LayoutDirection layoutDirection() const;
96
97 /*!
98 * The spacing between the rating stars.
99 *
100 * \sa setSpacing
101 */
102 int spacing() const;
103
104 QSize sizeHint() const override;
105
106 /*!
107 * If half steps are enabled one star equals to 2 rating
108 * points and uneven rating values result in half-stars being
109 * drawn.
110 *
111 * \sa setHalfStepsEnabled
112 */
113 bool halfStepsEnabled() const;
114
115 /*!
116 * The icon used to draw a star. In case a custom pixmap has been set
117 * this value is ignored.
118 *
119 * \sa setIcon, setCustomPixmap
120 */
121 QIcon icon() const;
122
123Q_SIGNALS:
124 /*!
125 * This signal is emitted when the rating is changed.
126 */
127 void ratingChanged(int rating);
128
129public Q_SLOTS:
130 /*!
131 * Set the current rating. Calling this method will trigger the
132 * ratingChanged signal if \a rating is different from the previous rating.
133 */
134 void setRating(int rating);
135
136 /*!
137 * Set the maximum allowed rating value. The default is 10 which means
138 * that a rating from 1 to 10 is selectable. If \a max is uneven steps
139 * are automatically only allowed full.
140 */
141 void setMaxRating(int max);
142
143 /*!
144 * If half steps are enabled (the default) then
145 * one rating step corresponds to half a star.
146 */
147 void setHalfStepsEnabled(bool enabled);
148
149 /*!
150 * Set the spacing between the pixmaps. The default is 0.
151 */
152 void setSpacing(int);
153
154 /*!
155 * The alignment of the stars in the drawing rect.
156 * All alignment flags are supported.
157 */
158 void setAlignment(Qt::Alignment align);
159
160 /*!
161 * LTR or RTL
162 */
163 void setLayoutDirection(Qt::LayoutDirection direction);
164
165 /*!
166 * Set a custom icon. Defaults to "rating".
167 */
168 void setIcon(const QIcon &icon);
169
170 /*!
171 * Set a custom pixmap.
172 */
173 void setCustomPixmap(const QPixmap &pixmap);
174
175 /*!
176 * Set the recommended size of the pixmaps. This is
177 * only used for the sizeHint. The actual size is always
178 * dependent on the size of the widget itself.
179 */
180 void setPixmapSize(int size);
181
182protected:
183 void mousePressEvent(QMouseEvent *e) override;
184 void mouseMoveEvent(QMouseEvent *e) override;
185 void leaveEvent(QEvent *e) override;
186 void paintEvent(QPaintEvent *e) override;
187 void resizeEvent(QResizeEvent *e) override;
188
189private:
190 std::unique_ptr<class KRatingWidgetPrivate> const d;
191};
192
193#endif
194

source code of kwidgetsaddons/src/kratingwidget.h