Kstars

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

KDE's Doxygen guidelines are available online.