Libplasma

theme.h
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 PLASMA_THEME_H
9#define PLASMA_THEME_H
10
11#include <QFont>
12#include <QGuiApplication>
13#include <QObject>
14
15#include <KSharedConfig>
16#include <plasma/plasma_export.h>
17
18class KPluginMetaData;
19
20namespace Plasma
21{
22class ThemePrivate;
23class SvgPrivate;
24
25/**
26 * @class Theme plasma/theme.h <Plasma/Theme>
27 *
28 * @short Interface to the Plasma theme
29 *
30 *
31 * Plasma::Theme provides access to a common and standardized set of graphic
32 * elements stored in SVG format. This allows artists to create single packages
33 * of SVGs that will affect the look and feel of all workspace components.
34 *
35 * Plasma::Svg uses Plasma::Theme internally to locate and load the appropriate
36 * SVG data. Alternatively, Plasma::Theme can be used directly to retrieve
37 * file system paths to SVGs by name.
38 */
39class PLASMA_EXPORT Theme : public QObject
40{
41 Q_OBJECT
42
43 Q_PROPERTY(QString themeName READ themeName NOTIFY themeChanged)
44 Q_PROPERTY(bool useGlobalSettings READ useGlobalSettings NOTIFY themeChanged)
45 Q_PROPERTY(QString wallpaperPath READ wallpaperPath NOTIFY themeChanged)
46
47 // fonts
48 Q_PROPERTY(QFont defaultFont READ defaultFont NOTIFY defaultFontChanged)
49 Q_PROPERTY(QFont smallestFont READ smallestFont NOTIFY smallestFontChanged)
50
51 Q_PROPERTY(QPalette palette READ palette NOTIFY themeChanged)
52
53 Q_PROPERTY(qreal backgroundContrast READ backgroundContrast NOTIFY themeChanged)
54 Q_PROPERTY(qreal backgroundIntensity READ backgroundIntensity NOTIFY themeChanged)
55 Q_PROPERTY(qreal backgroundSaturation READ backgroundSaturation NOTIFY themeChanged)
56
57public:
58 enum ColorRole {
59 TextColor = 0, /**< the text color to be used by items resting on the background */
60 BackgroundColor = 1, /**< the default background color */
61 HighlightColor = 2, /**< the text highlight color to be used by items resting
62 on the background */
63 HoverColor = 3, /**< color for hover effect on view */
64 FocusColor = 4, /**< color for focus effect on view */
65 LinkColor = 5, /**< color for clickable links */
66 VisitedLinkColor = 6, /**< color visited clickable links */
67 HighlightedTextColor = 7, /**< color contrasting with HighlightColor, to be used for instance with */
68 PositiveTextColor = 8, /**< color of foreground objects with a "positive message" connotation (usually green) */
69 NeutralTextColor = 9, /**< color of foreground objects with a "neutral message" connotation (usually yellow) */
70 NegativeTextColor = 10, /**< color of foreground objects with a "negative message" connotation (usually red) */
71 DisabledTextColor = 11, /**< color of disabled text @since 5.64 */
72 };
73
74 enum ColorGroup {
75 NormalColorGroup = 0,
76 ButtonColorGroup = 1,
77 ViewColorGroup = 2,
78 ComplementaryColorGroup = 3,
79 HeaderColorGroup,
80 ToolTipColorGroup,
81 };
82 Q_ENUM(ColorGroup)
83
84 /**
85 * Default constructor. It will be the global theme configured in plasmarc
86 * @param parent the parent object
87 */
88 explicit Theme(QObject *parent = nullptr);
89
90 /**
91 * Construct a theme. It will be a custom theme instance of themeName.
92 * @param themeName the name of the theme to create
93 * @param parent the parent object
94 * @since 4.3
95 */
96 explicit Theme(const QString &themeName, QObject *parent = nullptr);
97
98 ~Theme() override;
99
100 /**
101 * Sets the current theme being used.
102 */
103 void setThemeName(const QString &themeName);
104
105 /**
106 * @return the name of the theme.
107 */
108 QString themeName() const;
109
110 /**
111 * Retrieve the path for an SVG image in the current theme.
112 *
113 * @param name the name of the file in the theme directory (without the
114 * ".svg" part or a leading slash)
115 * @return the full path to the requested file for the current theme
116 */
117 QString imagePath(const QString &name) const;
118
119 /**
120 * Retrieves the default wallpaper associated with this theme.
121 *
122 * @param size the target height and width of the wallpaper; if an invalid size
123 * is passed in, then a default size will be provided instead.
124 * @return the full path to the wallpaper image
125 */
126 QString wallpaperPath(const QSize &size = QSize()) const;
127
128 Q_INVOKABLE QString wallpaperPathForSize(int width = -1, int height = -1) const;
129
130 /**
131 * Checks if this theme has an image named in a certain way
132 *
133 * @param name the name of the file in the theme directory (without the
134 * ".svg" part or a leading slash)
135 * @return true if the image exists for this theme
136 */
137 bool currentThemeHasImage(const QString &name) const;
138
139 /**
140 * Returns the color scheme configurationthat goes along this theme.
141 * This can be used with KStatefulBrush and KColorScheme to determine
142 * the proper colours to use along with the visual elements in this theme.
143 */
144 KSharedConfigPtr colorScheme() const;
145
146 /**
147 * Returns the text color to be used by items resting on the background
148 *
149 * @param role which role (usage pattern) to get the color for
150 * @param group which group we want a color of
151 */
152 QColor color(ColorRole role, ColorGroup group = NormalColorGroup) const;
153
154 /**
155 * Tells the theme whether to follow the global settings or use application
156 * specific settings
157 *
158 * @param useGlobal pass in true to follow the global settings
159 */
160 void setUseGlobalSettings(bool useGlobal);
161
162 /**
163 * @return true if the global settings are followed, false if application
164 * specific settings are used.
165 */
166 bool useGlobalSettings() const;
167
168 /**
169 * Returns a QPalette with the colors set as defined by the theme.
170 * @since 5.68
171 */
172 QPalette palette() const;
173
174 /**
175 * @return plugin metadata for this theme, with information such as
176 * name, description, author, website etc
177 * @since 5.95
178 */
179 KPluginMetaData metadata() const;
180
181 /**
182 * @return The default application font
183 * @since 5.0
184 */
185 QFont defaultFont() const;
186
187 /**
188 * @return The smallest readable font
189 * @since 5.0
190 */
191 QFont smallestFont() const;
192
193 /** This method allows Plasma to enable and disable the background
194 * contrast effect for a given theme, improving readability. The
195 * value is read from the "enabled" key in the "ContrastEffect"
196 * group in the Theme's metadata file.
197 * The configuration in the metadata.desktop file of the theme
198 * could look like this (for a lighter background):
199 * \code
200 * [ContrastEffect]
201 * enabled=true
202 * contrast=0.45
203 * intensity=0.45
204 * saturation=1.7
205 * \endcode
206 * @return Whether or not to enable the contrasteffect
207 * @since 5.0
208 */
209 bool backgroundContrastEnabled() const;
210
211 /** This method allows Plasma to enable and disable the adaptive
212 * transparency option of the panel, which allows user to decide
213 * whether the panel should be always transparent, always opaque
214 * or only opaque when a window is maximized.
215 * The configuration in the metadata.desktop file of the theme
216 * could look like this (for a lighter background):
217 * \code
218 * [AdaptiveTransparency]
219 * enabled=true
220 * \endcode
221 * @return Whether or not to enable the adaptive transparency
222 * @since 5.20
223 */
224 bool adaptiveTransparencyEnabled() const;
225
226 /** This method allows Plasma to set a background contrast effect
227 * for a given theme, improving readability. The value is read
228 * from the "contrast" key in the "ContrastEffect" group in the
229 * Theme's metadata file.
230 * @return The contrast provided to the contrasteffect
231 * @since 5.0
232 * @see backgroundContrastEnabled
233 */
234 qreal backgroundContrast() const;
235
236 /** This method allows Plasma to set a background contrast effect
237 * for a given theme, improving readability. The value is read
238 * from the "intensity" key in the "ContrastEffect" group in the
239 * Theme's metadata file.
240 * @return The intensity provided to the contrasteffect
241 * @since 5.0
242 * @see backgroundContrastEnabled
243 */
244 qreal backgroundIntensity() const;
245
246 /** This method allows Plasma to set a background contrast effect
247 * for a given theme, improving readability. The value is read
248 * from the "saturation" key in the "ContrastEffect" group in the
249 * Theme's metadata file.
250 * @return The saturation provided to the contrasteffect
251 * @since 5.0
252 * @see backgroundContrastEnabled
253 */
254 qreal backgroundSaturation() const;
255
256 /** This method allows Plasma to enable and disable the blurring
257 * of what is behind the background for a given theme. The
258 * value is read from the "enabled" key in the "BlurBehindEffect"
259 * group in the Theme's metadata file. Default is @c true.
260 *
261 * The configuration in the metadata.desktop file of the theme
262 * could look like this:
263 * \code
264 * [BlurBehindEffect]
265 * enabled=false
266 * \endcode
267 * @return Whether or not to enable blurring of what is behind
268 * @since 5.57
269 */
270 bool blurBehindEnabled() const;
271
272 /**
273 * Returns the size of the letter "M" as rendered on the screen with the given font.
274 * This values gives you a base size that:
275 * * scales dependent on the DPI of the screen
276 * * Scales with the default font as set by the user
277 * You can use it like this in QML Items:
278 * \code
279 * Item {
280 * width: PlasmaCore.Theme.mSize(PlasmaCore.Theme.defaultFont).height
281 * height: width
282 * }
283 * \endcode
284 * This allows you to dynamically scale elements of your user interface with different font settings and
285 * different physical outputs (with different DPI).
286 * @param font The font to use for the metrics.
287 * @return The size of the letter "M" as rendered on the screen with the given font.
288 * @since 5.0
289 */
290 Q_INVOKABLE QSizeF mSize(const QFont &font = QGuiApplication::font()) const;
291
292 QString backgroundPath(const QString &image) const;
293
294 static QPalette globalPalette();
295
296 static KSharedConfigPtr globalColorScheme();
297
298Q_SIGNALS:
299 /**
300 * Emitted when the user changes the theme. Stylesheet usage, colors, etc. should
301 * be updated at this point. However, SVGs should *not* be repainted in response
302 * to this signal; connect to Svg::repaintNeeded() instead for that, as Svg objects
303 * need repainting not only when themeChanged() is emitted; moreover Svg objects
304 * connect to and respond appropriately to themeChanged() internally, emitting
305 * Svg::repaintNeeded() at an appropriate time.
306 */
308
309 /** Notifier for change of defaultFont property */
311 /** Notifier for change of smallestFont property */
313
314private:
315 friend class SvgPrivate;
316 friend class FrameSvg;
317 friend class FrameSvgPrivate;
318 friend class ThemePrivate;
319 ThemePrivate *d;
320};
321
322} // Plasma namespace
323
324#endif // multiple inclusion guard
Interface to the Plasma theme.
Definition theme.h:40
void defaultFontChanged()
Notifier for change of defaultFont property.
void smallestFontChanged()
Notifier for change of smallestFont property.
void themeChanged()
Emitted when the user changes the theme.
Namespace for everything in libplasma.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:01:35 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.