src/ratingpainter.h

   1 /*
   2    This file is part of the Nepomuk KDE project.
   3    Copyright (C) 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 version 2 as published by the Free Software Foundation.
   8
   9    This library is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12    Library General Public License for more details.
  13
  14    You should have received a copy of the GNU Library General Public License
  15    along with this library; see the file COPYING.LIB.  If not, write to
  16    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17    Boston, MA 02110-1301, USA.
  18  */
  19
  20 #ifndef _NEPOMUK_RATING_PAINTER_H_
  21 #define _NEPOMUK_RATING_PAINTER_H_
  22
  23 class QPainter;
  24
  25 #include <QtCore/QRect>
  26 #include <QtCore/QPoint>
  27
  28 #include <kicon.h>
  29
  30 #include <nepomuk/nepomuk_export.h>
  31
  32
  33 namespace Nepomuk {
  34     /**
  35      * Utility class that draws a row of stars for a rating value.
  36      */
  37     class NEPOMUK_EXPORT RatingPainter
  38     {
  39     public:
  40         /**
  41          * Create a new RatingPainter.
  42          * Normally the static methods should be sufficient.
  43          */
  44         RatingPainter();
  45         ~RatingPainter();
  46
  47         int maxRating() const;
  48         bool halfStepsEnabled() const;
  49         Qt::Alignment alignment() const;
  50         Qt::LayoutDirection direction() const;
  51         KIcon icon() const;
  52         QPixmap customPixmap() const;
  53
  54         /**
  55          * The maximum rating. Defaults to 10.
  56          */
  57         void setMaxRating( int max );
  58
  59         /**
  60          * If half steps are enabled (the default) then
  61          * one rating step corresponds to half a star.
  62          */
  63         void setHalfStepsEnabled( bool enabled );
  64
  65         /**
  66          * The alignment of the stars in the drawing rect.
  67          * All alignment flags are supported.
  68          */
  69         void setAlignment( Qt::Alignment align );
  70
  71         /**
  72          * LTR or RTL
  73          */
  74         void setLayoutDirection( Qt::LayoutDirection direction );
  75
  76         /**
  77          * Set a custom icon. Defaults to "rating".
  78          */
  79         void setIcon( const KIcon& icon );
  80
  81         /**
  82          * Set a custom pixmap.
  83          */
  84         void setCustomPixmap( const QPixmap& pixmap );
  85
  86         /**
  87          * Draw the rating into the configured rect.
  88          */
  89         void draw( QPainter* painter, const QRect& rect, int rating, int hoverRating = -1 );
  90
  91         /**
  92          * Calculate the rating value from mouse position pos.
  93          *
  94          * \return The rating corresponding to pos or -1 if pos is
  95          * outside of the configured rect.
  96          */
  97         int fromPosition( const QRect& rect, const QPoint& pos );
  98
  99         /**
 100          * Convenience method that draws a rating into the given rect.
 101          *
 102          * LayoutDirection is read from QPainter.
 103          *
 104          * \param align can be aligned vertically and horizontally. Using Qt::AlignJustify will insert spacing
 105          * between the stars.
 106          */
 107         static void drawRating( QPainter* p, const QRect& rect, Qt::Alignment align, int rating, int hoverRating = -1 );
 108
 109         /**
 110          * Get the rating that would be selected if the user clicked position pos
 111          * within rect if the rating has been drawn with drawRating() using the same
 112          * rect and align values.
 113          *
 114          * \return The new rating or -1 if pos is outside of the rating area.
 115          */
 116         static int getRatingFromPosition( const QRect& rect, Qt::Alignment align, Qt::LayoutDirection direction, const QPoint& pos );
 117
 118     private:
 119         class Private;
 120         Private* const d;
 121     };
 122 }
 123
 124 #endif