1/*
2 SPDX-FileCopyrightText: 2006-2007 Aaron Seigo <aseigo@kde.org>
3 SPDX-FileCopyrightText: 2013 Marco Martin <mart@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KSVG_IMAGESET_H
9#define KSVG_IMAGESET_H
10
11#include <QGuiApplication>
12#include <QObject>
13
14#include <KSharedConfig>
15#include <ksvg/ksvg_export.h>
16
17class KPluginMetaData;
18
19namespace KSvg
20{
21class ImageSetPrivate;
22class SvgPrivate;
23
24// TODO: move in the plasma part the watching and regeneration of icon themes
25
26/*!
27 * \class KSvg::ImageSet
28 * \inheaderfile KSvg/ImageSet
29 * \inmodule KSvg
30 *
31 * \brief Interface to the Svg image set.
32 *
33 * KSvg::ImageSet provides access to a common and standardized set of graphic
34 * elements stored in SVG format. This allows artists to create single packages
35 * of SVGs that will affect the look and feel of all workspace components.
36 *
37 * KSvg::Svg uses KSvg::ImageSet internally to locate and load the appropriate
38 * SVG data. Alternatively, KSvg::ImageSet can be used directly to retrieve
39 * file system paths to SVGs by name.
40 */
41class KSVG_EXPORT ImageSet : public QObject
42{
43 Q_OBJECT
44
45 /*!
46 * \property KSvg::ImageSet::imageSetName
47 */
48 Q_PROPERTY(QString imageSetName READ imageSetName WRITE setImageSetName NOTIFY imageSetChanged)
49
50 /*!
51 * \property KSvg::ImageSet::basePath
52 */
53 Q_PROPERTY(QString basePath READ basePath WRITE setBasePath NOTIFY imageSetChanged)
54
55 /*!
56 * \property KSvg::ImageSet::useGlobalSettings
57 */
58 Q_PROPERTY(bool useGlobalSettings READ useGlobalSettings NOTIFY imageSetChanged)
59
60public:
61 /*!
62 * Default constructor.
63 *
64 * \a parent the parent object
65 */
66 explicit ImageSet(QObject *parent = nullptr);
67
68 /*!
69 * \brief This method constructs a theme which will be a custom theme
70 * instance of imageSetName.
71 *
72 * \a imageSetName the name of the theme to create
73 * \a basePath base path for the theme to look for svgs. if empty, the default will be used.
74 * \a parent the parent object
75 */
76 explicit ImageSet(const QString &imageSetName, const QString &basePath = {}, QObject *parent = nullptr);
77
78 ~ImageSet() override;
79
80 /*!
81 * \brief This method sets a base path for the theme to look for SVGs.
82 *
83 * It can be a path relative to QStandardPaths::GenericDataLocation or an
84 * absolute path.
85 *
86 * \a basePath the base path
87 */
88 void setBasePath(const QString &basePath);
89
90 /*!
91 * \brief This method returns the base path of the theme where the SVGs will
92 * be looked for.
93 */
94 QString basePath() const;
95
96 /*!
97 * \brief This method sets the file selectors.
98 *
99 * The theme can have different svgs with the same name for different
100 * situations and platforms. The Plasma desktop for instance uses "opaque"
101 * or "translucent" based on presence of compositing and KWin blur effects.
102 * Other uses may be platform, like android-specific graphics.
103 *
104 * \a selectors selectors in order of preference
105 */
106 void setSelectors(const QStringList &selectors);
107
108 /*!
109 * \brief This method returns the current selectors in order of preference.
110 */
111 QStringList selectors() const;
112
113 /*!
114 * \brief This method sets the current theme.
115 */
116 void setImageSetName(const QString &imageSetName);
117
118 /*!
119 * \brief This method returns the name of the current theme.
120 */
121 QString imageSetName() const;
122
123 /*!
124 * \brief This method returns the path for an SVG image in the current
125 * theme.
126 *
127 * \a name the name of the file in the theme directory (without the
128 * ".svg" part or a leading slash).
129 *
130 * Returns the full path to the requested file for the current theme
131 */
132 QString imagePath(const QString &name) const;
133
134 /*!
135 * \brief This method returns the path for a generic file in the current
136 * theme.
137 *
138 * The theme can also ship any generic file, such as configuration files.
139 *
140 * \a name the name of the file in the theme directory (without a
141 * leading slash)
142 *
143 * Returns the full path to the requested file for the current theme
144 */
145 QString filePath(const QString &name) const;
146
147 /*!
148 * \brief This method checks whether this theme contains an image with the
149 * given name.
150 *
151 * \a name the name of the file in the theme directory (without the
152 * ".svg" part or a leading slash)
153 *
154 * Returns true if the image exists for this theme
155 */
156 bool currentImageSetHasImage(const QString &name) const;
157
158 /*!
159 * \brief This method sets whether the theme should follow the global
160 * settings or use application-specific settings.
161 *
162 * \a useGlobal pass in true to follow the global settings
163 */
164 void setUseGlobalSettings(bool useGlobal);
165
166 /*!
167 * \brief This method returns whether the global settings are followed.
168 *
169 * If application-specific settings are being used, it returns \c false.
170 */
171 bool useGlobalSettings() const;
172
173 /*!
174 * \brief This method sets the maximum size of the cache (in kilobytes).
175 *
176 * If cache gets bigger than the limit, then some entries are removed.
177 * Setting cache limit to 0 disables automatic cache size limiting.
178 *
179 * Note that the cleanup might not be done immediately, so the cache might
180 * temporarily (for a few seconds) grow bigger than the limit.
181 **/
182 void setCacheLimit(int kbytes);
183
184 /*!
185 * \brief This method returns the plugin metadata for this theme.
186 *
187 * Metadata contains information such as name, description, author, website,
188 * and url.
189 */
190 KPluginMetaData metadata() const;
191
192Q_SIGNALS:
193 /*!
194 * \brief This signal is emitted when the user makes changes to the theme.
195 *
196 * Rendered images, colors, etc. should be updated at this point. However,
197 * SVGs should *not* be repainted in response to this signal; connect to
198 * Svg::repaintNeeded() instead for that, as SVG objects need repainting not
199 * only when imageSetChanged() is emitted; moreover SVG objects connect to
200 * and respond appropriately to imageSetChanged() internally, emitting
201 * Svg::repaintNeeded() at an appropriate time.
202 */
203 void imageSetChanged(const QString &basePath);
204
205 /*!
206 * \brief This signal is emitted when the user changes the base path of the
207 * image set.
208 */
209 void basePathChanged(const QString &basePath);
210
211private:
212 friend class SvgPrivate;
213 friend class Svg;
214 friend class FrameSvg;
215 friend class FrameSvgPrivate;
216 friend class ImageSetPrivate;
217 ImageSetPrivate *d;
218};
219
220} // KSvg namespace
221
222#endif // multiple inclusion guard
223

source code of ksvg/src/ksvg/imageset.h