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
17namespace KSyntaxHighlighting
18{
19class ThemeData;
20class 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 */
68class 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)
81public:
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 Comment,
185 Documentation,
186 Annotation,
187 CommentVar,
188 RegionMarker,
189 Information,
190 Warning,
191 Alert,
192 Error,
193 Others
194 };
195 Q_ENUM(TextStyle)
196
197 /*!
198 * Editor color roles, used to paint line numbers, editor background etc.
199 * The colors typically should have good contrast with the colors used
200 * in the TextStyle%s.
201 *
202 * \value BackgroundColor
203 * Background color for the editing area.
204 * \value TextSelection
205 * Background color for selected text.
206 * \value CurrentLine
207 * Background color for the line of the current text cursor.
208 * \value SearchHighlight
209 * Background color for matching text while searching.
210 * \value ReplaceHighlight
211 * Background color for replaced text for a search & replace action.
212 * \value BracketMatching
213 * Background color for matching bracket pairs (including quotes).
214 * \value TabMarker
215 * Foreground color for visualizing tabs and trailing spaces.
216 * \value SpellChecking
217 * Color used to underline spell check errors.
218 * \value IndentationLine
219 * Color used to draw vertical indentation levels, typically a line.
220 * \value IconBorder
221 * Background color for the icon border.
222 * \value CodeFolding
223 * Background colors for code folding regions in the text area, as well
224 * as code folding indicators in the code folding border.
225 * \value LineNumbers
226 * Foreground color for drawing the line numbers. This should have a
227 * good contrast with the IconBorder background color.
228 * \value CurrentLineNumber
229 * Foreground color for drawing the current line number. This should
230 * have a good contrast with the IconBorder background color.
231 * \value WordWrapMarker
232 * Color used in the icon border to indicate dynamically wrapped lines.
233 * This color should have a good contrast with the IconBorder
234 * background color.
235 * \value ModifiedLines
236 * Color used to draw a vertical line for marking changed lines.
237 * \value SavedLines
238 * Color used to draw a vertical line for marking saved lines.
239 * \value Separator
240 * Line color used to draw separator lines, e.g. at column 80 in the
241 * text editor area.
242 * \value MarkBookmark
243 * Background color for bookmarks.
244 * \value MarkBreakpointActive
245 * Background color for active breakpoints.
246 * \value MarkBreakpointReached
247 * Background color for a reached breakpoint.
248 * \value MarkBreakpointDisabled
249 * Background color for inactive (disabled) breakpoints.
250 * \value MarkExecution
251 * Background color for marking the current execution position.
252 * \value MarkWarning
253 * Background color for general warning marks.
254 * \value MarkError
255 * Background color for general error marks.
256 * \value TemplateBackground
257 * Background color for text templates (snippets).
258 * \value TemplatePlaceholder
259 * Background color for all editable placeholders in text templates.
260 * \value TemplateFocusedPlaceholder
261 * Background color for the currently active placeholder in text
262 * templates.
263 * \value TemplateReadOnlyPlaceholder
264 * Background color for read-only placeholders in text templates.
265 */
266 enum EditorColorRole {
267 BackgroundColor = 0,
268 TextSelection,
269 CurrentLine,
270 SearchHighlight,
271 ReplaceHighlight,
272 BracketMatching,
273 TabMarker,
274 SpellChecking,
275 IndentationLine,
276 IconBorder,
277 CodeFolding,
278 LineNumbers,
279 CurrentLineNumber,
280 WordWrapMarker,
281 ModifiedLines,
282 SavedLines,
283 Separator,
284 MarkBookmark,
285 MarkBreakpointActive,
286 MarkBreakpointReached,
287 MarkBreakpointDisabled,
288 MarkExecution,
289 MarkWarning,
290 MarkError,
291 TemplateBackground,
292 TemplatePlaceholder,
293 TemplateFocusedPlaceholder,
294 TemplateReadOnlyPlaceholder
295 };
296 Q_ENUM(EditorColorRole)
297
298 /*!
299 * Default constructor, creating an invalid Theme, see isValid().
300 */
301 Theme();
302
303 /*!
304 * Copy constructor, sharing the Theme data with \a copy.
305 */
306 Theme(const Theme &copy);
307
308 ~Theme();
309
310 /*!
311 * Assignment operator, sharing the Theme data with \a other.
312 */
313 Theme &operator=(const Theme &other);
314
315 /*!
316 * Returns \c true if this is a valid Theme.
317 * If the theme is invalid, none of the returned colors are well-defined.
318 */
319 bool isValid() const;
320
321 /*!
322 * Returns the unique name of this Theme.
323 * \sa translatedName()
324 */
325 QString name() const;
326
327 /*!
328 * Returns the translated name of this Theme. The translated name can be
329 * used in the user interface.
330 */
331 QString translatedName() const;
332
333 /*!
334 * Returns \c true if this Theme is read-only.
335 *
336 * A Theme is read-only, if the filePath() points to a non-writable file.
337 * This is typically the case for Themes that are compiled into the executable
338 * as resource file, as well as for theme files that are installed in read-only
339 * system locations (e.g. /usr/share/).
340 */
341 bool isReadOnly() const;
342
343 /*!
344 * Returns the full path and file name to this Theme.
345 * Themes from the Qt resource return the Qt resource path.
346 * Themes from disk return the local path.
347 *
348 * If the theme is invalid (isValid()), an empty string is returned.
349 */
350 QString filePath() const;
351
352 /*!
353 * Returns the text color to be used for \a style.
354 * \c 0 is returned for styles that do not specify a text color,
355 * use the default text color in that case.
356 */
357 QRgb textColor(TextStyle style) const;
358
359 /*!
360 * Returns the selected text color to be used for \a style.
361 * \c 0 is returned for styles that do not specify a selected text color,
362 * use the default textColor() in that case.
363 */
364 QRgb selectedTextColor(TextStyle style) const;
365
366 /*!
367 * Returns the background color to be used for \a style.
368 * \c 0 is returned for styles that do not specify a background color,
369 * use the default background color in that case.
370 */
371 QRgb backgroundColor(TextStyle style) const;
372
373 /*!
374 * Returns the background color to be used for selected text for \a style.
375 * \c 0 is returned for styles that do not specify a background color,
376 * use the default backgroundColor() in that case.
377 */
378 QRgb selectedBackgroundColor(TextStyle style) const;
379
380 /*!
381 * Returns whether the given style should be shown in bold.
382 */
383 bool isBold(TextStyle style) const;
384
385 /*!
386 * Returns whether the given style should be shown in italic.
387 */
388 bool isItalic(TextStyle style) const;
389
390 /*!
391 * Returns whether the given style should be shown underlined.
392 */
393 bool isUnderline(TextStyle style) const;
394
395 /*!
396 * Returns whether the given style should be shown struck through.
397 */
398 bool isStrikeThrough(TextStyle style) const;
399
400public:
401 /*!
402 * Returns the editor color for the requested \a role.
403 */
404 QRgb editorColor(EditorColorRole role) const;
405
406private:
407 /*!
408 * Constructor taking a shared ThemeData instance.
409 */
410 KSYNTAXHIGHLIGHTING_NO_EXPORT explicit Theme(ThemeData *data);
411 friend class RepositoryPrivate;
412 friend class ThemeData;
413
414private:
415 /*!
416 * Shared data holder.
417 */
418 QExplicitlySharedDataPointer<ThemeData> m_data;
419};
420
421}
422
423QT_BEGIN_NAMESPACE
424Q_DECLARE_TYPEINFO(KSyntaxHighlighting::Theme, Q_RELOCATABLE_TYPE);
425QT_END_NAMESPACE
426
427#endif // KSYNTAXHIGHLIGHTING_THEME_H
428

source code of syntax-highlighting/src/lib/theme.h