/usr/include/plasma/svg.h is in kdelibs5-dev 4:4.13.0-0ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 | /*
* Copyright 2006-2007 Aaron Seigo <aseigo@kde.org>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU Library General Public License as
* published by the Free Software Foundation; either version 2, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details
*
* You should have received a copy of the GNU Library General Public
* License along with this program; if not, write to the
* Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
#ifndef PLASMA_SVG_H
#define PLASMA_SVG_H
#include <QtCore/QObject>
#include <QtGui/QPixmap>
#include <plasma/plasma_export.h>
class QPainter;
class QPoint;
class QPointF;
class QRect;
class QRectF;
class QSize;
class QSizeF;
class QMatrix;
namespace Plasma
{
class FrameSvgPrivate;
class SvgPrivate;
class Theme;
/**
* @class Svg plasma/svg.h <Plasma/Svg>
*
* @short A theme aware image-centric SVG class
*
* Plasma::Svg provides a class for rendering SVG images to a QPainter in a
* convenient manner. Unless an absolute path to a file is provided, it loads
* the SVG document using Plasma::Theme. It also provides a number of internal
* optimizations to help lower the cost of painting SVGs, such as caching.
*
* @see Plasma::FrameSvg
**/
class PLASMA_EXPORT Svg : public QObject
{
Q_OBJECT
Q_ENUMS(ContentType)
Q_PROPERTY(QSize size READ size WRITE resize NOTIFY sizeChanged)
Q_PROPERTY(bool multipleImages READ containsMultipleImages WRITE setContainsMultipleImages)
Q_PROPERTY(QString imagePath READ imagePath WRITE setImagePath)
Q_PROPERTY(bool usingRenderingCache READ isUsingRenderingCache WRITE setUsingRenderingCache)
public:
/**
* Constructs an SVG object that implicitly shares and caches rendering.
*
* Unlike QSvgRenderer, which this class uses internally,
* Plasma::Svg represents an image generated from an SVG. As such, it
* has a related size and transform matrix (the latter being provided
* by the painter used to paint the image).
*
* The size is initialized to be the SVG's native size.
*
* @param parent options QObject to parent this to
*
* @related Plasma::Theme
*/
explicit Svg(QObject *parent = 0);
~Svg();
/**
* Returns a pixmap of the SVG represented by this object.
*
* The size of the pixmap will be the size of this Svg object (size())
* if containsMultipleImages is @c true; otherwise, it will be the
* size of the requested element after the whole SVG has been scaled
* to size().
*
* @param elementId the ID string of the element to render, or an empty
* string for the whole SVG (the default)
* @return a QPixmap of the rendered SVG
*/
Q_INVOKABLE QPixmap pixmap(const QString &elementID = QString());
/**
* Paints all or part of the SVG represented by this object
*
* The size of the painted area will be the size of this Svg object
* (size()) if containsMultipleImages is @c true; otherwise, it will
* be the size of the requested element after the whole SVG has been
* scaled to size().
*
* @param painter the QPainter to use
* @param point the position to start drawing; the entire svg will be
* drawn starting at this point.
* @param elementId the ID string of the element to render, or an empty
* string for the whole SVG (the default)
*/
Q_INVOKABLE void paint(QPainter *painter, const QPointF &point,
const QString &elementID = QString());
/**
* Paints all or part of the SVG represented by this object
*
* The size of the painted area will be the size of this Svg object
* (size()) if containsMultipleImages is @c true; otherwise, it will
* be the size of the requested element after the whole SVG has been
* scaled to size().
*
* @param painter the QPainter to use
* @param x the horizontal coordinate to start painting from
* @param y the vertical coordinate to start painting from
* @param elementId the ID string of the element to render, or an empty
* string for the whole SVG (the default)
*/
Q_INVOKABLE void paint(QPainter *painter, int x, int y,
const QString &elementID = QString());
/**
* Paints all or part of the SVG represented by this object
*
* @param painter the QPainter to use
* @param rect the rect to draw into; if smaller than the current size
* the drawing is starting at this point.
* @param elementId the ID string of the element to render, or an empty
* string for the whole SVG (the default)
*/
Q_INVOKABLE void paint(QPainter *painter, const QRectF &rect,
const QString &elementID = QString());
/**
* Paints all or part of the SVG represented by this object
*
* @param painter the QPainter to use
* @param x the horizontal coordinate to start painting from
* @param y the vertical coordinate to start painting from
* @param width the width of the element to draw
* @param height the height of the element do draw
* @param elementId the ID string of the element to render, or an empty
* string for the whole SVG (the default)
*/
Q_INVOKABLE void paint(QPainter *painter, int x, int y, int width,
int height, const QString &elementID = QString());
/**
* The size of the SVG.
*
* If the SVG has been resized with resize(), that size will be
* returned; otherwise, the natural size of the SVG will be returned.
*
* If containsMultipleImages is @c true, each element of the SVG
* will be rendered at this size by default.
*
* @return the current size of the SVG
**/
QSize size() const;
/**
* Resizes the rendered image.
*
* Rendering will actually take place on the next call to paint.
*
* If containsMultipleImages is @c true, each element of the SVG
* will be rendered at this size by default; otherwise, the entire
* image will be scaled to this size and each element will be
* scaled appropriately.
*
* @param width the new width
* @param height the new height
**/
Q_INVOKABLE void resize(qreal width, qreal height);
/**
* Resizes the rendered image.
*
* Rendering will actually take place on the next call to paint.
*
* If containsMultipleImages is @c true, each element of the SVG
* will be rendered at this size by default; otherwise, the entire
* image will be scaled to this size and each element will be
* scaled appropriately.
*
* @param size the new size of the image
**/
Q_INVOKABLE void resize(const QSizeF &size);
/**
* Resizes the rendered image to the natural size of the SVG.
*
* Rendering will actually take place on the next call to paint.
**/
Q_INVOKABLE void resize();
/**
* Find the size of a given element.
*
* This is the size of the element with ID @p elementId after the SVG
* has been scaled (see resize()). Note that this is unaffected by
* the containsMultipleImages property.
*
* @param elementId the id of the element to check
* @return the size of a given element, given the current size of the SVG
**/
Q_INVOKABLE QSize elementSize(const QString &elementId) const;
/**
* The bounding rect of a given element.
*
* This is the bounding rect of the element with ID @p elementId after
* the SVG has been scaled (see resize()). Note that this is
* unaffected by the containsMultipleImages property.
*
* @param elementId the id of the element to check
* @return the current rect of a given element, given the current size of the SVG
**/
Q_INVOKABLE QRectF elementRect(const QString &elementId) const;
/**
* Check whether an element exists in the loaded SVG.
*
* @param elementId the id of the element to check for
* @return @c true if the element is defined in the SVG, otherwise @c false
**/
Q_INVOKABLE bool hasElement(const QString &elementId) const;
/**
* Returns the element (by id) at the given point.
*
* An empty string is returned if there no element is at @p point.
*
* NOTE: not implemented! This will currently return an empty string!
*
* @param point a point in SVG co-ordinates
* @return an empty string
*/
Q_INVOKABLE QString elementAtPoint(const QPoint &point) const;
/**
* Check whether this object is backed by a valid SVG file.
*
* This method can be expensive as it causes disk access.
*
* @return @c true if the SVG file exists and the document is valid,
* otherwise @c false.
**/
Q_INVOKABLE bool isValid() const;
/**
* Set whether the SVG contains a single image or multiple ones.
*
* If this is set to @c true, the SVG will be treated as a
* collection of related images, rather than a consistent
* drawing.
*
* In particular, when individual elements are rendered, this
* affects whether the elements are resized to size() by default.
* See paint() and pixmap().
*
* @param multiple true if the svg contains multiple images
*/
void setContainsMultipleImages(bool multiple);
/**
* Whether the SVG contains multiple images.
*
* If this is @c true, the SVG will be treated as a
* collection of related images, rather than a consistent
* drawing.
*
* @return @c true if the SVG will be treated as containing
* multiple images, @c false if it will be treated
* as a coherent image.
*/
bool containsMultipleImages() const;
/**
* Set the SVG file to render.
*
* Relative paths are looked for in the current Plasma theme,
* and should not include the file extension (.svg and .svgz
* files will be searched for). See Theme::imagePath().
*
* If the parent object of this Svg is a Plasma::Applet,
* relative paths will be searched for in the applet's package
* first.
*
* @param svgFilePath either an absolute path to an SVG file, or
* an image name
*/
void setImagePath(const QString &svgFilePath);
/**
* The SVG file to render.
*
* If this SVG is themed, this will be a relative path, and will not
* include a file extension.
*
* @return either an absolute path to an SVG file, or an image name
* @see Theme::imagePath()
*/
QString imagePath() const;
/**
* Sets whether or not to cache the results of rendering to pixmaps.
*
* If the SVG is resized and re-rendered often (and does not keep using the
* same small set of pixmap dimensions), then it may be less efficient to do
* disk caching. A good example might be a progress meter that uses an Svg
* object to paint itself: the meter will be changing often enough, with
* enough unpredictability and without re-use of the previous pixmaps to
* not get a gain from caching.
*
* Most Svg objects should use the caching feature, however.
* Therefore, the default is to use the render cache.
*
* @param useCache true to cache rendered pixmaps
* @since 4.3
*/
void setUsingRenderingCache(bool useCache);
/**
* Whether the rendering cache is being used.
*
* @return @c true if the Svg object is using caching for rendering results
* @since 4.3
*/
bool isUsingRenderingCache() const;
/**
* Sets the Plasma::Theme to use with this Svg object.
*
* By default, Svg objects use Plasma::Theme::default().
*
* This determines how relative image paths are interpreted.
*
* @param theme the theme object to use
* @since 4.3
*/
void setTheme(Plasma::Theme *theme);
/**
* The Plasma::Theme used by this Svg object.
*
* This determines how relative image paths are interpreted.
*
* @return the theme used by this Svg
*/
Theme *theme() const;
Q_SIGNALS:
/**
* Emitted whenever the SVG data has changed in such a way that a repaint is required.
* Any usage of an Svg object that does the painting itself must connect to this signal
* and respond by updating the painting. Note that connected to Theme::themeChanged is
* incorrect in such a use case as the Svg itself may not be updated yet nor may theme
* change be the only case when a repaint is needed. Also note that classes or QML code
* which take Svg objects as parameters for their own painting all respond to this signal
* so that in those cases manually responding to the signal is unnecessary; ONLY when
* direct, manual painting with an Svg object is done in application code is this signal
* used.
*/
void repaintNeeded();
/**
* Emitted whenever the size of the Svg is changed. @see resize()
*/
void sizeChanged();
private:
SvgPrivate *const d;
Q_PRIVATE_SLOT(d, void themeChanged())
Q_PRIVATE_SLOT(d, void colorsChanged())
friend class SvgPrivate;
friend class FrameSvgPrivate;
friend class FrameSvg;
};
} // Plasma namespace
#endif // multiple inclusion guard
|