1/*
2 * This file is part of the Nepomuk KDE project.
3 * Copyright (C) 2006-2007 Sebastian Trueg <trueg@kde.org>
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Library General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Library General Public License for more details.
14 *
15 * You should have received a copy of the GNU Library General Public License
16 * along with this library; see the file COPYING.LIB. If not, write to
17 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 * Boston, MA 02110-1301, USA.
19 */
20
21#ifndef KRATINGWIDGET_H
22#define KRATINGWIDGET_H
23
24#include <QtGui/QFrame>
25
26#include <kdeui_export.h>
27
28/**
29 * \class KRatingWidget kratingwidget.h KDE/KRatingWidget
30 *
31 * \brief Displays a rating value as a row of pixmaps.
32 *
33 * The KRatingWidget displays a range of stars or other arbitrary
34 * pixmaps and allows the user to select a certain number by mouse.
35 *
36 * \sa KRatingPainter
37 *
38 * \author Sebastian Trueg <trueg@kde.org>
39 */
40class KDEUI_EXPORT KRatingWidget : public QFrame
41{
42 Q_OBJECT
43 Q_PROPERTY( int rating READ rating WRITE setRating )
44 Q_PROPERTY( int maxRating READ maxRating WRITE setMaxRating )
45 Q_PROPERTY( Qt::Alignment alignment READ alignment WRITE setAlignment )
46 Q_PROPERTY( bool halfStepsEnabled READ halfStepsEnabled WRITE setHalfStepsEnabled )
47 Q_PROPERTY( int spacing READ spacing WRITE setSpacing )
48 Q_PROPERTY( QIcon icon READ icon WRITE setIcon )
49
50 public:
51 /**
52 * Creates a new rating widget.
53 */
54 KRatingWidget( QWidget* parent = 0 );
55
56 /**
57 * Destructor
58 */
59 ~KRatingWidget();
60
61 /**
62 * \return The current rating.
63 */
64 unsigned int rating() const;
65
66 /**
67 * \return the maximum possible rating.
68 */
69 int maxRating() const;
70
71 /**
72 * The alignment of the stars.
73 *
74 * \sa setAlignment
75 */
76 Qt::Alignment alignment() const;
77
78 /**
79 * The layout direction. If RTL the stars
80 * representing the rating value will be drawn from the
81 * right.
82 *
83 * \sa setLayoutDirection
84 */
85 Qt::LayoutDirection layoutDirection() const;
86
87 /**
88 * The spacing between the rating stars.
89 *
90 * \sa setSpacing
91 */
92 int spacing() const;
93
94 QSize sizeHint() const;
95
96 /**
97 * If half steps are enabled one star equals to 2 rating
98 * points and uneven rating values result in half-stars being
99 * drawn.
100 *
101 * \sa setHalfStepsEnabled
102 */
103 bool halfStepsEnabled() const;
104
105 /**
106 * The icon used to draw a star. In case a custom pixmap has been set
107 * this value is ignored.
108 *
109 * \sa setIcon, setCustomPixmap
110 */
111 QIcon icon() const;
112
113 Q_SIGNALS:
114 /**
115 * This signal is emitted when the rating is changed.
116 */
117 void ratingChanged( unsigned int rating );
118 void ratingChanged( int rating );
119
120 public Q_SLOTS:
121 /**
122 * Set the current rating. Calling this method will trigger the
123 * ratingChanged signal if @p rating is different from the previous rating.
124 */
125 void setRating( int rating );
126
127 /**
128 * \deprecated use setRating( int rating )
129 */
130#ifndef KDE_NO_DEPRECATED
131 KDE_DEPRECATED void setRating( unsigned int rating );
132#endif
133
134 /**
135 * Set the maximum allowed rating value. The default is 10 which means
136 * that a rating from 1 to 10 is selectable. If \a max is uneven steps
137 * are automatically only allowed full.
138 */
139 void setMaxRating( int max );
140
141 /**
142 * \deprecated use setMaxRating( int max )
143 */
144#ifndef KDE_NO_DEPRECATED
145 KDE_DEPRECATED void setMaxRating( unsigned int max );
146#endif
147
148 /**
149 * If half steps are enabled (the default) then
150 * one rating step corresponds to half a star.
151 */
152 void setHalfStepsEnabled( bool enabled );
153
154 /**
155 * \deprecated Use setHalfStepsEnabled
156 */
157#ifndef KDE_NO_DEPRECATED
158 KDE_DEPRECATED void setOnlyPaintFullSteps( bool );
159#endif
160
161 /**
162 * Set the spacing between the pixmaps. The default is 0.
163 */
164 void setSpacing( int );
165
166 /**
167 * The alignment of the stars in the drawing rect.
168 * All alignment flags are supported.
169 */
170 void setAlignment( Qt::Alignment align );
171
172 /**
173 * LTR or RTL
174 */
175 void setLayoutDirection( Qt::LayoutDirection direction );
176
177 /**
178 * Set a custom icon. Defaults to "rating".
179 */
180 void setIcon( const QIcon& icon );
181
182 /**
183 * Set a custom pixmap.
184 */
185 void setCustomPixmap( const QPixmap& pixmap );
186
187 /**
188 * Set the pixap to be used to display a rating step.
189 * By default the "rating" pixmap is loaded.
190 *
191 * \deprecated use setCustomPixmap
192 */
193#ifndef KDE_NO_DEPRECATED
194 KDE_DEPRECATED void setPixmap( const QPixmap& );
195#endif
196
197 /**
198 * Set the recommended size of the pixmaps. This is
199 * only used for the sizeHint. The actual size is always
200 * dependent on the size of the widget itself.
201 */
202 void setPixmapSize( int size );
203
204 protected:
205 void mousePressEvent( QMouseEvent* e );
206 void mouseMoveEvent( QMouseEvent* e );
207 void leaveEvent( QEvent* e );
208 void paintEvent( QPaintEvent* e );
209 void resizeEvent( QResizeEvent* e );
210
211 private:
212 class Private;
213 Private* const d;
214};
215
216#endif
217