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
28class QIcon;
29class QPixmap;
30class QPainter;
31class QPoint;
32class 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 */
50class KDEUI_EXPORT KRatingPainter
51{
52public:
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
214private:
215 class Private;
216 Private* const d;
217};
218
219#endif
220