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
20class 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{
54public:
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 */
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 */
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 */
238 PositiveText = 7
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
297public:
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
438private:
439
441};
A set of methods used to work with colors.
ColorSet
This enumeration describes the color set for which a color is being selected.
@ Selection
Selected items in views.
@ Complementary
Complementary areas.
@ View
Views; for example, frames, input fields, etc.
@ Button
Buttons and button-like controls.
@ Window
Non-editable window elements; for example, menus.
@ Tooltip
Tooltips.
QBrush background(BackgroundRole=NormalBackground) const
Retrieve the requested background brush.
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 ...
static qreal contrastF(const KSharedConfigPtr &config=KSharedConfigPtr())
Returns the contrast for borders as a floating point value.
BackgroundRole
This enumeration describes the background color being selected from the given set.
@ LinkBackground
Fourth color; corresponds to (unvisited) links.
@ PositiveBackground
Eigth color; for example, success messages, trusted content.
@ AlternateBackground
Alternate background; for example, for use in lists.
@ ActiveBackground
Third color; for example, items which are new, active, requesting attention, etc.
@ VisitedBackground
Fifth color; corresponds to visited links.
@ NormalBackground
Normal background.
@ NegativeBackground
Sixth color; for example, errors, untrusted content, etc.
@ NeutralBackground
Seventh color; for example, warnings, secure/encrypted content.
ForegroundRole
This enumeration describes the foreground color being selected from the given set.
@ NormalText
Normal foreground.
@ InactiveText
Second color; for example, comments, items which are old, inactive or disabled.
@ LinkText
Fourth color; use for (unvisited) links.
@ VisitedText
Fifth color; used for (visited) links.
@ ActiveText
Third color; for example items which are new, active, requesting attention, etc.
@ NegativeText
Sixth color; for example, errors, untrusted content, deletions, etc.
@ NeutralText
Seventh color; for example, warnings, secure/encrypted content.
@ PositiveText
Eigth color; for example, additions, success messages, trusted content.
SchemeManager & operator=(const SchemeManager &)
Standard assignment operator.
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 ...
static int contrast()
Returns the contrast for borders.
DecorationRole
This enumeration describes the decoration color being selected from the given set.
@ HoverColor
Color used to draw decorations for items which will be activated by clicking.
@ FocusColor
Color used to draw decorations for items which have input focus.
static QPalette createApplicationPalette(const KSharedConfigPtr &config)
Used to obtain the QPalette that will be used to set the application palette from KDE Platform theme.
QColor shade(ShadeRole) const
Retrieve the requested shade color, using SchemeManager::background(SchemeManager::NormalBackground) ...
QBrush decoration(DecorationRole) const
Retrieve the requested decoration brush.
ShadeRole
This enumeration describes the color shade being selected from the given set.
@ DarkShade
The dark color is in between mid() and shadow().
@ MidlightShade
The midlight color is in between base() and light().
@ LightShade
The light color is lighter than dark() or shadow() and contrasts with the base color.
@ ShadowShade
The shadow color is darker than light() or midlight() and contrasts the base color.
@ MidShade
The mid color is in between base() and dark().
QBrush foreground(ForegroundRole=NormalText) const
Retrieve the requested foreground brush.
SchemeManager(const SchemeManager &)
Construct a copy of another SchemeManager.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Mon Nov 4 2024 16:38:42 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.