plasma/framesvg.h

   1 /*
   2  *   Copyright 2008 by Aaron Seigo <aseigo@kde.org>
   3  *   Copyright 2008 Marco Martin <notmart@gmail.com>
   4  *
   5  *   This program is free software; you can redistribute it and/or modify
   6  *   it under the terms of the GNU Library General Public License as
   7  *   published by the Free Software Foundation; either version 2, or
   8  *   (at your option) any later version.
   9  *
  10  *   This program 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
  13  *   GNU General Public License for more details
  14  *
  15  *   You should have received a copy of the GNU Library General Public
  16  *   License along with this program; if not, write to the
  17  *   Free Software Foundation, Inc.,
  18  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  19  */
  20
  21 #ifndef PLASMA_FRAMESVG_H
  22 #define PLASMA_FRAMESVG_H
  23
  24 #include <QtCore/QObject>
  25 #include <QtGui/QPixmap>
  26
  27 #include <plasma/plasma_export.h>
  28
  29 #include <plasma/plasma.h>
  30 #include <plasma/svg.h>
  31
  32 class QPainter;
  33 class QPoint;
  34 class QPointF;
  35 class QRect;
  36 class QRectF;
  37 class QSize;
  38 class QSizeF;
  39 class QMatrix;
  40
  41 namespace Plasma
  42 {
  43
  44 class FrameSvgPrivate;
  45
  46 /**
  47  * @class FrameSvg plasma/framesvg.h <Plasma/FrameSvg>
  48  *
  49  * @short Provides an SVG with borders.
  50  *
  51  * When using SVG images for a background of an object that may change
  52  * its aspect ratio, such as a dialog, simply scaling a single image
  53  * may not be enough.
  54  *
  55  * FrameSvg allows SVGs to provide several elements for borders as well
  56  * as a central element, each of which are scaled individually.  These
  57  * elements should be named
  58  *
  59  *  - @c center  - the central element, which will be scaled in both directions
  60  *  - @c top     - the top border; the height is fixed, but it will be scaled
  61  *                 horizontally to the same width as @c center
  62  *  - @c bottom  - the bottom border; scaled in the same way as @c top
  63  *  - @c left    - the left border; the width is fixed, but it will be scaled
  64  *                 vertically to the same height as @c center
  65  *  - @c right   - the right border; scaled in the same way as @c left
  66  *  - @c topleft - fixed size; must be the same height as @c top and the same
  67  *                 width as @c left
  68  *  - @c bottomleft, @c topright, @c bottomright - similar to @c topleft
  69  *
  70  * @c center must exist, but all the others are optional.  @c topleft and
  71  * @c topright will be ignored if @c top does not exist, and similarly for
  72  * @c bottomleft and @c bottomright.
  73  *
  74  * @see Plamsa::Svg
  75  **/
  76 class PLASMA_EXPORT FrameSvg : public Svg
  77 {
  78     Q_OBJECT
  79
  80     friend class Applet;
  81
  82     public:
  83         /**
  84          * These flags represents what borders should be drawn
  85          */
  86         enum EnabledBorder {
  87             NoBorder = 0,
  88             TopBorder = 1,
  89             BottomBorder = 2,
  90             LeftBorder = 4,
  91             RightBorder = 8,
  92             AllBorders = TopBorder | BottomBorder | LeftBorder | RightBorder
  93         };
  94         Q_DECLARE_FLAGS(EnabledBorders, EnabledBorder)
  95
  96         /**
  97          * Constructs a new FrameSvg that paints the proper named subelements
  98          * as borders. It may also be used as a regular Plasma::Svg object
  99          * for direct access to elements in the Svg.
 100          *
 101          * @arg parent options QObject to parent this to
 102          *
 103          * @related Plasma::Theme
 104          */
 105         explicit FrameSvg(QObject *parent = 0);
 106         ~FrameSvg();
 107
 108         /**
 109          * Loads a new Svg
 110          * @arg imagePath the new file
 111          */
 112         Q_INVOKABLE void setImagePath(const QString &path);
 113
 114         /**
 115          * Sets what borders should be painted
 116          * @arg flags borders we want to paint
 117          */
 118         Q_INVOKABLE void setEnabledBorders(const EnabledBorders borders);
 119
 120         /**
 121          * Convenience method to get the enabled borders
 122          * @return what borders are painted
 123          */
 124         Q_INVOKABLE EnabledBorders enabledBorders() const;
 125
 126         /**
 127          * Resize the frame maintaining the same border size
 128          * @arg size the new size of the frame
 129          */
 130         Q_INVOKABLE void resizeFrame(const QSizeF &size);
 131
 132         /**
 133          * @returns the size of the frame
 134          */
 135         Q_INVOKABLE QSizeF frameSize() const;
 136
 137         /**
 138          * Returns the margin size given the margin edge we want
 139          * @arg edge the margin edge we want, top, bottom, left or right
 140          * @return the margin size
 141          */
 142         Q_INVOKABLE qreal marginSize(const Plasma::MarginEdge edge) const;
 143
 144         /**
 145          * Convenience method that extracts the size of the four margins
 146          * in the four output parameters
 147          * @arg left left margin size
 148          * @arg top top margin size
 149          * @arg right right margin size
 150          * @arg bottom bottom margin size
 151          */
 152         Q_INVOKABLE void getMargins(qreal &left, qreal &top, qreal &right, qreal &bottom) const;
 153
 154         /**
 155          * @return the rectangle of the center element, taking the margins into account.
 156          */
 157         Q_INVOKABLE QRectF contentsRect() const;
 158
 159         /**
 160          * Sets the prefix (@see setElementPrefix) to 'north', 'south', 'west' and 'east'
 161          * when the location is TopEdge, BottomEdge, LeftEdge and RightEdge,
 162          * respectively. Clears the prefix in other cases.
 163          * @arg location location
 164          */
 165         Q_INVOKABLE void setElementPrefix(Plasma::Location location);
 166
 167         /**
 168          * Sets the prefix for the SVG elements to be used for painting. For example,
 169          * if prefix is 'active', then instead of using the 'top' element of the SVG
 170          * file to paint the top border, 'active-top' element will be used. The same
 171          * goes for other SVG elements.
 172          *
 173          * If the elements with prefixes are not present, the default ones are used.
 174          * (for the sake of speed, the test is present only for the 'center' element)
 175          *
 176          * Setting the prefix manually resets the location to Floating.
 177          * If the
 178          * @arg prefix prefix for the SVG element names
 179          */
 180         Q_INVOKABLE void setElementPrefix(const QString & prefix);
 181
 182         /**
 183          * @return true if the svg has the necessary elements with the given prefix
 184          * to draw a frame
 185          * @arg prefix the given prefix we want to check if drawable
 186          */
 187         Q_INVOKABLE bool hasElementPrefix(const QString & prefix) const;
 188
 189         /**
 190          * This is an overloaded method provided for convenience equivalent to
 191          * hasElementPrefix("north"), hasElementPrefix("south")
 192          * hasElementPrefix("west") and hasElementPrefix("east")
 193          * @return true if the svg has the necessary elements with the given prefix
 194          * to draw a frame.
 195          * @arg location the given prefix we want to check if drawable
 196          */
 197         Q_INVOKABLE bool hasElementPrefix(Plasma::Location location) const;
 198
 199         /**
 200          * Returns the prefix for SVG elements of the FrameSvg
 201          * @return the prefix
 202          */
 203         Q_INVOKABLE QString prefix();
 204
 205         /**
 206          * Returns a mask that tightly contains the fully opaque areas of the svg
 207          * @return a region of opaque areas
 208          */
 209         Q_INVOKABLE QRegion mask() const;
 210
 211         /**
 212          * @return a pixmap whose alpha channel is the opacity of the frame. It may be the frame itself or a special frame with the mask- prefix
 213          */
 214         QPixmap alphaMask() const;
 215
 216        /**
 217         * Sets whether saving all the rendered prefixes in a cache or not
 218         * @arg cache if use the cache or not
 219         */
 220         Q_INVOKABLE void setCacheAllRenderedFrames(bool cache);
 221
 222        /**
 223         * @return if all the different prefixes should be kept in a cache when rendered
 224         */
 225         Q_INVOKABLE bool cacheAllRenderedFrames() const;
 226
 227        /**
 228         * Deletes the internal cache freeing memory: use this if you want to switch the rendered
 229         * element and you don't plan to switch back to the previous one for a long time and you
 230         * used setUseCache(true)
 231         */
 232         Q_INVOKABLE void clearCache();
 233
 234        /**
 235          * Returns a pixmap of the SVG represented by this object.
 236          *
 237          * @arg elelementId the ID string of the element to render, or an empty
 238          *                  string for the whole SVG (the default)
 239          * @return a QPixmap of the rendered SVG
 240          */
 241         Q_INVOKABLE QPixmap framePixmap();
 242
 243         /**
 244          * Paints the loaded SVG with the elements that represents the border
 245          * @arg painter the QPainter to use
 246          * @arg target the target rectangle on the paint device
 247          * @arg source the portion rectangle of the source image
 248          */
 249         Q_INVOKABLE void paintFrame(QPainter *painter, const QRectF &target,
 250                                     const QRectF &source = QRectF());
 251
 252         /**
 253          * Paints the loaded SVG with the elements that represents the border
 254          * This is an overloaded member provided for convenience
 255          * @arg painter the QPainter to use
 256          * @arg pos where to paint the svg
 257          */
 258         Q_INVOKABLE void paintFrame(QPainter *painter, const QPointF &pos = QPointF(0, 0));
 259
 260     private:
 261         FrameSvgPrivate *const d;
 262
 263         Q_PRIVATE_SLOT(d, void updateSizes())
 264         Q_PRIVATE_SLOT(d, void updateNeeded())
 265         Q_PRIVATE_SLOT(d, void scheduledCacheUpdate())
 266 };
 267
 268 } // Plasma namespace
 269
 270 Q_DECLARE_OPERATORS_FOR_FLAGS(Plasma::FrameSvg::EnabledBorders)
 271
 272 #endif // multiple inclusion guard