1/*
2 SPDX-FileCopyrightText: 2016 Volker Krause <[email protected]>
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 * \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 &copy);
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
402public:
403 /*!
404 * Returns the editor color for the requested \a role.
405 */
406 QRgb editorColor(EditorColorRole role) const;
407
408private:
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
416private:
417 /*!
418 * Shared data holder.
419 */
420 QExplicitlySharedDataPointer<ThemeData> m_data;
421};
422
423}
424
425QT_BEGIN_NAMESPACE
426Q_DECLARE_TYPEINFO(KSyntaxHighlighting::Theme, Q_RELOCATABLE_TYPE);
427QT_END_NAMESPACE
428
429#endif // KSYNTAXHIGHLIGHTING_THEME_H
430

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