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

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