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