KConfigWidgets

kcolorscheme.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 2007 Matthew Woehlke <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef KCOLORSCHEME_H
9 #define KCOLORSCHEME_H
10 
11 #include <KSharedConfig>
12 #include <kconfigwidgets_export.h>
13 
14 #include <QExplicitlySharedDataPointer>
15 
16 #include <QPalette>
17 
18 class QColor;
19 class QBrush;
20 
21 class KColorSchemePrivate;
22 
23 /**
24  * @class KColorScheme kcolorscheme.h KColorScheme
25  *
26  * A set of methods used to work with colors.
27  *
28  * KColorScheme currently provides access to the system color palette that the
29  * user has selected (in the future, it is expected to do more). It greatly
30  * expands on QPalette by providing five distinct "sets" with several color
31  * choices each, covering background, foreground, and decoration colors.
32  *
33  * A KColorScheme instance represents colors corresponding to a "set", where a
34  * set consists of those colors used to draw a particular type of element, such
35  * as a menu, button, view, selected text, or tooltip. Each set has a distinct
36  * set of colors, so you should always use the correct set for drawing and
37  * never assume that a particular foreground for one set is the same as the
38  * foreground for any other set. Individual colors may be quickly referenced by
39  * creating an anonymous instance and invoking a lookup member.
40  *
41  * @note
42  * The color palettes for the various states of a widget (active, inactive,
43  * disabled) may be wildly different. Therefore, it is important to take the
44  * state into account. This is why the KColorScheme constructor requires a
45  * QPalette::ColorGroup as an argument.
46  *
47  * To facilitate working with potentially-varying states, two convenience API's
48  * are provided. These are KColorScheme::adjustBackground and its sister
49  * KColorScheme::adjustForeground, and the helper class ::KStatefulBrush.
50  *
51  * @see KColorScheme::ColorSet, KColorScheme::ForegroundRole,
52  * KColorScheme::BackgroundRole, KColorScheme::DecorationRole,
53  * KColorScheme::ShadeRole
54  */
55 class KCONFIGWIDGETS_EXPORT KColorScheme
56 {
57 public:
58  /**
59  * This enumeration describes the color set for which a color is being
60  * selected.
61  *
62  * Color sets define a color "environment", suitable for drawing all parts
63  * of a given region. Colors from different sets should not be combined.
64  */
65  enum ColorSet {
66  /**
67  * Views; for example, frames, input fields, etc.
68  *
69  * If it contains things that can be selected, it is probably a View.
70  */
72  /**
73  * Non-editable window elements; for example, menus.
74  *
75  * If it isn't a Button, View, or Tooltip, it is probably a Window.
76  */
78  /**
79  * Buttons and button-like controls.
80  *
81  * In addition to buttons, "button-like" controls such as non-editable
82  * dropdowns, scrollbar sliders, slider handles, etc. should also use
83  * this role.
84  */
86  /**
87  * Selected items in views.
88  *
89  * Note that unfocused or disabled selections should use the Window
90  * role. This makes it more obvious to the user that the view
91  * containing the selection does not have input focus.
92  */
94  /**
95  * Tooltips.
96  *
97  * The tooltip set can often be substituted for the view
98  * set when editing is not possible, but the Window set is deemed
99  * inappropriate. "What's This" help is an excellent example, another
100  * might be pop-up notifications (depending on taste).
101  */
103  /**
104  * Complementary areas.
105  *
106  * Some applications want some areas to have a different color scheme.
107  * Usually dark areas over a light theme. For instance the fullscreen UI
108  * of a picture viewer, or the logout/lock screen of the plasma workspace
109  * ask for a dark color scheme even on light themes.
110  * @since 5.19
111  */
113  /**
114  * Colors for header areas that should be used both by the top toolbar and the titlebar.
115  * @since 5.69
116  */
118  /**
119  * Number of color sets.
120  * Note: don't use this
121  * @since 5.65
122  */
124  };
125 
126  /**
127  * This enumeration describes the background color being selected from the
128  * given set.
129  *
130  * Background colors are suitable for drawing under text, and should never
131  * be used to draw text. In combination with one of the overloads of
132  * KColorScheme::shade, they may be used to generate colors for drawing
133  * frames, bevels, and similar decorations.
134  */
136  /**
137  * Normal background.
138  */
140  /**
141  * Alternate background; for example, for use in lists.
142  *
143  * This color may be the same as BackgroundNormal, especially in sets
144  * other than View and Window.
145  */
147  /**
148  * Third color; for example, items which are new, active, requesting
149  * attention, etc.
150  *
151  * Alerting the user that a certain field must be filled out would be a
152  * good usage (although NegativeBackground could be used to the same
153  * effect, depending on what you are trying to achieve). Unlike
154  * ActiveText, this should not be used for mouseover effects.
155  */
157  /**
158  * Fourth color; corresponds to (unvisited) links.
159  *
160  * Exactly what this might be used for is somewhat harder to qualify;
161  * it might be used for bookmarks, as a 'you can click here' indicator,
162  * or to highlight recent content (i.e. in a most-recently-accessed
163  * list).
164  */
166  /**
167  * Fifth color; corresponds to visited links.
168  *
169  * This can also be used to indicate "not recent" content, especially
170  * when a color is needed to denote content which is "old" or
171  * "archival".
172  */
174  /**
175  * Sixth color; for example, errors, untrusted content, etc.
176  */
178  /**
179  * Seventh color; for example, warnings, secure/encrypted content.
180  */
182  /**
183  * Eighth color; for example, success messages, trusted content.
184  */
186  /**
187  * Number of background roles.
188  * @since 5.65
189  */
191  };
192 
193  /**
194  * This enumeration describes the foreground color being selected from the
195  * given set.
196  *
197  * Foreground colors are suitable for drawing text or glyphs (such as the
198  * symbols on window decoration buttons, assuming a suitable background
199  * brush is used), and should never be used to draw backgrounds.
200  *
201  * For window decorations, the following is suggested, but not set in
202  * stone:
203  * @li Maximize - PositiveText
204  * @li Minimize - NeutralText
205  * @li Close - NegativeText
206  * @li WhatsThis - LinkText
207  * @li Sticky - ActiveText
208  */
210  /**
211  * Normal foreground.
212  */
214  /**
215  * Second color; for example, comments, items which are old, inactive
216  * or disabled. Generally used for things that are meant to be "less
217  * important". InactiveText is not the same role as NormalText in the
218  * inactive state.
219  */
221  /**
222  * Third color; for example items which are new, active, requesting
223  * attention, etc. May be used as a hover color for clickable items.
224  */
226  /**
227  * Fourth color; use for (unvisited) links. May also be used for other
228  * clickable items or content that indicates relationships, items that
229  * indicate somewhere the user can visit, etc.
230  */
232  /**
233  * Fifth color; used for (visited) links. As with LinkText, may be used
234  * for items that have already been "visited" or accessed. May also be
235  * used to indicate "historical" (i.e. "old") items or information,
236  * especially if InactiveText is being used in the same context to
237  * express something different.
238  */
240  /**
241  * Sixth color; for example, errors, untrusted content, deletions,
242  * etc.
243  */
245  /**
246  * Seventh color; for example, warnings, secure/encrypted content.
247  */
249  /**
250  * Eighth color; for example, additions, success messages, trusted
251  * content.
252  */
254  /**
255  * Number of foreground roles.
256  * @since 5.65
257  */
259  };
260 
261  /**
262  * This enumeration describes the decoration color being selected from the
263  * given set.
264  *
265  * Decoration colors are used to draw decorations (such as frames) for
266  * special purposes. Like color shades, they are neither foreground nor
267  * background colors. Text should not be painted over a decoration color,
268  * and decoration colors should not be used to draw text.
269  */
271  /**
272  * Color used to draw decorations for items which have input focus.
273  */
275  /**
276  * Color used to draw decorations for items which will be activated by
277  * clicking.
278  */
280  /**
281  * Number of decoration roles.
282  * @since 5.65
283  */
285  };
286 
287  /**
288  * This enumeration describes the color shade being selected from the given
289  * set.
290  *
291  * Color shades are used to draw "3d" elements, such as frames and bevels.
292  * They are neither foreground nor background colors. Text should not be
293  * painted over a shade, and shades should not be used to draw text.
294  */
295  enum ShadeRole {
296  /**
297  * The light color is lighter than dark() or shadow() and contrasts
298  * with the base color.
299  */
301  /**
302  * The midlight color is in between base() and light().
303  */
305  /**
306  * The mid color is in between base() and dark().
307  */
309  /**
310  * The dark color is in between mid() and shadow().
311  */
313  /**
314  * The shadow color is darker than light() or midlight() and contrasts
315  * the base color.
316  */
318  /**
319  * Number of shade roles.
320  * @since 5.65
321  */
323  };
324 
325  /** Destructor */
326  virtual ~KColorScheme(); // TODO KF6: remove virtual
327 
328  KColorScheme(const KColorScheme &);
329  KColorScheme &operator=(const KColorScheme &);
331  KColorScheme &operator=(KColorScheme &&);
332 
333  /**
334  * Construct a palette from given color set and state. Colors are taken
335  * from the given KConfig. If null, the application's color scheme is used
336  * (either the system default or one set by KColorSchemeManager).
337  *
338  * @note KColorScheme provides direct access to the color scheme for users
339  * that deal directly with widget states. Unless you are a low-level user
340  * or have a legitimate reason to only care about a fixed, limited number
341  * of states (e.g. windows that cannot be inactive), consider using a
342  * ::KStatefulBrush instead.
343  */
344  explicit KColorScheme(QPalette::ColorGroup = QPalette::Normal, ColorSet = View, KSharedConfigPtr = KSharedConfigPtr());
345 
346  /**
347  * Retrieve the requested background brush.
348  */
349  QBrush background(BackgroundRole = NormalBackground) const;
350 
351  /**
352  * Retrieve the requested foreground brush.
353  */
354  QBrush foreground(ForegroundRole = NormalText) const;
355 
356  /**
357  * Retrieve the requested decoration brush.
358  */
359  QBrush decoration(DecorationRole) const;
360 
361  /**
362  * Retrieve the requested shade color, using
363  * KColorScheme::background(KColorScheme::NormalBackground)
364  * as the base color and the contrast setting from the KConfig used to
365  * create this KColorScheme instance.
366  *
367  * @note Shades are chosen such that all shades would contrast with the
368  * base color. This means that if base is very dark, the 'dark' shades will
369  * be lighter than the base color, with midlight() == shadow().
370  * Conversely, if the base color is very light, the 'light' shades will be
371  * darker than the base color, with light() == mid().
372  */
373  QColor shade(ShadeRole) const;
374 
375 #if KCONFIGWIDGETS_ENABLE_DEPRECATED_SINCE(5, 93)
376  /**
377  * Returns the contrast for borders.
378  * @return the contrast (between 0 for minimum and 10 for maximum
379  * contrast)
380  * @deprecated since 5.93, use <tt>contrastF() * 10</tt>
381  */
382  KCONFIGWIDGETS_DEPRECATED_VERSION(5, 93, "Use contrastF() * 10")
383  static int contrast();
384 #endif
385 
386  /**
387  * Returns the contrast for borders as a floating point value.
388  * @param config pointer to the config from which to read the contrast
389  * setting. If null, the application's color scheme will be used
390  * (either the system default or one set by KColorSchemeManager).
391  * @return the contrast (between 0.0 for minimum and 1.0 for maximum
392  * contrast)
393  */
394  static qreal contrastF(const KSharedConfigPtr &config = KSharedConfigPtr());
395 
396  /**
397  * Retrieve the requested shade color, using the specified color as the
398  * base color and the application's contrast setting.
399  *
400  * @note Shades are chosen such that all shades would contrast with the
401  * base color. This means that if base is very dark, the 'dark' shades will
402  * be lighter than the base color, with midlight() == shadow().
403  * Conversely, if the base color is very light, the 'light' shades will be
404  * darker than the base color, with light() == mid().
405  */
406  static QColor shade(const QColor &, ShadeRole);
407 
408  /**
409  * Retrieve the requested shade color, using the specified color as the
410  * base color and the specified contrast.
411  *
412  * @param contrast Amount roughly specifying the contrast by which to
413  * adjust the base color, between -1.0 and 1.0 (values between 0.0 and 1.0
414  * correspond to the value from KColorScheme::contrastF)
415  * @param chromaAdjust (optional) Amount by which to adjust the chroma of
416  * the shade (1.0 means no adjustment)
417  *
418  * @note Shades are chosen such that all shades would contrast with the
419  * base color. This means that if base is very dark, the 'dark' shades will
420  * be lighter than the base color, with midlight() == shadow().
421  * Conversely, if the base color is very light, the 'light' shades will be
422  * darker than the base color, with light() == mid().
423  *
424  * @see KColorUtils::shade
425  */
426  static QColor shade(const QColor &, ShadeRole, qreal contrast, qreal chromaAdjust = 0.0);
427 
428  /**
429  * Adjust a QPalette by replacing the specified QPalette::ColorRole with
430  * the requested background color for all states. Using this method is
431  * safer than replacing individual states, as it insulates you against
432  * changes in QPalette::ColorGroup.
433  *
434  * @note Although it is possible to replace a foreground color using this
435  * method, it's bad usability to do so. Just say "no".
436  */
437  static void adjustBackground(QPalette &,
438  BackgroundRole newRole = NormalBackground,
440  ColorSet set = View,
441  KSharedConfigPtr = KSharedConfigPtr());
442 
443  /**
444  * Adjust a QPalette by replacing the specified QPalette::ColorRole with
445  * the requested foreground color for all states. Using this method is
446  * safer than replacing individual states, as it insulates you against
447  * changes in QPalette::ColorGroup.
448  *
449  * @note Although it is possible to replace a background color using this
450  * method, it's bad usability to do so. Just say "no".
451  */
452  static void adjustForeground(QPalette &,
453  ForegroundRole newRole = NormalText,
455  ColorSet set = View,
456  KSharedConfigPtr = KSharedConfigPtr());
457 
458  /**
459  * Used to obtain the QPalette that will be used to set the application
460  * palette from KDE Platform theme.
461  *
462  * @param config KConfig from which to load the colors
463  *
464  * @returns the QPalette
465  *
466  * @since 5.0
467  */
468  static QPalette createApplicationPalette(const KSharedConfigPtr &config);
469 
470  /**
471  * Used to check if the color scheme has a given set.
472  *
473  * @param config KConfig from which to load the colors
474  *
475  * @param set The color set to check for.
476  *
477  * @returns whether the color scheme has a given color set
478  *
479  * @since 5.75
480  */
481  static bool isColorSetSupported(const KSharedConfigPtr &config, KColorScheme::ColorSet set);
482 
483  /**
484  * @since 5.92
485  */
486  bool operator==(const KColorScheme &other) const;
487 
488 private:
490 };
491 
492 Q_DECLARE_METATYPE(KColorScheme)
493 
494 #if KCONFIGWIDGETS_ENABLE_DEPRECATED_SINCE(5, 93)
495 // Include for compatibility because class was defined here before
496 #include "kstatefulbrush.h"
497 #endif
498 
499 #endif // KCOLORSCHEME_H
@ VisitedText
Fifth color; used for (visited) links.
Definition: kcolorscheme.h:239
@ MidShade
The mid color is in between base() and dark().
Definition: kcolorscheme.h:308
@ MidlightShade
The midlight color is in between base() and light().
Definition: kcolorscheme.h:304
@ NeutralBackground
Seventh color; for example, warnings, secure/encrypted content.
Definition: kcolorscheme.h:181
@ Selection
Selected items in views.
Definition: kcolorscheme.h:93
@ NormalText
Normal foreground.
Definition: kcolorscheme.h:213
@ NegativeBackground
Sixth color; for example, errors, untrusted content, etc.
Definition: kcolorscheme.h:177
@ Header
Colors for header areas that should be used both by the top toolbar and the titlebar.
Definition: kcolorscheme.h:117
@ Window
Non-editable window elements; for example, menus.
Definition: kcolorscheme.h:77
@ DarkShade
The dark color is in between mid() and shadow().
Definition: kcolorscheme.h:312
@ ActiveText
Third color; for example items which are new, active, requesting attention, etc.
Definition: kcolorscheme.h:225
@ PositiveBackground
Eighth color; for example, success messages, trusted content.
Definition: kcolorscheme.h:185
@ LinkText
Fourth color; use for (unvisited) links.
Definition: kcolorscheme.h:231
@ NBackgroundRoles
Number of background roles.
Definition: kcolorscheme.h:190
@ NeutralText
Seventh color; for example, warnings, secure/encrypted content.
Definition: kcolorscheme.h:248
@ NColorSets
Number of color sets.
Definition: kcolorscheme.h:123
@ ShadowShade
The shadow color is darker than light() or midlight() and contrasts the base color.
Definition: kcolorscheme.h:317
@ FocusColor
Color used to draw decorations for items which have input focus.
Definition: kcolorscheme.h:274
ForegroundRole
This enumeration describes the foreground color being selected from the given set.
Definition: kcolorscheme.h:209
@ PositiveText
Eighth color; for example, additions, success messages, trusted content.
Definition: kcolorscheme.h:253
@ NormalBackground
Normal background.
Definition: kcolorscheme.h:139
ShadeRole
This enumeration describes the color shade being selected from the given set.
Definition: kcolorscheme.h:295
ColorSet
This enumeration describes the color set for which a color is being selected.
Definition: kcolorscheme.h:65
@ NForegroundRoles
Number of foreground roles.
Definition: kcolorscheme.h:258
@ AlternateBackground
Alternate background; for example, for use in lists.
Definition: kcolorscheme.h:146
@ Button
Buttons and button-like controls.
Definition: kcolorscheme.h:85
@ Tooltip
Tooltips.
Definition: kcolorscheme.h:102
@ InactiveText
Second color; for example, comments, items which are old, inactive or disabled.
Definition: kcolorscheme.h:220
@ LightShade
The light color is lighter than dark() or shadow() and contrasts with the base color.
Definition: kcolorscheme.h:300
@ VisitedBackground
Fifth color; corresponds to visited links.
Definition: kcolorscheme.h:173
@ LinkBackground
Fourth color; corresponds to (unvisited) links.
Definition: kcolorscheme.h:165
DecorationRole
This enumeration describes the decoration color being selected from the given set.
Definition: kcolorscheme.h:270
@ View
Views; for example, frames, input fields, etc.
Definition: kcolorscheme.h:71
@ NDecorationRoles
Number of decoration roles.
Definition: kcolorscheme.h:284
@ Complementary
Complementary areas.
Definition: kcolorscheme.h:112
@ NShadeRoles
Number of shade roles.
Definition: kcolorscheme.h:322
BackgroundRole
This enumeration describes the background color being selected from the given set.
Definition: kcolorscheme.h:135
@ NegativeText
Sixth color; for example, errors, untrusted content, deletions, etc.
Definition: kcolorscheme.h:244
@ HoverColor
Color used to draw decorations for items which will be activated by clicking.
Definition: kcolorscheme.h:279
@ ActiveBackground
Third color; for example, items which are new, active, requesting attention, etc.
Definition: kcolorscheme.h:156
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Sep 25 2023 03:46:23 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.