1 | /* |
2 | * Copyright 2006-2007 Aaron Seigo <aseigo@kde.org> |
3 | * |
4 | * This program is free software; you can redistribute it and/or modify |
5 | * it under the terms of the GNU Library General Public License as |
6 | * published by the Free Software Foundation; either version 2, or |
7 | * (at your option) any later version. |
8 | * |
9 | * This program is distributed in the hope that it will be useful, |
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
12 | * GNU General Public License for more details |
13 | * |
14 | * You should have received a copy of the GNU Library General Public |
15 | * License along with this program; if not, write to the |
16 | * Free Software Foundation, Inc., |
17 | * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef PLASMA_THEME_H |
21 | #define PLASMA_THEME_H |
22 | |
23 | #include <QtCore/QObject> |
24 | #include <QtGui/QFont> |
25 | #include <QtGui/QFontMetrics> |
26 | |
27 | #include <kplugininfo.h> |
28 | #include <ksharedconfig.h> |
29 | |
30 | #include <plasma/plasma_export.h> |
31 | #include <plasma/packagestructure.h> |
32 | |
33 | namespace Plasma |
34 | { |
35 | |
36 | class ThemePrivate; |
37 | |
38 | /** |
39 | * @class Theme plasma/theme.h <Plasma/Theme> |
40 | * |
41 | * @short Interface to the Plasma theme |
42 | * |
43 | * Accessed via Plasma::Theme::defaultTheme() e.g: |
44 | * \code |
45 | * QString imagePath = Plasma::Theme::defaultTheme()->imagePath("widgets/clock") |
46 | * \endcode |
47 | * |
48 | * Plasma::Theme provides access to a common and standardized set of graphic |
49 | * elements stored in SVG format. This allows artists to create single packages |
50 | * of SVGs that will affect the look and feel of all workspace components. |
51 | * |
52 | * Plasma::Svg uses Plasma::Theme internally to locate and load the appropriate |
53 | * SVG data. Alternatively, Plasma::Theme can be used directly to retrieve |
54 | * file system paths to SVGs by name. |
55 | */ |
56 | class PLASMA_EXPORT Theme : public QObject |
57 | { |
58 | Q_OBJECT |
59 | Q_PROPERTY(QString themeName READ themeName) |
60 | |
61 | public: |
62 | enum ColorRole { |
63 | TextColor = 0, /**< the text color to be used by items resting on the background */ |
64 | HighlightColor = 1, /**< the text higlight color to be used by items resting |
65 | on the background */ |
66 | BackgroundColor = 2, /**< the default background color */ |
67 | ButtonTextColor = 4, /** text color for buttons */ |
68 | ButtonBackgroundColor = 8, /** background color for buttons*/ |
69 | LinkColor = 16, /** color for clickable links */ |
70 | VisitedLinkColor = 32, /** color visited clickable links */ |
71 | ButtonHoverColor = 64, /** color for hover effect on buttons */ |
72 | ButtonFocusColor = 128, /** color for focus effect on buttons */ |
73 | ViewTextColor = 256, /** text color for views */ |
74 | ViewBackgroundColor = 512, /** background color for views */ |
75 | ViewHoverColor = 1024, /** color for hover effect on view */ |
76 | ViewFocusColor = 2048 /** color for focus effect on view */ |
77 | }; |
78 | |
79 | enum FontRole { |
80 | DefaultFont = 0, /**< The standard text font */ |
81 | DesktopFont, /**< The standard text font */ |
82 | SmallestFont /**< The smallest readable font */ |
83 | }; |
84 | |
85 | /** |
86 | * Singleton pattern accessor |
87 | **/ |
88 | static Theme *defaultTheme(); |
89 | |
90 | /** |
91 | * Default constructor. Usually you want to use the singleton instead. |
92 | * @see defaultTheme |
93 | * @param parent the parent object |
94 | */ |
95 | explicit Theme(QObject *parent = 0); |
96 | |
97 | /** |
98 | * Construct a theme. Usually you want to use the singleton instead. |
99 | * @see defaultTheme |
100 | * @param themeName the name of the theme to create |
101 | * @param parent the parent object |
102 | * @since 4.3 |
103 | */ |
104 | explicit Theme(const QString &themeName, QObject *parent = 0); |
105 | |
106 | ~Theme(); |
107 | |
108 | /** |
109 | * @return a package structure representing a Theme |
110 | */ |
111 | static PackageStructure::Ptr packageStructure(); |
112 | |
113 | /** |
114 | * @return a list of all known themes |
115 | * @since 4.3 |
116 | */ |
117 | static KPluginInfo::List listThemeInfo(); |
118 | |
119 | /** |
120 | * Sets the current theme being used. |
121 | */ |
122 | void setThemeName(const QString &themeName); |
123 | |
124 | /** |
125 | * @return the name of the theme. |
126 | */ |
127 | QString themeName() const; |
128 | |
129 | /** |
130 | * Retrieve the path for an SVG image in the current theme. |
131 | * |
132 | * @param name the name of the file in the theme directory (without the |
133 | * ".svg" part or a leading slash) |
134 | * @return the full path to the requested file for the current theme |
135 | */ |
136 | Q_INVOKABLE QString imagePath(const QString &name) const; |
137 | |
138 | /** |
139 | * Retrieves the path for the script file that contains a given |
140 | * Javascript animation. |
141 | * @param the name of the animation |
142 | * @return the full path to the script file, or an emptry string on failure |
143 | * @since 4.5 |
144 | */ |
145 | Q_INVOKABLE QString animationPath(const QString &name) const; |
146 | |
147 | /** |
148 | * Retrieves the default wallpaper associated with this theme. |
149 | * |
150 | * @param size the target height and width of the wallpaper; if an invalid size |
151 | * is passed in, then a default size will be provided instead. |
152 | * @return the full path to the wallpaper image |
153 | */ |
154 | Q_INVOKABLE QString wallpaperPath(const QSize &size = QSize()) const; |
155 | |
156 | /** |
157 | * Checks if this theme has an image named in a certain way |
158 | * |
159 | * @param name the name of the file in the theme directory (without the |
160 | * ".svg" part or a leading slash) |
161 | * @return true if the image exists for this theme |
162 | */ |
163 | Q_INVOKABLE bool currentThemeHasImage(const QString &name) const; |
164 | |
165 | /** |
166 | * Returns the color scheme configurationthat goes along this theme. |
167 | * This can be used with KStatefulBrush and KColorScheme to determine |
168 | * the proper colours to use along with the visual elements in this theme. |
169 | */ |
170 | Q_INVOKABLE KSharedConfigPtr colorScheme() const; |
171 | |
172 | /** |
173 | * Returns the text color to be used by items resting on the background |
174 | * |
175 | * @param role which role (usage pattern) to get the color for |
176 | */ |
177 | Q_INVOKABLE QColor color(ColorRole role) const; |
178 | |
179 | /** |
180 | * Sets the default font to be used with themed items. Defaults to |
181 | * the application wide default font. |
182 | * |
183 | * @param font the new font |
184 | * @param role which role (usage pattern) to set the font for |
185 | */ |
186 | Q_INVOKABLE void setFont(const QFont &font, FontRole role = DefaultFont); |
187 | |
188 | /** |
189 | * Returns the font to be used by themed items |
190 | * |
191 | * @param role which role (usage pattern) to get the font for |
192 | */ |
193 | Q_INVOKABLE QFont font(FontRole role) const; |
194 | |
195 | /** |
196 | * @return the font metrics for the font to be used by themed items |
197 | */ |
198 | Q_INVOKABLE QFontMetrics fontMetrics() const; |
199 | |
200 | /** |
201 | * @return true if the window manager effects (e.g. translucency, compositing) is active or not |
202 | */ |
203 | Q_INVOKABLE bool windowTranslucencyEnabled() const; |
204 | |
205 | /** |
206 | * Tells the theme whether to follow the global settings or use application |
207 | * specific settings |
208 | * |
209 | * @param useGlobal pass in true to follow the global settings |
210 | */ |
211 | void setUseGlobalSettings(bool useGlobal); |
212 | |
213 | /** |
214 | * @return true if the global settings are followed, false if application |
215 | * specific settings are used. |
216 | */ |
217 | bool useGlobalSettings() const; |
218 | |
219 | /** |
220 | * @return true if the native widget styles should be used instead of themed |
221 | * widgets. Defaults is false. |
222 | */ |
223 | bool useNativeWidgetStyle() const; |
224 | |
225 | /** |
226 | * Provides a Plasma::Theme-themed stylesheet for hybrid (web / native Plasma) widgets. |
227 | * |
228 | * You can use this method to retrieve a basic default stylesheet, or to theme your |
229 | * custom stylesheet you use for example in Plasma::WebView. The QString you can pass |
230 | * into this method does not have to be a valid stylesheet, in fact you can use this |
231 | * method to replace color placeholders with the theme's color in any QString. |
232 | * |
233 | * In order to use this method with a custom stylesheet, just put for example %textcolor |
234 | * in your QString and it will be replaced with the theme's text (or foreground) color. |
235 | * |
236 | * Just like in many other methods for retrieving theme information, do not forget to |
237 | * update your stylesheet upon the themeChanged() signal. |
238 | * |
239 | * The following tags will be replaced by corresponding colors from Plasma::Theme: |
240 | * |
241 | * %textcolor |
242 | * %backgroundcolor |
243 | * %buttonbackgroundcolor |
244 | * |
245 | * %link |
246 | * %activatedlink |
247 | * %hoveredlink |
248 | * %visitedlink |
249 | * |
250 | * %fontfamily |
251 | * %fontsize |
252 | * %smallfontsize |
253 | * |
254 | * @param css a stylesheet to theme, leave empty for a default stylesheet containing |
255 | * theming for some commonly used elements, body text and links, for example. |
256 | * |
257 | * @return a piece of CSS that sets the most commonly used style elements to a theme |
258 | * matching Plasma::Theme. |
259 | * |
260 | * @since 4.5 |
261 | */ |
262 | Q_INVOKABLE QString styleSheet(const QString &css = QString()) const; |
263 | |
264 | |
265 | /** |
266 | * Tries to load pixmap with the specified key from cache. |
267 | * |
268 | * @param key the name to use in the cache for this image |
269 | * @param pix the pixmap object to populate with the resulting data if found |
270 | * |
271 | * @return true when pixmap was found and loaded from cache, false otherwise |
272 | **/ |
273 | bool findInCache(const QString &key, QPixmap &pix); |
274 | |
275 | /** |
276 | * This is an overloaded member provided to check with file timestamp |
277 | * where cache is still valid. |
278 | * |
279 | * @param key the name to use in the cache for this image |
280 | * @param pix the pixmap object to populate with the resulting data if found |
281 | * @param lastModified if non-zero, the time stamp is also checked on the file, |
282 | * and must be newer than the timestamp to be loaded |
283 | * |
284 | * @return true when pixmap was found and loaded from cache, false otherwise |
285 | * @since 4.3 |
286 | **/ |
287 | bool findInCache(const QString &key, QPixmap &pix, unsigned int lastModified); |
288 | |
289 | /** |
290 | * Insert specified pixmap into the cache. |
291 | * If the cache already contains pixmap with the specified key then it is |
292 | * overwritten. |
293 | * |
294 | * @param key the name to use in the cache for this pixmap |
295 | * @param pix the pixmap data to store in the cache |
296 | **/ |
297 | void insertIntoCache(const QString& key, const QPixmap& pix); |
298 | |
299 | /** |
300 | * Insert specified pixmap into the cache. |
301 | * If the cache already contains pixmap with the specified key then it is |
302 | * overwritten. |
303 | * The actual insert is delayed for optimization reasons and the id |
304 | * parameter is used to discard repeated inserts in the delay time, useful |
305 | * when for instance the graphics to inser comes from a quickly resizing |
306 | * object: the frames between the start and destination sizes aren't |
307 | * useful in the cache and just cause overhead. |
308 | * |
309 | * @param key the name to use in the cache for this pixmap |
310 | * @param pix the pixmap data to store in the cache |
311 | * @param id a name that identifies the caller class of this function in an unique fashion. |
312 | * This is needed to limit disk writes of the cache. |
313 | * If an image with the same id changes quickly, |
314 | * only the last size where insertIntoCache was called is actually stored on disk |
315 | * @since 4.3 |
316 | **/ |
317 | void insertIntoCache(const QString& key, const QPixmap& pix, const QString& id); |
318 | |
319 | /** |
320 | * Sets the maximum size of the cache (in kilobytes). If cache gets bigger |
321 | * the limit then some entries are removed |
322 | * Setting cache limit to 0 disables automatic cache size limiting. |
323 | * |
324 | * Note that the cleanup might not be done immediately, so the cache might |
325 | * temporarily (for a few seconds) grow bigger than the limit. |
326 | **/ |
327 | void setCacheLimit(int kbytes); |
328 | |
329 | /** |
330 | * Tries to load the rect of a sub element from a disk cache |
331 | * |
332 | * @param image path of the image we want to check |
333 | * @param element sub element we want to retrieve |
334 | * @param rect output parameter of the element rect found in cache |
335 | * if not found or if we are sure it doesn't exist it will be QRect() |
336 | * @return true if the element was found in cache or if we are sure the element doesn't exist |
337 | **/ |
338 | bool findInRectsCache(const QString &image, const QString &element, QRectF &rect) const; |
339 | |
340 | /** |
341 | * Returns a list of all keys of cached rects for the given image. |
342 | * |
343 | * @param image path of the image for which the keys should be returned |
344 | * |
345 | * @return a QStringList whose elements are the entry keys in the rects cache |
346 | * |
347 | * @since 4.6 |
348 | */ |
349 | QStringList listCachedRectKeys(const QString &image) const; |
350 | |
351 | /** |
352 | * Inserts a rectangle of a sub element of an image into a disk cache |
353 | * |
354 | * @param image path of the image we want to insert information |
355 | * @param element sub element we want insert the rect |
356 | * @param rect element rectangle |
357 | **/ |
358 | void insertIntoRectsCache(const QString& image, const QString &element, const QRectF &rect); |
359 | |
360 | /** |
361 | * Discards all the information about a given image from the rectangle disk cache |
362 | * |
363 | * @param image the path to the image the cache is assoiated with |
364 | **/ |
365 | void invalidateRectsCache(const QString &image); |
366 | |
367 | /** |
368 | * Frees up memory used by cached information for a given image without removing |
369 | * the permenant record of it on disk. |
370 | * @see invalidateRectsCache |
371 | * |
372 | * @param image the path to the image the cache is assoiated with |
373 | */ |
374 | void releaseRectsCache(const QString &image); |
375 | |
376 | /** |
377 | * @return the default homepage to use in conjunction with the branding svg content |
378 | * @since 4.7 |
379 | */ |
380 | KUrl homepage() const; |
381 | |
382 | /** |
383 | * @return the default tool tip delay; -1 means "no tooltips" |
384 | */ |
385 | int toolTipDelay() const; |
386 | |
387 | Q_SIGNALS: |
388 | /** |
389 | * Emitted when the user changes the theme. Stylesheet usage, colors, etc. should |
390 | * be updated at this point. However, SVGs should *not* be repainted in response |
391 | * to this signal; connect to Svg::repaintNeeded() instead for that, as Svg objects |
392 | * need repainting not only when themeChanged() is emitted; moreover Svg objects |
393 | * connect to and respond appropriately to themeChanged() internally, emitting |
394 | * Svg::repaintNeeded() at an appropriate time. |
395 | */ |
396 | void themeChanged(); |
397 | |
398 | public Q_SLOTS: |
399 | /** |
400 | * Notifies the Theme object that the theme settings have changed |
401 | * and should be read from the config file |
402 | **/ |
403 | void settingsChanged(); |
404 | |
405 | private: |
406 | friend class ThemeSingleton; |
407 | friend class ThemePrivate; |
408 | ThemePrivate *const d; |
409 | |
410 | Q_PRIVATE_SLOT(d, void compositingChanged(bool)) |
411 | Q_PRIVATE_SLOT(d, void colorsChanged()) |
412 | Q_PRIVATE_SLOT(d, void blurBehindChanged(bool blur)) |
413 | Q_PRIVATE_SLOT(d, void settingsFileChanged(const QString &)) |
414 | Q_PRIVATE_SLOT(d, void scheduledCacheUpdate()) |
415 | Q_PRIVATE_SLOT(d, void onAppExitCleanup()) |
416 | Q_PRIVATE_SLOT(d, void notifyOfChanged()) |
417 | }; |
418 | |
419 | } // Plasma namespace |
420 | |
421 | #endif // multiple inclusion guard |
422 | |
423 | |