1 | /* |
2 | SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org> |
3 | |
4 | SPDX-License-Identifier: MIT |
5 | */ |
6 | |
7 | #ifndef KSYNTAXHIGHLIGHTING_THEME_H |
8 | #define KSYNTAXHIGHLIGHTING_THEME_H |
9 | |
10 | #include "ksyntaxhighlighting_export.h" |
11 | |
12 | #include <QColor> |
13 | #include <QExplicitlySharedDataPointer> |
14 | #include <QTypeInfo> |
15 | #include <qobjectdefs.h> |
16 | |
17 | namespace KSyntaxHighlighting |
18 | { |
19 | class ThemeData; |
20 | class RepositoryPrivate; |
21 | |
22 | /*! |
23 | * \class KSyntaxHighlighting::Theme |
24 | * \inheaderfile KSyntaxHighlighting/Theme |
25 | * \inmodule KSyntaxHighlighting |
26 | * |
27 | * \brief Color theme definition used for highlighting. |
28 | * |
29 | * The Theme provides a full color theme for painting the highlighted text. |
30 | * One Theme is defined either as a *.theme file on disk, or as a file compiled |
31 | * into the SyntaxHighlighting library by using Qt's resource system. Each |
32 | * Theme has a unique name(), including a translatedName() if put into the UI. |
33 | * Themes shipped by default are typically read-only, see isReadOnly(). |
34 | * |
35 | * A Theme defines two sets of colors: |
36 | * \list |
37 | * \li Text colors, including foreground and background colors, colors for |
38 | * selected text, and properties such as bold and italic. These colors are |
39 | * used e.g. by the SyntaxHighlighter. |
40 | * \li Editor colors, including a background color for the entire editor widget, |
41 | * the line number color, code folding colors, etc. |
42 | * \endlist |
43 | * |
44 | * \section1 Text Colors and the Class Format |
45 | * |
46 | * The text colors are used for syntax highlighting. |
47 | * // TODO: elaborate more and explain relation to Format class |
48 | * |
49 | * \section1 theme_editor_colors Editor Colors |
50 | * |
51 | * If you want to use the SyntaxHighlighting framework to write your own text |
52 | * editor, you also need to paint the background of the editing widget. In |
53 | * addition, the editor may support showing line numbers, a folding bar, a |
54 | * highlight for the current text line, and similar features. All these colors |
55 | * are defined in terms of the "editor colors" and accessible by calling |
56 | * editorColor() with the desired enum EditorColorRole. |
57 | * |
58 | * \section1 Accessing a Theme |
59 | * |
60 | * All available Theme%s are accessed through the Repository. These themes are |
61 | * typically valid themes. If you create a Theme on your own, isValid() will |
62 | * return \c false, and all colors provided by this Theme are in fact invalid |
63 | * and therefore unusable. |
64 | * |
65 | * \sa Format |
66 | * \since 5.28 |
67 | */ |
68 | class KSYNTAXHIGHLIGHTING_EXPORT Theme |
69 | { |
70 | Q_GADGET |
71 | |
72 | /*! |
73 | * \property KSyntaxHighlighting::Theme::name |
74 | */ |
75 | Q_PROPERTY(QString name READ name) |
76 | |
77 | /*! |
78 | * \property KSyntaxHighlighting::Theme::translatedName |
79 | */ |
80 | Q_PROPERTY(QString translatedName READ translatedName) |
81 | public: |
82 | /*! |
83 | * Default styles that can be referenced from syntax definition XML files. |
84 | * Make sure to choose readable colors with good contrast especially in |
85 | * combination with the EditorColorRole%s. |
86 | * |
87 | * \value Normal |
88 | * Default text style for normal text and source code without |
89 | * special highlighting. |
90 | * \value Keyword |
91 | * Text style for language keywords. |
92 | * \value Function |
93 | * Text style for function definitions and function calls. |
94 | * \value Variable |
95 | * Text style for variables, if applicable. For instance, variables in |
96 | * PHP typically start with a '$', so all identifiers following the |
97 | * pattern $foo are highlighted as variable. |
98 | * \value ControlFlow |
99 | * Text style for control flow highlighting, such as if, then, |
100 | * else, return, or continue. |
101 | * \value Operator |
102 | * Text style for operators such as +, -, *, / and :: etc. |
103 | * \value BuiltIn |
104 | * Text style for built-in language classes and functions. |
105 | * \value Extension |
106 | * Text style for well-known extensions, such as Qt or boost. |
107 | * \value Preprocessor |
108 | * Text style for preprocessor statements. |
109 | * \value Attribute |
110 | * Text style for attributes of functions or objects, e.g. \@override |
111 | * in Java, or __declspec(...) and __attribute__((...)) in C++. |
112 | * \value Char |
113 | * Text style for single characters such as 'a'. |
114 | * \value SpecialChar |
115 | * Text style for escaped characters in strings, such as "hello\n". |
116 | * \value String |
117 | * Text style for strings, for instance "hello world". |
118 | * \value VerbatimString |
119 | * Text style for verbatim strings such as HERE docs. |
120 | * \value SpecialString |
121 | * Text style for special strings such as regular expressions in |
122 | * ECMAScript or the LaTeX math mode. |
123 | * \value Import |
124 | * Text style for includes, imports, modules, or LaTeX packages. |
125 | * \value DataType |
126 | * Text style for data types such as int, char, float etc. |
127 | * \value DecVal |
128 | * Text style for decimal values. |
129 | * \value BaseN |
130 | * Text style for numbers with base other than 10. |
131 | * \value Float |
132 | * Text style for floating point numbers. |
133 | * \value Constant |
134 | * Text style for language constants, e.g. True, False, None in Python |
135 | * or nullptr in C/C++. |
136 | * \value Comment |
137 | * Text style for normal comments. |
138 | * \value Documentation |
139 | * Text style for comments that reflect API documentation, such as |
140 | * doxygen comments. |
141 | * \value Annotation |
142 | * Text style for annotations in comments, such as \a in Doxygen |
143 | * or JavaDoc. |
144 | * \value CommentVar |
145 | * Text style that refers to variables in a comment, such as after |
146 | * \a \<identifier\> in Doxygen or JavaDoc. |
147 | * \value RegionMarker |
148 | * Text style for region markers, typically defined by BEGIN/END. |
149 | * \value Information |
150 | * Text style for information, such as the keyword \\note in Doxygen. |
151 | * \value Warning |
152 | * Text style for warnings, such as the keyword \\warning in Doxygen. |
153 | * \value Alert |
154 | * Text style for comment specials such as TODO and WARNING in |
155 | * comments. |
156 | * \value Error |
157 | * Text style indicating wrong syntax. |
158 | * \value Others |
159 | * Text style for attributes that do not match any of the other default |
160 | * styles. |
161 | */ |
162 | enum TextStyle { |
163 | Normal = 0, |
164 | Keyword, |
165 | Function, |
166 | Variable, |
167 | ControlFlow, |
168 | Operator, |
169 | BuiltIn, |
170 | Extension, |
171 | Preprocessor, |
172 | Attribute, |
173 | Char, |
174 | SpecialChar, |
175 | String, |
176 | VerbatimString, |
177 | SpecialString, |
178 | Import, |
179 | DataType, |
180 | DecVal, |
181 | BaseN, |
182 | Float, |
183 | Constant, |
184 | , |
185 | Documentation, |
186 | Annotation, |
187 | , |
188 | RegionMarker, |
189 | Information, |
190 | Warning, |
191 | Alert, |
192 | Error, |
193 | Others |
194 | }; |
195 | Q_ENUM(TextStyle) |
196 | |
197 | /*! |
198 | * \enum EditorColorRole |
199 | * |
200 | * Editor color roles, used to paint line numbers, editor background etc. |
201 | * The colors typically should have good contrast with the colors used |
202 | * in the TextStyle%s. |
203 | * |
204 | * \value BackgroundColor |
205 | * Background color for the editing area. |
206 | * \value TextSelection |
207 | * Background color for selected text. |
208 | * \value CurrentLine |
209 | * Background color for the line of the current text cursor. |
210 | * \value SearchHighlight |
211 | * Background color for matching text while searching. |
212 | * \value ReplaceHighlight |
213 | * Background color for replaced text for a search & replace action. |
214 | * \value BracketMatching |
215 | * Background color for matching bracket pairs (including quotes). |
216 | * \value TabMarker |
217 | * Foreground color for visualizing tabs and trailing spaces. |
218 | * \value SpellChecking |
219 | * Color used to underline spell check errors. |
220 | * \value IndentationLine |
221 | * Color used to draw vertical indentation levels, typically a line. |
222 | * \value IconBorder |
223 | * Background color for the icon border. |
224 | * \value CodeFolding |
225 | * Background colors for code folding regions in the text area, as well |
226 | * as code folding indicators in the code folding border. |
227 | * \value LineNumbers |
228 | * Foreground color for drawing the line numbers. This should have a |
229 | * good contrast with the IconBorder background color. |
230 | * \value CurrentLineNumber |
231 | * Foreground color for drawing the current line number. This should |
232 | * have a good contrast with the IconBorder background color. |
233 | * \value WordWrapMarker |
234 | * Color used in the icon border to indicate dynamically wrapped lines. |
235 | * This color should have a good contrast with the IconBorder |
236 | * background color. |
237 | * \value ModifiedLines |
238 | * Color used to draw a vertical line for marking changed lines. |
239 | * \value SavedLines |
240 | * Color used to draw a vertical line for marking saved lines. |
241 | * \value Separator |
242 | * Line color used to draw separator lines, e.g. at column 80 in the |
243 | * text editor area. |
244 | * \value MarkBookmark |
245 | * Background color for bookmarks. |
246 | * \value MarkBreakpointActive |
247 | * Background color for active breakpoints. |
248 | * \value MarkBreakpointReached |
249 | * Background color for a reached breakpoint. |
250 | * \value MarkBreakpointDisabled |
251 | * Background color for inactive (disabled) breakpoints. |
252 | * \value MarkExecution |
253 | * Background color for marking the current execution position. |
254 | * \value MarkWarning |
255 | * Background color for general warning marks. |
256 | * \value MarkError |
257 | * Background color for general error marks. |
258 | * \value TemplateBackground |
259 | * Background color for text templates (snippets). |
260 | * \value TemplatePlaceholder |
261 | * Background color for all editable placeholders in text templates. |
262 | * \value TemplateFocusedPlaceholder |
263 | * Background color for the currently active placeholder in text |
264 | * templates. |
265 | * \value TemplateReadOnlyPlaceholder |
266 | * Background color for read-only placeholders in text templates. |
267 | */ |
268 | enum EditorColorRole { |
269 | BackgroundColor = 0, |
270 | TextSelection, |
271 | CurrentLine, |
272 | SearchHighlight, |
273 | ReplaceHighlight, |
274 | BracketMatching, |
275 | TabMarker, |
276 | SpellChecking, |
277 | IndentationLine, |
278 | IconBorder, |
279 | CodeFolding, |
280 | LineNumbers, |
281 | CurrentLineNumber, |
282 | WordWrapMarker, |
283 | ModifiedLines, |
284 | SavedLines, |
285 | Separator, |
286 | MarkBookmark, |
287 | MarkBreakpointActive, |
288 | MarkBreakpointReached, |
289 | MarkBreakpointDisabled, |
290 | MarkExecution, |
291 | MarkWarning, |
292 | MarkError, |
293 | TemplateBackground, |
294 | TemplatePlaceholder, |
295 | TemplateFocusedPlaceholder, |
296 | TemplateReadOnlyPlaceholder |
297 | }; |
298 | Q_ENUM(EditorColorRole) |
299 | |
300 | /*! |
301 | * Default constructor, creating an invalid Theme, see isValid(). |
302 | */ |
303 | Theme(); |
304 | |
305 | /*! |
306 | * Copy constructor, sharing the Theme data with \a copy. |
307 | */ |
308 | Theme(const Theme ©); |
309 | |
310 | ~Theme(); |
311 | |
312 | /*! |
313 | * Assignment operator, sharing the Theme data with \a other. |
314 | */ |
315 | Theme &operator=(const Theme &other); |
316 | |
317 | /*! |
318 | * Returns \c true if this is a valid Theme. |
319 | * If the theme is invalid, none of the returned colors are well-defined. |
320 | */ |
321 | bool isValid() const; |
322 | |
323 | /*! |
324 | * Returns the unique name of this Theme. |
325 | * \sa translatedName() |
326 | */ |
327 | QString name() const; |
328 | |
329 | /*! |
330 | * Returns the translated name of this Theme. The translated name can be |
331 | * used in the user interface. |
332 | */ |
333 | QString translatedName() const; |
334 | |
335 | /*! |
336 | * Returns \c true if this Theme is read-only. |
337 | * |
338 | * A Theme is read-only, if the filePath() points to a non-writable file. |
339 | * This is typically the case for Themes that are compiled into the executable |
340 | * as resource file, as well as for theme files that are installed in read-only |
341 | * system locations (e.g. /usr/share/). |
342 | */ |
343 | bool isReadOnly() const; |
344 | |
345 | /*! |
346 | * Returns the full path and file name to this Theme. |
347 | * Themes from the Qt resource return the Qt resource path. |
348 | * Themes from disk return the local path. |
349 | * |
350 | * If the theme is invalid (isValid()), an empty string is returned. |
351 | */ |
352 | QString filePath() const; |
353 | |
354 | /*! |
355 | * Returns the text color to be used for \a style. |
356 | * \c 0 is returned for styles that do not specify a text color, |
357 | * use the default text color in that case. |
358 | */ |
359 | QRgb textColor(TextStyle style) const; |
360 | |
361 | /*! |
362 | * Returns the selected text color to be used for \a style. |
363 | * \c 0 is returned for styles that do not specify a selected text color, |
364 | * use the default textColor() in that case. |
365 | */ |
366 | QRgb selectedTextColor(TextStyle style) const; |
367 | |
368 | /*! |
369 | * Returns the background color to be used for \a style. |
370 | * \c 0 is returned for styles that do not specify a background color, |
371 | * use the default background color in that case. |
372 | */ |
373 | QRgb backgroundColor(TextStyle style) const; |
374 | |
375 | /*! |
376 | * Returns the background color to be used for selected text for \a style. |
377 | * \c 0 is returned for styles that do not specify a background color, |
378 | * use the default backgroundColor() in that case. |
379 | */ |
380 | QRgb selectedBackgroundColor(TextStyle style) const; |
381 | |
382 | /*! |
383 | * Returns whether the given style should be shown in bold. |
384 | */ |
385 | bool isBold(TextStyle style) const; |
386 | |
387 | /*! |
388 | * Returns whether the given style should be shown in italic. |
389 | */ |
390 | bool isItalic(TextStyle style) const; |
391 | |
392 | /*! |
393 | * Returns whether the given style should be shown underlined. |
394 | */ |
395 | bool isUnderline(TextStyle style) const; |
396 | |
397 | /*! |
398 | * Returns whether the given style should be shown struck through. |
399 | */ |
400 | bool isStrikeThrough(TextStyle style) const; |
401 | |
402 | public: |
403 | /*! |
404 | * Returns the editor color for the requested \a role. |
405 | */ |
406 | QRgb editorColor(EditorColorRole role) const; |
407 | |
408 | private: |
409 | /*! |
410 | * Constructor taking a shared ThemeData instance. |
411 | */ |
412 | KSYNTAXHIGHLIGHTING_NO_EXPORT explicit Theme(ThemeData *data); |
413 | friend class RepositoryPrivate; |
414 | friend class ThemeData; |
415 | |
416 | private: |
417 | /*! |
418 | * Shared data holder. |
419 | */ |
420 | QExplicitlySharedDataPointer<ThemeData> m_data; |
421 | }; |
422 | |
423 | } |
424 | |
425 | QT_BEGIN_NAMESPACE |
426 | Q_DECLARE_TYPEINFO(KSyntaxHighlighting::Theme, Q_RELOCATABLE_TYPE); |
427 | QT_END_NAMESPACE |
428 | |
429 | #endif // KSYNTAXHIGHLIGHTING_THEME_H |
430 | |