KSyntaxHighlighting

theme.h
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.
81 //! Text style for function definitions and function calls.
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.
87 //! Text style for control flow highlighting, such as @e if, @e then,
88 //! @e else, @e return, or @e continue.
90 //! Text style for operators such as +, -, *, / and :: etc.
92 //! Text style for built-in language classes and functions.
94 //! Text style for well-known extensions, such as Qt or boost.
96 //! Text style for preprocessor statements.
98 //! Text style for attributes of functions or objects, e.g. \@override
99 //! in Java, or __declspec(...) and __attribute__((...)) in C++.
101 //! Text style for single characters such as 'a'.
103 //! Text style for escaped characters in strings, such as "hello\n".
105 //! Text style for strings, for instance "hello world".
107 //! Text style for verbatim strings such as HERE docs.
109 //! Text style for special strings such as regular expressions in
110 //! ECMAScript or the LaTeX math mode.
112 //! Text style for includes, imports, modules, or LaTeX packages.
114 //! Text style for data types such as int, char, float etc.
116 //! Text style for decimal values.
118 //! Text style for numbers with base other than 10.
120 //! Text style for floating point numbers.
122 //! Text style for language constants, e.g. True, False, None in Python
123 //! or nullptr in C/C++.
125 //! Text style for normal comments.
127 //! Text style for comments that reflect API documentation, such as
128 //! doxygen /** */ comments.
130 //! Text style for annotations in comments, such as \@param in Doxygen
131 //! or JavaDoc.
133 //! Text style that refers to variables in a comment, such as after
134 //! \@param <identifier> in Doxygen or JavaDoc.
136 //! Text style for region markers, typically defined by BEGIN/END.
138 //! Text style for information, such as the keyword \@note in Doxygen.
140 //! Text style for warnings, such as the keyword \@warning in Doxygen.
142 //! Text style for comment specials such as TODO and WARNING in
143 //! comments.
145 //! Text style indicating wrong syntax.
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 */
159 //! Background color for the editing area.
160 BackgroundColor = 0,
161 //! Background color for selected text.
163 //! Background color for the line of the current text cursor.
165 //! Background color for matching text while searching.
167 //! Background color for replaced text for a search & replace action.
169 //! Background color for matching bracket pairs (including quotes)
171 //! Foreground color for visualizing tabs and trailing spaces.
173 //! Color used to underline spell check errors.
175 //! Color used to draw vertical indentation levels, typically a line.
177 //! Background color for the icon border.
179 //! Background colors for code folding regions in the text area, as well
180 //! as code folding indicators in the code folding border.
182 //! Foreground color for drawing the line numbers. This should have a
183 //! good contrast with the IconBorder background color.
185 //! Foreground color for drawing the current line number. This should
186 //! have a good contrast with the IconBorder background color.
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.
192 //! Color used to draw a vertical line for marking changed lines.
194 //! Color used to draw a vertical line for marking saved lines.
196 //! Line color used to draw separator lines, e.g. at column 80 in the
197 //! text editor area.
199 //! Background color for bookmarks.
201 //! Background color for active breakpoints.
203 //! Background color for a reached breakpoint.
205 //! Background color for inactive (disabled) breakpoints.
207 //! Background color for marking the current execution position.
209 //! Background color for general warning marks.
211 //! Background color for general error marks.
213 //! Background color for text templates (snippets).
215 //! Background color for all editable placeholders in text templates.
217 //! Background color for the currently active placeholder in text
218 //! templates.
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 */
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 */
349};
350
351}
352
353QT_BEGIN_NAMESPACE
354Q_DECLARE_TYPEINFO(KSyntaxHighlighting::Theme, Q_RELOCATABLE_TYPE);
355QT_END_NAMESPACE
356
357#endif // KSYNTAXHIGHLIGHTING_THEME_H
Color theme definition used for highlighting.
Definition theme.h:65
Theme(const Theme &copy)
Copy constructor, sharing the Theme data with copy.
EditorColorRole
Editor color roles, used to paint line numbers, editor background etc.
Definition theme.h:158
@ IndentationLine
Color used to draw vertical indentation levels, typically a line.
Definition theme.h:176
@ CodeFolding
Background colors for code folding regions in the text area, as well as code folding indicators in th...
Definition theme.h:181
@ MarkWarning
Background color for general warning marks.
Definition theme.h:210
@ SpellChecking
Color used to underline spell check errors.
Definition theme.h:174
@ MarkBookmark
Background color for bookmarks.
Definition theme.h:200
@ MarkBreakpointReached
Background color for a reached breakpoint.
Definition theme.h:204
@ SavedLines
Color used to draw a vertical line for marking saved lines.
Definition theme.h:195
@ TemplateFocusedPlaceholder
Background color for the currently active placeholder in text templates.
Definition theme.h:219
@ MarkError
Background color for general error marks.
Definition theme.h:212
@ CurrentLineNumber
Foreground color for drawing the current line number.
Definition theme.h:187
@ TemplateBackground
Background color for text templates (snippets).
Definition theme.h:214
@ MarkBreakpointDisabled
Background color for inactive (disabled) breakpoints.
Definition theme.h:206
@ IconBorder
Background color for the icon border.
Definition theme.h:178
@ Separator
Line color used to draw separator lines, e.g.
Definition theme.h:198
@ TabMarker
Foreground color for visualizing tabs and trailing spaces.
Definition theme.h:172
@ SearchHighlight
Background color for matching text while searching.
Definition theme.h:166
@ TextSelection
Background color for selected text.
Definition theme.h:162
@ ReplaceHighlight
Background color for replaced text for a search & replace action.
Definition theme.h:168
@ BracketMatching
Background color for matching bracket pairs (including quotes)
Definition theme.h:170
@ MarkBreakpointActive
Background color for active breakpoints.
Definition theme.h:202
@ ModifiedLines
Color used to draw a vertical line for marking changed lines.
Definition theme.h:193
@ LineNumbers
Foreground color for drawing the line numbers.
Definition theme.h:184
@ TemplatePlaceholder
Background color for all editable placeholders in text templates.
Definition theme.h:216
@ MarkExecution
Background color for marking the current execution position.
Definition theme.h:208
@ CurrentLine
Background color for the line of the current text cursor.
Definition theme.h:164
@ WordWrapMarker
Color used in the icon border to indicate dynamically wrapped lines.
Definition theme.h:191
Theme & operator=(const Theme &other)
Assignment operator, sharing the Theme data with other.
TextStyle
Default styles that can be referenced from syntax definition XML files.
Definition theme.h:75
@ Import
Text style for includes, imports, modules, or LaTeX packages.
Definition theme.h:113
@ Attribute
Text style for attributes of functions or objects, e.g.
Definition theme.h:100
@ BaseN
Text style for numbers with base other than 10.
Definition theme.h:119
@ CommentVar
Text style that refers to variables in a comment, such as after @param <identifier> in Doxygen or Jav...
Definition theme.h:135
@ Comment
Text style for normal comments.
Definition theme.h:126
@ SpecialString
Text style for special strings such as regular expressions in ECMAScript or the LaTeX math mode.
Definition theme.h:111
@ Char
Text style for single characters such as 'a'.
Definition theme.h:102
@ Warning
Text style for warnings, such as the keyword @warning in Doxygen.
Definition theme.h:141
@ Error
Text style indicating wrong syntax.
Definition theme.h:146
@ Preprocessor
Text style for preprocessor statements.
Definition theme.h:97
@ Constant
Text style for language constants, e.g.
Definition theme.h:124
@ Float
Text style for floating point numbers.
Definition theme.h:121
@ Keyword
Text style for language keywords.
Definition theme.h:80
@ VerbatimString
Text style for verbatim strings such as HERE docs.
Definition theme.h:108
@ Extension
Text style for well-known extensions, such as Qt or boost.
Definition theme.h:95
@ ControlFlow
Text style for control flow highlighting, such as if, then, else, return, or continue.
Definition theme.h:89
@ DecVal
Text style for decimal values.
Definition theme.h:117
@ BuiltIn
Text style for built-in language classes and functions.
Definition theme.h:93
@ DataType
Text style for data types such as int, char, float etc.
Definition theme.h:115
@ Documentation
Text style for comments that reflect API documentation, such as doxygen /‍** *‍/ comments.
Definition theme.h:129
@ SpecialChar
Text style for escaped characters in strings, such as "hello\n".
Definition theme.h:104
@ RegionMarker
Text style for region markers, typically defined by BEGIN/END.
Definition theme.h:137
@ Information
Text style for information, such as the keyword @note in Doxygen.
Definition theme.h:139
@ String
Text style for strings, for instance "hello world".
Definition theme.h:106
@ Function
Text style for function definitions and function calls.
Definition theme.h:82
@ Alert
Text style for comment specials such as TODO and WARNING in comments.
Definition theme.h:144
@ Variable
Text style for variables, if applicable.
Definition theme.h:86
@ Annotation
Text style for annotations in comments, such as @param in Doxygen or JavaDoc.
Definition theme.h:132
@ Operator
Text style for operators such as +, -, *, / and :: etc.
Definition theme.h:91
Syntax highlighting engine for Kate syntax definitions.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 21 2024 11:55:27 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.