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

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