Plasma

theme.h
1 /*
2  SPDX-FileCopyrightText: 2006-2007 Aaron Seigo <[email protected]>
3  SPDX-FileCopyrightText: 2013 Marco Martin <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef PLASMA_THEME_H
9 #define PLASMA_THEME_H
10 
11 #include <QFont>
12 #include <QGuiApplication>
13 #include <QObject>
14 
15 #include <plasma/plasma_export.h>
16 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 94)
17 #include <KPluginInfo>
18 #endif
19 #include <KSharedConfig>
20 
21 class KPluginMetaData;
22 
23 namespace Plasma
24 {
25 class ThemePrivate;
26 class SvgPrivate;
27 
28 /**
29  * @class Theme plasma/theme.h <Plasma/Theme>
30  *
31  * @short Interface to the Plasma theme
32  *
33  *
34  * Plasma::Theme provides access to a common and standardized set of graphic
35  * elements stored in SVG format. This allows artists to create single packages
36  * of SVGs that will affect the look and feel of all workspace components.
37  *
38  * Plasma::Svg uses Plasma::Theme internally to locate and load the appropriate
39  * SVG data. Alternatively, Plasma::Theme can be used directly to retrieve
40  * file system paths to SVGs by name.
41  */
42 class PLASMA_EXPORT Theme : public QObject
43 {
44  Q_OBJECT
45 
46  Q_PROPERTY(QString themeName READ themeName NOTIFY themeChanged)
47  Q_PROPERTY(bool useGlobalSettings READ useGlobalSettings NOTIFY themeChanged)
48  Q_PROPERTY(QString wallpaperPath READ wallpaperPath NOTIFY themeChanged)
49 
50  // fonts
51  Q_PROPERTY(QFont defaultFont READ defaultFont NOTIFY defaultFontChanged)
52  Q_PROPERTY(QFont smallestFont READ smallestFont NOTIFY smallestFontChanged)
53 
54  // stylesheet
55  Q_PROPERTY(QString styleSheet READ styleSheet NOTIFY themeChanged)
56 
57  Q_PROPERTY(QPalette palette READ palette NOTIFY themeChanged)
58 
59 public:
60  enum ColorRole {
61  TextColor = 0, /**< the text color to be used by items resting on the background */
62  BackgroundColor = 1, /**< the default background color */
63  HighlightColor = 2, /**< the text highlight color to be used by items resting
64  on the background */
65  HoverColor = 3, /**< color for hover effect on view */
66  FocusColor = 4, /**< color for focus effect on view */
67  LinkColor = 5, /**< color for clickable links */
68  VisitedLinkColor = 6, /**< color visited clickable links */
69  HighlightedTextColor = 7, /**< color contrasting with HighlightColor, to be used for instance with */
70  PositiveTextColor = 8, /**< color of foreground objects with a "positive message" connotation (usually green) */
71  NeutralTextColor = 9, /**< color of foreground objects with a "neutral message" connotation (usually yellow) */
72  NegativeTextColor = 10, /**< color of foreground objects with a "negative message" connotation (usually red) */
73  DisabledTextColor = 11, /**< color of disabled text @since 5.64 */
74  };
75 
76  enum ColorGroup {
77  NormalColorGroup = 0,
78  ButtonColorGroup = 1,
79  ViewColorGroup = 2,
80  ComplementaryColorGroup = 3,
81  HeaderColorGroup,
82  ToolTipColorGroup,
83  };
84  Q_ENUM(ColorGroup)
85 
86  /**
87  * Default constructor. It will be the global theme configured in plasmarc
88  * @param parent the parent object
89  */
90  explicit Theme(QObject *parent = nullptr);
91 
92  /**
93  * Construct a theme. It will be a custom theme instance of themeName.
94  * @param themeName the name of the theme to create
95  * @param parent the parent object
96  * @since 4.3
97  */
98  explicit Theme(const QString &themeName, QObject *parent = nullptr);
99 
100  ~Theme() override;
101 
102  /**
103  * Sets the current theme being used.
104  */
105  void setThemeName(const QString &themeName);
106 
107  /**
108  * @return the name of the theme.
109  */
110  QString themeName() const;
111 
112  /**
113  * Retrieve the path for an SVG image in the current theme.
114  *
115  * @param name the name of the file in the theme directory (without the
116  * ".svg" part or a leading slash)
117  * @return the full path to the requested file for the current theme
118  */
119  QString imagePath(const QString &name) const;
120 
121  /**
122  * Retrieves the default wallpaper associated with this theme.
123  *
124  * @param size the target height and width of the wallpaper; if an invalid size
125  * is passed in, then a default size will be provided instead.
126  * @return the full path to the wallpaper image
127  */
128  QString wallpaperPath(const QSize &size = QSize()) const;
129 
130  Q_INVOKABLE QString wallpaperPathForSize(int width = -1, int height = -1) const;
131 
132  /**
133  * Checks if this theme has an image named in a certain way
134  *
135  * @param name the name of the file in the theme directory (without the
136  * ".svg" part or a leading slash)
137  * @return true if the image exists for this theme
138  */
139  bool currentThemeHasImage(const QString &name) const;
140 
141  /**
142  * Returns the color scheme configurationthat goes along this theme.
143  * This can be used with KStatefulBrush and KColorScheme to determine
144  * the proper colours to use along with the visual elements in this theme.
145  */
146  KSharedConfigPtr colorScheme() const;
147 
148  /**
149  * Returns the text color to be used by items resting on the background
150  *
151  * @param role which role (usage pattern) to get the color for
152  * @param group which group we want a color of
153  */
154  QColor color(ColorRole role, ColorGroup group = NormalColorGroup) const;
155 
156  /**
157  * Tells the theme whether to follow the global settings or use application
158  * specific settings
159  *
160  * @param useGlobal pass in true to follow the global settings
161  */
162  void setUseGlobalSettings(bool useGlobal);
163 
164  /**
165  * @return true if the global settings are followed, false if application
166  * specific settings are used.
167  */
168  bool useGlobalSettings() const;
169 
170  /**
171  * Provides a Plasma::Theme-themed stylesheet for hybrid (web / native Plasma) widgets.
172  *
173  * You can use this method to retrieve a basic default stylesheet, or to theme your
174  * custom stylesheet you use for example in Plasma::WebView. The QString you can pass
175  * into this method does not have to be a valid stylesheet, in fact you can use this
176  * method to replace color placeholders with the theme's color in any QString.
177  *
178  * In order to use this method with a custom stylesheet, just put for example %textcolor
179  * in your QString and it will be replaced with the theme's text (or foreground) color.
180  *
181  * Just like in many other methods for retrieving theme information, do not forget to
182  * update your stylesheet upon the themeChanged() signal.
183  *
184  * The following tags will be replaced by corresponding colors from Plasma::Theme:
185  *
186  * %textcolor
187  * %backgroundcolor
188  * %buttonbackgroundcolor
189  *
190  * %link
191  * %activatedlink
192  * %hoveredlink
193  * %visitedlink
194  *
195  * %fontfamily
196  * %fontsize
197  * %smallfontsize
198  *
199  * @param css a stylesheet to theme, leave empty for a default stylesheet containing
200  * theming for some commonly used elements, body text and links, for example.
201  *
202  * @return a piece of CSS that sets the most commonly used style elements to a theme
203  * matching Plasma::Theme.
204  *
205  * @since 4.5
206  */
207  QString styleSheet(const QString &css = QString()) const;
208 
209  /**
210  * Returns a QPalette with the colors set as defined by the theme.
211  * @since 5.68
212  */
213  QPalette palette() const;
214 
215  /**
216  * This is an overloaded member provided to check with file timestamp
217  * where cache is still valid.
218  *
219  * @param key the name to use in the cache for this image
220  * @param pix the pixmap object to populate with the resulting data if found
221  * @param lastModified if non-zero, the time stamp is also checked on the file,
222  * and must be newer than the timestamp to be loaded
223  *
224  * @note Since KF 5.75, a lastModified value of 0 is deprecated. If used, it
225  * will now always return false. Use a proper file timestamp instead
226  * so modification can be properly tracked.
227  *
228  * @return true when pixmap was found and loaded from cache, false otherwise
229  * @since 4.3
230  **/
231  bool findInCache(const QString &key, QPixmap &pix, unsigned int lastModified = 0);
232 
233  /**
234  * Insert specified pixmap into the cache.
235  * If the cache already contains pixmap with the specified key then it is
236  * overwritten.
237  *
238  * @param key the name to use in the cache for this pixmap
239  * @param pix the pixmap data to store in the cache
240  **/
241  void insertIntoCache(const QString &key, const QPixmap &pix);
242 
243  /**
244  * Insert specified pixmap into the cache.
245  * If the cache already contains pixmap with the specified key then it is
246  * overwritten.
247  * The actual insert is delayed for optimization reasons and the id
248  * parameter is used to discard repeated inserts in the delay time, useful
249  * when for instance the graphics to insert comes from a quickly resizing
250  * object: the frames between the start and destination sizes aren't
251  * useful in the cache and just cause overhead.
252  *
253  * @param key the name to use in the cache for this pixmap
254  * @param pix the pixmap data to store in the cache
255  * @param id a name that identifies the caller class of this function in an unique fashion.
256  * This is needed to limit disk writes of the cache.
257  * If an image with the same id changes quickly,
258  * only the last size where insertIntoCache was called is actually stored on disk
259  * @since 4.3
260  **/
261  void insertIntoCache(const QString &key, const QPixmap &pix, const QString &id);
262 
263  /**
264  * Sets the maximum size of the cache (in kilobytes). If cache gets bigger
265  * the limit then some entries are removed
266  * Setting cache limit to 0 disables automatic cache size limiting.
267  *
268  * Note that the cleanup might not be done immediately, so the cache might
269  * temporarily (for a few seconds) grow bigger than the limit.
270  **/
271  void setCacheLimit(int kbytes);
272 
273 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 78)
274  /**
275  * Tries to load the rect of a sub element from a disk cache
276  *
277  * @param image path of the image we want to check
278  * @param element sub element we want to retrieve
279  * @param rect output parameter of the element rect found in cache
280  * if not found or if we are sure it doesn't exist it will be QRect()
281  * @return true if the element was found in cache or if we are sure the element doesn't exist
282  **/
283  PLASMA_DEPRECATED_VERSION(5, 78, "Rects Cache public API is deprecated")
284  bool findInRectsCache(const QString &image, const QString &element, QRectF &rect) const;
285 
286  /**
287  * Returns a list of all keys of cached rects for the given image.
288  *
289  * @param image path of the image for which the keys should be returned
290  *
291  * @return a QStringList whose elements are the entry keys in the rects cache
292  *
293  * @since 4.6
294  */
295  PLASMA_DEPRECATED_VERSION(5, 78, "Rects Cache public API is deprecated")
296  QStringList listCachedRectKeys(const QString &image) const;
297 
298  /**
299  * Inserts a rectangle of a sub element of an image into a disk cache
300  *
301  * @param image path of the image we want to insert information
302  * @param element sub element we want insert the rect
303  * @param rect element rectangle
304  **/
305  PLASMA_DEPRECATED_VERSION(5, 78, "Rects Cache public API is deprecated")
306  void insertIntoRectsCache(const QString &image, const QString &element, const QRectF &rect);
307 
308  /**
309  * Discards all the information about a given image from the rectangle disk cache
310  *
311  * @param image the path to the image the cache is associated with
312  **/
313  PLASMA_DEPRECATED_VERSION(5, 78, "Rects Cache public API is deprecated")
314  void invalidateRectsCache(const QString &image);
315 
316  /**
317  * Frees up memory used by cached information for a given image without removing
318  * the permanent record of it on disk.
319  * @see invalidateRectsCache
320  *
321  * @param image the path to the image the cache is associated with
322  */
323  PLASMA_DEPRECATED_VERSION(5, 78, "Rects Cache public API is deprecated")
324  void releaseRectsCache(const QString &image);
325 #endif
326 
327 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 67)
328  /**
329  * @return plugin info for this theme, with information such as
330  * name, description, author, website etc
331  * @since 5.0
332  *
333  * @deprecated since 5.67, use KPluginMetaData
334  */
335  PLASMA_DEPRECATED_VERSION(5, 67, "Use KPluginMetaData metadata()")
336  KPluginInfo pluginInfo() const;
337 #endif
338 
339  /**
340  * @return plugin metadata for this theme, with information such as
341  * name, description, author, website etc
342  * @since 5.95
343  */
344  KPluginMetaData metadata() const;
345 
346  /**
347  * @return The default application font
348  * @since 5.0
349  */
350  QFont defaultFont() const;
351 
352  /**
353  * @return The smallest readable font
354  * @since 5.0
355  */
356  QFont smallestFont() const;
357 
358  /** This method allows Plasma to enable and disable the background
359  * contrast effect for a given theme, improving readability. The
360  * value is read from the "enabled" key in the "ContrastEffect"
361  * group in the Theme's metadata file.
362  * The configuration in the metadata.desktop file of the theme
363  * could look like this (for a lighter background):
364  * \code
365  * [ContrastEffect]
366  * enabled=true
367  * contrast=0.45
368  * intensity=0.45
369  * saturation=1.7
370  * \endcode
371  * @return Whether or not to enable the contrasteffect
372  * @since 5.0
373  */
374  bool backgroundContrastEnabled() const;
375 
376  /** This method allows Plasma to enable and disable the adaptive
377  * transparency option of the panel, which allows user to decide
378  * whether the panel should be always transparent, always opaque
379  * or only opaque when a window is maximized.
380  * The configuration in the metadata.desktop file of the theme
381  * could look like this (for a lighter background):
382  * \code
383  * [AdaptiveTransparency]
384  * enabled=true
385  * \endcode
386  * @return Whether or not to enable the adaptive transparency
387  * @since 5.20
388  */
389  bool adaptiveTransparencyEnabled() const;
390 
391  /** This method allows Plasma to set a background contrast effect
392  * for a given theme, improving readability. The value is read
393  * from the "contrast" key in the "ContrastEffect" group in the
394  * Theme's metadata file.
395  * @return The contrast provided to the contrasteffect
396  * @since 5.0
397  * @see backgroundContrastEnabled
398  */
399  qreal backgroundContrast() const;
400 
401  /** This method allows Plasma to set a background contrast effect
402  * for a given theme, improving readability. The value is read
403  * from the "intensity" key in the "ContrastEffect" group in the
404  * Theme's metadata file.
405  * @return The intensity provided to the contrasteffect
406  * @since 5.0
407  * @see backgroundContrastEnabled
408  */
409  qreal backgroundIntensity() const;
410 
411  /** This method allows Plasma to set a background contrast effect
412  * for a given theme, improving readability. The value is read
413  * from the "saturation" key in the "ContrastEffect" group in the
414  * Theme's metadata file.
415  * @return The saturation provided to the contrasteffect
416  * @since 5.0
417  * @see backgroundContrastEnabled
418  */
419  qreal backgroundSaturation() const;
420 
421  /** This method allows Plasma to enable and disable the blurring
422  * of what is behind the background for a given theme. The
423  * value is read from the "enabled" key in the "BlurBehindEffect"
424  * group in the Theme's metadata file. Default is @c true.
425  *
426  * The configuration in the metadata.desktop file of the theme
427  * could look like this:
428  * \code
429  * [BlurBehindEffect]
430  * enabled=false
431  * \endcode
432  * @return Whether or not to enable blurring of what is behind
433  * @since 5.57
434  */
435  bool blurBehindEnabled() const;
436 
437  /**
438  * Returns the size of the letter "M" as rendered on the screen with the given font.
439  * This values gives you a base size that:
440  * * scales dependent on the DPI of the screen
441  * * Scales with the default font as set by the user
442  * You can use it like this in QML Items:
443  * \code
444  * Item {
445  * width: PlasmaCore.Theme.mSize(PlasmaCore.Theme.defaultFont).height
446  * height: width
447  * }
448  * \endcode
449  * This allows you to dynamically scale elements of your user interface with different font settings and
450  * different physical outputs (with different DPI).
451  * @param font The font to use for the metrics.
452  * @return The size of the letter "M" as rendered on the screen with the given font.
453  * @since 5.0
454  */
455  Q_INVOKABLE QSizeF mSize(const QFont &font = QGuiApplication::font()) const;
456 
457  QString backgroundPath(const QString &image) const;
458 
459  static QPalette globalPalette();
460 
461 Q_SIGNALS:
462  /**
463  * Emitted when the user changes the theme. Stylesheet usage, colors, etc. should
464  * be updated at this point. However, SVGs should *not* be repainted in response
465  * to this signal; connect to Svg::repaintNeeded() instead for that, as Svg objects
466  * need repainting not only when themeChanged() is emitted; moreover Svg objects
467  * connect to and respond appropriately to themeChanged() internally, emitting
468  * Svg::repaintNeeded() at an appropriate time.
469  */
470  void themeChanged();
471 
472  /** Notifier for change of defaultFont property */
473  void defaultFontChanged();
474  /** Notifier for change of smallestFont property */
475  void smallestFontChanged();
476 
477 private:
478  friend class SvgPrivate;
479  friend class FrameSvg;
480  friend class FrameSvgPrivate;
481  friend class ThemePrivate;
482  ThemePrivate *d;
483 };
484 
485 } // Plasma namespace
486 
487 #endif // multiple inclusion guard
Definition: Theme.qml:10
Namespace for everything in libplasma.
Definition: datamodel.cpp:14
Interface to the Plasma theme.
Definition: theme.h:42
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Feb 5 2023 04:14:16 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.