File indexing completed on 2023-10-01 04:11:46

 /*
     SPDX-FileCopyrightText: 2006-2007 Aaron Seigo <aseigo@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #ifndef PLASMA_SVG_H
 #define PLASMA_SVG_H
 
 #include <QObject>
 #include <QPixmap>
 
 #include <plasma/plasma_export.h>
 #include <plasma/theme.h>
 
 class QPainter;
 class QPoint;
 class QPointF;
 class QRect;
 class QRectF;
 class QSize;
 class QSizeF;
 class QMatrix;
 
 namespace Plasma
 {
 class FrameSvgPrivate;
 class SvgPrivate;
 
 /**
  * @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_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 NOTIFY imagePathChanged)
     Q_PROPERTY(bool usingRenderingCache READ isUsingRenderingCache WRITE setUsingRenderingCache)
     Q_PROPERTY(bool fromCurrentTheme READ fromCurrentTheme NOTIFY fromCurrentThemeChanged)
     Q_PROPERTY(Plasma::Theme::ColorGroup colorGroup READ colorGroup WRITE setColorGroup NOTIFY colorGroupChanged)
     Q_PROPERTY(Plasma::Svg::Status status READ status WRITE setStatus NOTIFY statusChanged)
 
 public:
     enum Status {
         Normal = 0,
         Selected,
         Inactive,
     };
     Q_ENUM(Status)
 
     /**
      * 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 = nullptr);
     ~Svg() override;
 
     /**
      * Set the device pixel ratio for the Svg. This is the ratio between
      * image pixels and device-independent pixels.
      * The Svg will produce pixmaps scaled by devicePixelRatio, but all the sizes and element
      * rects will not be altered.
      * The default value is 1.0 and the scale will be done rounded to the floor integer
      * Setting it to something more, will make all the elements of this svg appear bigger.
      */
     void setDevicePixelRatio(qreal ratio);
 
     /**
      * @return the device pixel ratio for this Svg.
      */
     qreal devicePixelRatio();
 
     /**
      * Setting a scale factor greater than one it will result in final images scaled by it.
      * Unlike devicePixelRatio, every size and element rect will be scaled accordingly.
      * @return how much to scale the rendered image.
      */
     qreal scaleFactor() const;
 
     /**
      * Setting a scale factor greater than one it will result in final images scaled by it.
      * Unlike devicePixelRatio, every size and element rect will be scaled accordingly.
      * The default value is 1.0 and the scale will be done rounded to the floor integer.
      * @param how much to scale the Svg
      */
     void setScaleFactor(qreal factor);
 
     /**
      * Set a color group for the Svg.
      * if the Svg uses stylesheets and has elements
      * that are either TextColor or BackgroundColor class,
      * make them use ButtonTextColor/ButtonBackgroundColor
      * or ViewTextColor/ViewBackgroundColor
      */
     void setColorGroup(Plasma::Theme::ColorGroup group);
 
     /**
      * @return the color group for this Svg
      */
     Plasma::Theme::ColorGroup colorGroup() const;
 
     /**
      * 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());
 
     /**
      * Returns an image of the SVG represented by this object.
      *
      * The size of the image 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 QImage image(const QSize &size, 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;
 
     QSize elementSize(QStringView 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;
 
     QRectF elementRect(QStringView 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;
 
     bool hasElement(QStringView elementId) 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
      */
     virtual 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;
 
     /**
      * Whether the current theme has this Svg, without any fallback
      * to the default theme involved
      *
      * @return true if the svg is loaded from the current theme
      * @see Theme::currentThemeHasImage
      */
     bool fromCurrentTheme() const;
 
     /**
      * Sets whether the Svg uses the global system theme for its colors or
      * the Plasma theme. Default is False.
      *
      * @since 5.16
      */
     void setUseSystemColors(bool system);
 
     /**
      * @returns True if colors from the system theme are used.
      *           Default is False
      * @since 5.16
      */
     bool useSystemColors() 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;
 
     /**
      * Sets the image in a selected status.
      * Svgs can be colored with system color themes, if the status is selected,
      * the TextColor will become HighlightedText color and BackgroundColor
      * will become HighlightColor, making the svg graphics (for instance an icon)
      * will look correct together selected text
      * Supported statuses as of 5.23 are Normal and Selected
      * @since 5.23
      */
     void setStatus(Svg::Status status);
 
     /**
      * @return the status of the Svg
      * @since 5.23
      */
     Svg::Status status() 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();
 
     /**
      * Emitted whenever the image path of the Svg is changed.
      */
     void imagePathChanged();
 
     /**
      * Emitted whenever the color hint has changed.
      */
     void colorHintChanged();
 
     /**
      * Emitted whenever the color group has changed.
      */
     void colorGroupChanged();
 
     /**
      * Emitted when fromCurrentTheme() value has changed
      */
     void fromCurrentThemeChanged(bool fromCurrentTheme);
 
     /**
      * Emitted when the status changes
      * @since 5.23
      */
     void statusChanged(Plasma::Svg::Status status);
 
 private:
     SvgPrivate *const d;
     bool eventFilter(QObject *watched, QEvent *event) override;
 
     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