workspace/libs/plasma/svg.h

   1 /*
   2  *   Copyright 2006-2007 Aaron Seigo <aseigo@kde.org>
   3  *
   4  *   This program is free software; you can redistribute it and/or modify
   5  *   it under the terms of the GNU Library General Public License as
   6  *   published by the Free Software Foundation; either version 2, or
   7  *   (at your option) any later version.
   8  *
   9  *   This program 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
  12  *   GNU General Public License for more details
  13  *
  14  *   You should have received a copy of the GNU Library General Public
  15  *   License along with this program; if not, write to the
  16  *   Free Software Foundation, Inc.,
  17  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  18  */
  19
  20 #ifndef PLASMA_SVG_H
  21 #define PLASMA_SVG_H
  22
  23 #include <QtCore/QObject>
  24
  25 #include <plasma/plasma_export.h>
  26
  27 class QPainter;
  28 class QPoint;
  29 class QPointF;
  30 class QRect;
  31 class QRectF;
  32 class QSize;
  33 class QSizeF;
  34 class QMatrix;
  35
  36 namespace Plasma
  37 {
  38
  39 /**
  40  * @brief A theme aware image-centric SVG class
  41  *
  42  * Plasma::Svg provides a class for rendering SVG images to a QPainter in a
  43  * convenient manner. Unless an absolute path to a file is provided, it loads
  44  * the SVG document using Plasma::Theme. It also provides a number of internal
  45  * optimizations to help lower the cost of painting SVGs, such as caching.
  46  **/
  47 class PLASMA_EXPORT Svg : public QObject
  48 {
  49     Q_OBJECT
  50     Q_ENUMS( ContentType )
  51     Q_PROPERTY( QSize size READ size )
  52     Q_PROPERTY( ContentType contentType READ contentType WRITE setContentType )
  53     Q_PROPERTY( QString file READ file WRITE setFile )
  54
  55     public:
  56         /**
  57          * Describes what is in the Svg document to be loaded. The important
  58          * distinction is whether the Svg is a single image (or group of
  59          * elements) that are meant to be viewed together, such as a clock face
  60          * and hands, or a set of images that are meant to be displayed
  61          * individually, such as a deck of cards.
  62          */
  63         enum ContentType { SingleImage = 0 /**< A set of elements that together
  64                                                 make an image. Elements may be
  65                                                 drawn separately to accomplish
  66                                                 this. This is the default. */,
  67                            ImageSet /**< A set of elements, each of which
  68                                          constitutes a whole image. Each
  69                                          element will therefore be rendered
  70                                          to the set size of the Svg object */
  71                          };
  72
  73         /**
  74          * Constructs an SVG object that implicitly shares and caches rendering
  75          * As opposed to QSvgRenderer, which this class uses internally,
  76          * Plasma::Svg represents an image generated from an SVG. As such, it
  77          * has a related size and transform matrix (the latter being provided
  78          * by the painter used to paint the image).
  79          *
  80          * The size is initialized to be the SVG's native size.
  81          *
  82          * @arg imagePath the image to show. If a relative path is passed, then
  83          *      Plasma::Theme is used to load the SVG.
  84          * @arg parent options QObject to parent this to
  85          *
  86          * @related Plasma::Theme
  87          */
  88         explicit Svg(const QString& imagePath = QString(), QObject* parent = 0);
  89         ~Svg();
  90
  91
  92         /**
  93          * Paints the SVG represented by this object
  94          * @arg painter the QPainter to use
  95          * @arg point the position to start drawing; the entire svg will be
  96          *      drawn starting at this point.
  97          */
  98         Q_INVOKABLE void paint(QPainter* painter, const QPointF& point,
  99                                const QString& elementID = QString());
 100
 101         /**
 102          * Paints the SVG represented by this object
 103          * @arg painter the QPainter to use
 104          * @arg x the horizontal coordinate to start painting from
 105          * @arg y the vertical coordinate to start painting from
 106          */
 107         Q_INVOKABLE void paint(QPainter* painter, int x, int y,
 108                                const QString& elementID = QString());
 109
 110         /**
 111          * Paints the SVG represented by this object
 112          * @arg painter the QPainter to use
 113          * @arg rect the rect to draw into; if small than the current size
 114          *           of the
 115          *      drawn starting at this point.
 116          */
 117         Q_INVOKABLE void paint(QPainter* painter, const QRectF& rect,
 118                                const QString& elementID = QString());
 119
 120         /**
 121          * Resizes the rendered image. Rendering will actually take place on
 122          * the next call to paint.
 123          * @arg width the new width
 124          * @arg height the new height
 125          **/
 126         Q_INVOKABLE void resize( int width, int height );
 127
 128         /**
 129          * Resizes the rendered image. Rendering will actually take place on
 130          * the next call to paint.
 131          * @arg size the new size of the image
 132          **/
 133         Q_INVOKABLE void resize( const QSizeF& size );
 134
 135         /**
 136          * Resizes the rendered image to the natural size of the SVG.
 137          * Rendering will actually take place on the next call to paint.
 138          **/
 139         Q_INVOKABLE void resize();
 140
 141         /**
 142          * Size of a given element
 143          * @arg elementId the id of the element to check
 144          * @return the current size of a given element, given the current size of the Svg
 145          **/
 146         Q_INVOKABLE QSize elementSize( const QString& elementId ) const;
 147
 148         /**
 149          * The bounding rect of a given element
 150          * @arg elementId the id of the element to check
 151          * @return the current rect of a given element, given the current size of the Svg
 152          **/
 153         Q_INVOKABLE QRect elementRect(const QString& elementId) const;
 154
 155         /**
 156          * Check when an element exists in the loaded Svg
 157          * @arg elementId the id of the element to check
 158          * @return true if the element is defined in the Svg, otherwise false
 159          **/
 160         Q_INVOKABLE bool elementExists( const QString& elementId ) const;
 161
 162         /**
 163          * Returns the element (by id) at the given point. An empty string is
 164          * returned if no element is at that point.
 165          */
 166         Q_INVOKABLE QString elementAtPoint(const QPoint &point) const;
 167
 168         /**
 169          * The transformation matrix of the element. That includes the
 170          * transformation on the element itself.
 171          * @arg elementId the id of the element
 172          * @return the matrix for the element
 173          **/
 174         Q_INVOKABLE QMatrix matrixForElement(const QString& elementId) const;
 175
 176         /**
 177          * @return true if the SVG file exists and the document is valid,
 178          *         otherwise false. This method can be expensive as it
 179          *         causes disk access.
 180          **/
 181         Q_INVOKABLE bool isValid() const;
 182
 183         /**
 184          * Currently set size of the SVG
 185          * @return the current size of a given element
 186          **/
 187         QSize size() const;
 188
 189         /**
 190          * Sets what sort of content is in the Svg.
 191          * @see ContentType
 192          * @arg contents whether the Svg is a single image or a set of images
 193          */
 194         void setContentType(ContentType contentType);
 195
 196         /**
 197          * Returns the content type of the Svg
 198          * @see SetContentType
 199          * @arg contents whether the Svg is a single image or a set of images
 200          */
 201         ContentType contentType();
 202
 203         /**
 204          * Convenience method for setting the svg file to use for the Svg.
 205          * @arg svgFilePath the filepath including name of the svg.
 206          */
 207         void setFile(const QString &svgFilePath);
 208
 209         /**
 210          * Convenience method to get the svg filepath and name of svg.
 211          * @return the svg's filepath including name of the svg.
 212          */
 213         QString file() const;
 214
 215     Q_SIGNALS:
 216         void repaintNeeded();
 217
 218     private Q_SLOTS:
 219         void themeChanged();
 220         void colorsChanged();
 221
 222     private:
 223         class Private;
 224         Private* const d;
 225 };
 226
 227 } // Plasma namespace
 228
 229 #endif // multiple inclusion guard
 230