Differential D18683 Diff 51530 plugins/kdecorations/aurorae/src/colorhelper.h

Changeset View

Standalone View

View Options

plugins/kdecorations/aurorae/src/colorhelper.h

Show All 39 Lines38public:
40 ~ColorHelper(); 40​ ~ColorHelper();
41 /** 41​ /**
42 * This enumeration describes the color shade being selected from the given 42​ * This enumeration describes the color shade being selected from the given
43 * set. 43​ * set.
44 * 44​ *
45 * Color shades are used to draw "3d" elements, such as frames and bevels. 45​ * Color shades are used to draw "3d" elements, such as frames and bevels.
46 * They are neither foreground nor background colors. Text should not be 46​ * They are neither foreground nor background colors. Text should not be
47 * painted over a shade, and shades should not be used to draw text. 47​ * painted over a shade, and shades should not be used to draw text.
48 */ 48​ **/
49 enum ShadeRole { 49​ enum ShadeRole {
50 /** 50​ /**
51 * The light color is lighter than dark() or shadow() and contrasts 51​ * The light color is lighter than dark() or shadow() and contrasts
52 * with the base color. 52​ * with the base color.
53 */ 53​ **/
54 LightShade, 54​ LightShade,
55 /** 55​ /**
56 * The midlight color is in between base() and light(). 56​ * The midlight color is in between base() and light().
57 */ 57​ **/
58 MidlightShade, 58​ MidlightShade,
59 /** 59​ /**
60 * The mid color is in between base() and dark(). 60​ * The mid color is in between base() and dark().
61 */ 61​ **/
62 MidShade, 62​ MidShade,
63 /** 63​ /**
64 * The dark color is in between mid() and shadow(). 64​ * The dark color is in between mid() and shadow().
65 */ 65​ **/
66 DarkShade, 66​ DarkShade,
67 /** 67​ /**
68 * The shadow color is darker than light() or midlight() and contrasts 68​ * The shadow color is darker than light() or midlight() and contrasts
69 * the base color. 69​ * the base color.
70 */ 70​ **/
71 ShadowShade 71​ ShadowShade
72 }; 72​ };
73 /** 73​ /**
74 * This enumeration describes the background color being selected from the 74​ * This enumeration describes the background color being selected from the
75 * given set. 75​ * given set.
76 * 76​ *
77 * Background colors are suitable for drawing under text, and should never 77​ * Background colors are suitable for drawing under text, and should never
78 * be used to draw text. In combination with one of the overloads of 78​ * be used to draw text. In combination with one of the overloads of
79 * KColorScheme::shade, they may be used to generate colors for drawing 79​ * KColorScheme::shade, they may be used to generate colors for drawing
80 * frames, bevels, and similar decorations. 80​ * frames, bevels, and similar decorations.
81 */ 81​ **/
82 enum BackgroundRole { 82​ enum BackgroundRole {
83 /** 83​ /**
84 * Normal background. 84​ * Normal background.
85 */ 85​ **/
86 NormalBackground = 0, 86​ NormalBackground = 0,
87 /** 87​ /**
88 * Alternate background; for example, for use in lists. 88​ * Alternate background; for example, for use in lists.
89 * 89​ *
90 * This color may be the same as BackgroundNormal, especially in sets 90​ * This color may be the same as BackgroundNormal, especially in sets
91 * other than View and Window. 91​ * other than View and Window.
92 */ 92​ **/
93 AlternateBackground = 1, 93​ AlternateBackground = 1,
94 /** 94​ /**
95 * Third color; for example, items which are new, active, requesting 95​ * Third color; for example, items which are new, active, requesting
96 * attention, etc. 96​ * attention, etc.
97 * 97​ *
98 * Alerting the user that a certain field must be filled out would be a 98​ * Alerting the user that a certain field must be filled out would be a
99 * good usage (although NegativeBackground could be used to the same 99​ * good usage (although NegativeBackground could be used to the same
100 * effect, depending on what you are trying to achieve). Unlike 100​ * effect, depending on what you are trying to achieve). Unlike
101 * ActiveText, this should not be used for mouseover effects. 101​ * ActiveText, this should not be used for mouseover effects.
102 */ 102​ **/
103 ActiveBackground = 2, 103​ ActiveBackground = 2,
104 /** 104​ /**
105 * Fourth color; corresponds to (unvisited) links. 105​ * Fourth color; corresponds to (unvisited) links.
106 * 106​ *
107 * Exactly what this might be used for is somewhat harder to qualify; 107​ * Exactly what this might be used for is somewhat harder to qualify;
108 * it might be used for bookmarks, as a 'you can click here' indicator, 108​ * it might be used for bookmarks, as a 'you can click here' indicator,
109 * or to highlight recent content (i.e. in a most-recently-accessed 109​ * or to highlight recent content (i.e. in a most-recently-accessed
110 * list). 110​ * list).
111 */ 111​ **/
112 LinkBackground = 3, 112​ LinkBackground = 3,
113 /** 113​ /**
114 * Fifth color; corresponds to visited links. 114​ * Fifth color; corresponds to visited links.
115 * 115​ *
116 * This can also be used to indicate "not recent" content, especially 116​ * This can also be used to indicate "not recent" content, especially
117 * when a color is needed to denote content which is "old" or 117​ * when a color is needed to denote content which is "old" or
118 * "archival". 118​ * "archival".
119 */ 119​ **/
120 VisitedBackground = 4, 120​ VisitedBackground = 4,
121 /** 121​ /**
122 * Sixth color; for example, errors, untrusted content, etc. 122​ * Sixth color; for example, errors, untrusted content, etc.
123 */ 123​ **/
124 NegativeBackground = 5, 124​ NegativeBackground = 5,
125 /** 125​ /**
126 * Seventh color; for example, warnings, secure/encrypted content. 126​ * Seventh color; for example, warnings, secure/encrypted content.
127 */ 127​ **/
128 NeutralBackground = 6, 128​ NeutralBackground = 6,
129 /** 129​ /**
130 * Eigth color; for example, success messages, trusted content. 130​ * Eigth color; for example, success messages, trusted content.
131 */ 131​ **/
132 PositiveBackground = 7 132​ PositiveBackground = 7
133 }; 133​ };
134 134​
135 /** 135​ /**
136 * This enumeration describes the foreground color being selected from the 136​ * This enumeration describes the foreground color being selected from the
137 * given set. 137​ * given set.
138 * 138​ *
139 * Foreground colors are suitable for drawing text or glyphs (such as the 139​ * Foreground colors are suitable for drawing text or glyphs (such as the
140 * symbols on window decoration buttons, assuming a suitable background 140​ * symbols on window decoration buttons, assuming a suitable background
141 * brush is used), and should never be used to draw backgrounds. 141​ * brush is used), and should never be used to draw backgrounds.
142 * 142​ *
143 * For window decorations, the following is suggested, but not set in 143​ * For window decorations, the following is suggested, but not set in
144 * stone: 144​ * stone:
145 * @li Maximize - PositiveText 145​ * @li Maximize - PositiveText
146 * @li Minimize - NeutralText 146​ * @li Minimize - NeutralText
147 * @li Close - NegativeText 147​ * @li Close - NegativeText
148 * @li WhatsThis - LinkText 148​ * @li WhatsThis - LinkText
149 * @li Sticky - ActiveText 149​ * @li Sticky - ActiveText
150 */ 150​ **/
151 enum ForegroundRole { 151​ enum ForegroundRole {
152 /** 152​ /**
153 * Normal foreground. 153​ * Normal foreground.
154 */ 154​ **/
155 NormalText = 0, 155​ NormalText = 0,
156 /** 156​ /**
157 * Second color; for example, comments, items which are old, inactive 157​ * Second color; for example, comments, items which are old, inactive
158 * or disabled. Generally used for things that are meant to be "less 158​ * or disabled. Generally used for things that are meant to be "less
159 * important". InactiveText is not the same role as NormalText in the 159​ * important". InactiveText is not the same role as NormalText in the
160 * inactive state. 160​ * inactive state.
161 */ 161​ **/
162 InactiveText = 1, 162​ InactiveText = 1,
163 /** 163​ /**
164 * Third color; for example items which are new, active, requesting 164​ * Third color; for example items which are new, active, requesting
165 * attention, etc. May be used as a hover color for clickable items. 165​ * attention, etc. May be used as a hover color for clickable items.
166 */ 166​ **/
167 ActiveText = 2, 167​ ActiveText = 2,
168 /** 168​ /**
169 * Fourth color; use for (unvisited) links. May also be used for other 169​ * Fourth color; use for (unvisited) links. May also be used for other
170 * clickable items or content that indicates relationships, items that 170​ * clickable items or content that indicates relationships, items that
171 * indicate somewhere the user can visit, etc. 171​ * indicate somewhere the user can visit, etc.
172 */ 172​ **/
173 LinkText = 3, 173​ LinkText = 3,
174 /** 174​ /**
175 * Fifth color; used for (visited) links. As with LinkText, may be used 175​ * Fifth color; used for (visited) links. As with LinkText, may be used
176 * for items that have already been "visited" or accessed. May also be 176​ * for items that have already been "visited" or accessed. May also be
177 * used to indicate "historical" (i.e. "old") items or information, 177​ * used to indicate "historical" (i.e. "old") items or information,
178 * especially if InactiveText is being used in the same context to 178​ * especially if InactiveText is being used in the same context to
179 * express something different. 179​ * express something different.
180 */ 180​ **/
181 VisitedText = 4, 181​ VisitedText = 4,
182 /** 182​ /**
183 * Sixth color; for example, errors, untrusted content, deletions, 183​ * Sixth color; for example, errors, untrusted content, deletions,
184 * etc. 184​ * etc.
185 */ 185​ **/
186 NegativeText = 5, 186​ NegativeText = 5,
187 /** 187​ /**
188 * Seventh color; for example, warnings, secure/encrypted content. 188​ * Seventh color; for example, warnings, secure/encrypted content.
189 */ 189​ **/
190 NeutralText = 6, 190​ NeutralText = 6,
191 /** 191​ /**
192 * Eigth color; for example, additions, success messages, trusted 192​ * Eigth color; for example, additions, success messages, trusted
193 * content. 193​ * content.
194 */ 194​ **/
195 PositiveText = 7 195​ PositiveText = 7
196 }; 196​ };
197 /** 197​ /**
198 * Retrieve the requested shade color, using the specified color as the 198​ * Retrieve the requested shade color, using the specified color as the
199 * base color and the system contrast setting. 199​ * base color and the system contrast setting.
200 * 200​ *
201 * @note Shades are chosen such that all shades would contrast with the 201​ * @note Shades are chosen such that all shades would contrast with the
202 * base color. This means that if base is very dark, the 'dark' shades will 202​ * base color. This means that if base is very dark, the 'dark' shades will
203 * be lighter than the base color, with midlight() == shadow(). 203​ * be lighter than the base color, with midlight() == shadow().
204 * Conversely, if the base color is very light, the 'light' shades will be 204​ * Conversely, if the base color is very light, the 'light' shades will be
205 * darker than the base color, with light() == mid(). 205​ * darker than the base color, with light() == mid().
206 */ 206​ **/
207 Q_INVOKABLE QColor shade(const QColor& color, ShadeRole role); 207​ Q_INVOKABLE QColor shade(const QColor& color, ShadeRole role);
208 Q_INVOKABLE QColor shade(const QColor& color, ShadeRole role, qreal contrast); /** 208​ Q_INVOKABLE QColor shade(const QColor& color, ShadeRole role, qreal contrast);
209​ /**
209 * Retrieve the requested shade color, using the specified color as the 210​ * Retrieve the requested shade color, using the specified color as the
210 * base color and the specified contrast. 211​ * base color and the specified contrast.
211 * 212​ *
212 * @param contrast Amount roughly specifying the contrast by which to 213​ * @param contrast Amount roughly specifying the contrast by which to
213 * adjust the base color, between -1.0 and 1.0 (values between 0.0 and 1.0 214​ * adjust the base color, between -1.0 and 1.0 (values between 0.0 and 1.0
214 * correspond to the value from KGlobalSettings::contrastF) 215​ * correspond to the value from KGlobalSettings::contrastF)
215 * 216​ *
216 * @note Shades are chosen such that all shades would contrast with the 217​ * @note Shades are chosen such that all shades would contrast with the
217 * base color. This means that if base is very dark, the 'dark' shades will 218​ * base color. This means that if base is very dark, the 'dark' shades will
218 * be lighter than the base color, with midlight() == shadow(). 219​ * be lighter than the base color, with midlight() == shadow().
219 * Conversely, if the base color is very light, the 'light' shades will be 220​ * Conversely, if the base color is very light, the 'light' shades will be
220 * darker than the base color, with light() == mid(). 221​ * darker than the base color, with light() == mid().
221 * 222​ *
222 * @see KColorUtils::shade 223​ * @see KColorUtils::shade
223 */ 224​ **/
224 Q_INVOKABLE QColor multiplyAlpha(const QColor& color, qreal alpha); 225​ Q_INVOKABLE QColor multiplyAlpha(const QColor& color, qreal alpha);
225 /** 226​ /**
226 * Retrieve the requested background brush's color for the @p active button. 227​ * Retrieve the requested background brush's color for the @p active button.
227 * @param active Whether the active or inactive palette should be used. 228​ * @param active Whether the active or inactive palette should be used.
228 */ 229​ **/
229 Q_INVOKABLE QColor background(bool active, BackgroundRole role = NormalBackground) const; 230​ Q_INVOKABLE QColor background(bool active, BackgroundRole role = NormalBackground) const;
230 231​
231 /** 232​ /**
232 * Retrieve the requested foreground brush's color for the @p active button. 233​ * Retrieve the requested foreground brush's color for the @p active button.
233 * @param active Whether the active or inactive palette should be used. 234​ * @param active Whether the active or inactive palette should be used.
234 */ 235​ **/
235 Q_INVOKABLE QColor foreground(bool active, ForegroundRole role = NormalText) const; 236​ Q_INVOKABLE QColor foreground(bool active, ForegroundRole role = NormalText) const;
236 237​
237 qreal contrast() const; 238​ qreal contrast() const;
238}; 239​};
239 240​
240#endif 241​#endif