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

source code of kwidgetsaddons/src/kratingwidget.h