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 #include <QtGui/QPixmap>
  25
  26 #include <plasma/plasma_export.h>
  27
  28 class QPainter;
  29 class QPoint;
  30 class QPointF;
  31 class QRect;
  32 class QRectF;
  33 class QSize;
  34 class QSizeF;
  35 class QMatrix;
  36
  37 namespace Plasma
  38 {
  39
  40 class SvgPrivate;
  41 class FrameSvgPrivate;
  42
  43 /**
  44  * @class Svg plasma/svg.h <Plasma/Svg>
  45  *
  46  * @short A theme aware image-centric SVG class
  47  *
  48  * Plasma::Svg provides a class for rendering SVG images to a QPainter in a
  49  * convenient manner. Unless an absolute path to a file is provided, it loads
  50  * the SVG document using Plasma::Theme. It also provides a number of internal
  51  * optimizations to help lower the cost of painting SVGs, such as caching.
  52  *
  53  * @see Plasma::FrameSvg
  54  **/
  55 class PLASMA_EXPORT Svg : public QObject
  56 {
  57     Q_OBJECT
  58     Q_ENUMS(ContentType)
  59     Q_PROPERTY(QSize size READ size)
  60     Q_PROPERTY(bool multipleImages READ containsMultipleImages WRITE setContainsMultipleImages)
  61     Q_PROPERTY(QString imagePath READ imagePath WRITE setImagePath)
  62
  63     public:
  64
  65         /**
  66          * Constructs an SVG object that implicitly shares and caches rendering
  67          * As opposed to QSvgRenderer, which this class uses internally,
  68          * Plasma::Svg represents an image generated from an SVG. As such, it
  69          * has a related size and transform matrix (the latter being provided
  70          * by the painter used to paint the image).
  71          *
  72          * The size is initialized to be the SVG's native size.
  73          *
  74          * @arg parent options QObject to parent this to
  75          *
  76          * @related Plasma::Theme
  77          */
  78         explicit Svg(QObject *parent = 0);
  79         ~Svg();
  80
  81         /**
  82          * Returns a pixmap of the SVG represented by this object.
  83          *
  84          * @arg elelementId the ID string of the element to render, or an empty
  85          *                  string for the whole SVG (the default)
  86          * @return a QPixmap of the rendered SVG
  87          */
  88         Q_INVOKABLE QPixmap pixmap(const QString &elementID = QString());
  89
  90         /**
  91          * Paints the SVG represented by this object
  92          * @arg painter the QPainter to use
  93          * @arg point the position to start drawing; the entire svg will be
  94          *      drawn starting at this point.
  95          * @arg elelementId the ID string of the element to render, or an empty
  96          *                  string for the whole SVG (the default)
  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          * @arg elelementId the ID string of the element to render, or an empty
 107          *                  string for the whole SVG (the default)
 108          */
 109         Q_INVOKABLE void paint(QPainter *painter, int x, int y,
 110                                const QString &elementID = QString());
 111
 112         /**
 113          * Paints the SVG represented by this object
 114          * @arg painter the QPainter to use
 115          * @arg rect the rect to draw into; if smaller than the current size
 116          *           the drawing is starting at this point.
 117          * @arg elelementId the ID string of the element to render, or an empty
 118          *                  string for the whole SVG (the default)
 119          */
 120         Q_INVOKABLE void paint(QPainter *painter, const QRectF &rect,
 121                                const QString &elementID = QString());
 122
 123         /**
 124          * Paints the SVG represented by this object
 125          * @arg painter the QPainter to use
 126          * @arg x the horizontal coordinate to start painting from
 127          * @arg y the vertical coordinate to start painting from
 128          * @arg width the width of the element to draw
 129          * @arg height the height of the element do draw
 130          * @arg elelementId the ID string of the element to render, or an empty
 131          *                  string for the whole SVG (the default)
 132          */
 133         Q_INVOKABLE void paint(QPainter *painter, int x, int y, int width,
 134                                int height, const QString &elementID = QString());
 135
 136         /**
 137          * Currently set size of the SVG
 138          * @return the current size of the SVG
 139          **/
 140         QSize size() const;
 141
 142         /**
 143          * Resizes the rendered image. Rendering will actually take place on
 144          * the next call to paint.
 145          * @arg width the new width
 146          * @arg height the new height
 147          **/
 148         Q_INVOKABLE void resize(qreal width, qreal height);
 149
 150         /**
 151          * Resizes the rendered image. Rendering will actually take place on
 152          * the next call to paint.
 153          * @arg size the new size of the image
 154          **/
 155         Q_INVOKABLE void resize(const QSizeF &size);
 156
 157         /**
 158          * Resizes the rendered image to the natural size of the SVG.
 159          * Rendering will actually take place on the next call to paint.
 160          **/
 161         Q_INVOKABLE void resize();
 162
 163         /**
 164          * Size of a given element
 165          * @arg elementId the id of the element to check
 166          * @return the current size of a given element, given the current size of the Svg
 167          **/
 168         Q_INVOKABLE QSize elementSize(const QString &elementId) const;
 169
 170         /**
 171          * The bounding rect of a given element
 172          * @arg elementId the id of the element to check
 173          * @return the current rect of a given element, given the current size of the Svg
 174          **/
 175         Q_INVOKABLE QRectF elementRect(const QString &elementId) const;
 176
 177         /**
 178          * Check when an element exists in the loaded Svg
 179          * @arg elementId the id of the element to check
 180          * @return true if the element is defined in the Svg, otherwise false
 181          **/
 182         Q_INVOKABLE bool hasElement(const QString &elementId) const;
 183
 184         /**
 185          * Returns the element (by id) at the given point. An empty string is
 186          * returned if no element is at that point.
 187          */
 188         Q_INVOKABLE QString elementAtPoint(const QPoint &point) const;
 189
 190         /**
 191          * @return true if the SVG file exists and the document is valid,
 192          *         otherwise false. This method can be expensive as it
 193          *         causes disk access.
 194          **/
 195         Q_INVOKABLE bool isValid() const;
 196
 197        /**
 198         * Set if the svg contains a single image or multiple ones.
 199         * @arg multiple true if the svg contains multiple images
 200         */
 201         void setContainsMultipleImages(bool multiple);
 202
 203        /**
 204         * @return whether or not the svg contains multiple images or not
 205         */
 206         bool containsMultipleImages() const;
 207
 208         /**
 209          * Convenience method for setting the svg file to use for the Svg.
 210          * @arg svgFilePath the filepath including name of the svg.
 211          */
 212         void setImagePath(const QString &svgFilePath);
 213
 214         /**
 215          * Convenience method to get the svg filepath and name of svg.
 216          * @return the svg's filepath including name of the svg.
 217          */
 218         QString imagePath() const;
 219
 220     Q_SIGNALS:
 221         void repaintNeeded();
 222
 223     private:
 224         SvgPrivate *const d;
 225
 226         Q_PRIVATE_SLOT(d, void themeChanged())
 227         Q_PRIVATE_SLOT(d, void colorsChanged())
 228         Q_PRIVATE_SLOT(d, void scheduledCacheUpdate())
 229
 230         friend class SvgPrivate;
 231         friend class FrameSvgPrivate;
 232 };
 233
 234 } // Plasma namespace
 235
 236 #endif // multiple inclusion guard
 237