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 | */ |
40 | class 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 | |