KSyntaxHighlighting

format.h
1/*
2 SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org>
3 SPDX-FileCopyrightText: 2020 Jonathan Poelen <jonathan.poelen@gmail.com>
4
5 SPDX-License-Identifier: MIT
6*/
7
8#ifndef KSYNTAXHIGHLIGHTING_FORMAT_H
9#define KSYNTAXHIGHLIGHTING_FORMAT_H
10
11#include "ksyntaxhighlighting_export.h"
12#include "theme.h"
13
14#include <QExplicitlySharedDataPointer>
15
16namespace KSyntaxHighlighting
17{
18class FormatPrivate;
19
20/** Describes the format to be used for a specific text fragment.
21 * The actual format used for displaying is merged from the format information
22 * in the syntax definition file, and a theme.
23 *
24 * @see Theme
25 * @since 5.28
26 */
27class KSYNTAXHIGHLIGHTING_EXPORT Format
28{
29public:
30 /** Creates an empty/invalid format. */
31 Format();
32 Format(const Format &other);
33 ~Format();
34
35 Format &operator=(const Format &other);
36
37 /** Returns @c true if this is a valid format, ie. one that
38 * was read from a syntax definition file.
39 */
40 bool isValid() const;
41
42 /** The name of this format as used in the syntax definition file. */
43 QString name() const;
44
45 /** Returns a unique identifier of this format.
46 * This is useful for efficient storing of formats in a text line. The
47 * identifier is unique per Repository instance, but will change when
48 * the repository is reloaded (which also invalidatess the corresponding
49 * Definition anyway).
50 */
51 int id() const;
52
53 /** Returns the underlying TextStyle of this Format.
54 * Every Theme::TextStyle is visually defined by a Theme. A Format uses one
55 * of the Theme::TextStyle%s and on top allows modifications such as setting
56 * a different foreground color etc.
57 * @see Theme::TextStyle
58 * @since 5.49
59 */
60 Theme::TextStyle textStyle() const;
61
62 /** Returns @c true if the combination of this format and the theme @p theme
63 * do not change the default text format in any way.
64 * This is useful for output formats where changing formatting implies cost,
65 * and thus benefit from optimizing the default case of not having any format
66 * applied. If you make use of this, make sure to set the default text style
67 * to what the corresponding theme sets for Theme::Normal.
68 */
69 bool isDefaultTextStyle(const Theme &theme) const;
70
71 /** Returns @c true if the combination of this format and the theme @p theme
72 * change the foreground color compared to the default format.
73 */
74 bool hasTextColor(const Theme &theme) const;
75 /** Returns the foreground color of the combination of this format and the
76 * given theme.
77 */
78 QColor textColor(const Theme &theme) const;
79 /** Returns the foreground color for selected text of the combination of
80 * this format and the given theme.
81 */
82 QColor selectedTextColor(const Theme &theme) const;
83 /** Returns @c true if the combination of this format and the theme @p theme
84 * change the background color compared to the default format.
85 */
86 bool hasBackgroundColor(const Theme &theme) const;
87 /** Returns the background color of the combination of this format and the
88 * given theme.
89 */
90 QColor backgroundColor(const Theme &theme) const;
91 /** Returns the background color of selected text of the combination of
92 * this format and the given theme.
93 */
94 QColor selectedBackgroundColor(const Theme &theme) const;
95
96 /** Returns @c true if the combination of this format and the given theme
97 * results in bold text formatting.
98 */
99 bool isBold(const Theme &theme) const;
100 /** Returns @c true if the combination of this format and the given theme
101 * results in italic text formatting.
102 */
103 bool isItalic(const Theme &theme) const;
104 /** Returns @c true if the combination of this format and the given theme
105 * results in underlined text.
106 */
107 bool isUnderline(const Theme &theme) const;
108 /** Returns @c true if the combination of this format and the given theme
109 * results in struck through text.
110 */
111 bool isStrikeThrough(const Theme &theme) const;
112
113 /**
114 * Returns whether characters with this format should be spell checked.
115 */
116 bool spellCheck() const;
117
118 /** Returns @c true if the syntax definition file sets a value for the bold text
119 * attribute and, therefore, overrides the theme and the default formatting
120 * style. If the return is @p true, this value is obtained by isBold().
121 * @see isBold()
122 * @since 5.62
123 */
124 bool hasBoldOverride() const;
125
126 /** Returns @c true if the syntax definition file sets a value for the italic text
127 * attribute and, therefore, overrides the theme and the default formatting style.
128 * If the return is @p true, this value is obtained by isItalic().
129 * @see isItalic()
130 * @since 5.62
131 */
132 bool hasItalicOverride() const;
133
134 /** Returns @c true if the syntax definition file sets a value for the underlined
135 * text attribute and, therefore, overrides the theme and the default formatting
136 * style. If the return is @p true, this value is obtained by isUnderline().
137 * @see isUnderline()
138 * @since 5.62
139 */
140 bool hasUnderlineOverride() const;
141
142 /** Returns @c true if the syntax definition file specifies a value for the
143 * struck through text attribute. If the return is @p true, this value
144 * is obtained by isStrikeThrough().
145 * @see isStrikeThrough()
146 * @since 5.62
147 */
148 bool hasStrikeThroughOverride() const;
149
150 /** Returns @c true if the syntax definition file sets a value for the foreground
151 * text color attribute and, therefore, overrides the theme and the default formatting
152 * style. If the return is @p true, this value is obtained by textColor().
153 * @see textColor(), hasTextColor()
154 * @since 5.62
155 */
156 bool hasTextColorOverride() const;
157
158 /** Returns @c true if the syntax definition file sets a value for the background
159 * color attribute and, therefore, overrides the theme and the default formatting
160 * style. If the return is @p true, this value is obtained by backgroundColor().
161 * @see backgroundColor(), hasBackgroundColor()
162 * @since 5.62
163 */
164 bool hasBackgroundColorOverride() const;
165
166 /** Returns @c true if the syntax definition file specifies a value for the
167 * selected text color attribute. If the return is @p true, this value is
168 * obtained by selectedTextColor().
169 * @see selectedTextColor()
170 * @since 5.62
171 */
172 bool hasSelectedTextColorOverride() const;
173
174 /** Returns @c true if the syntax definition file specifies a value for the
175 * selected background color attribute. If the return is @p true, this
176 * value is obtained by selectedBackgroundColor().
177 * @see selectedBackgroundColor()
178 * @since 5.62
179 */
180 bool hasSelectedBackgroundColorOverride() const;
181
182private:
183 friend class FormatPrivate;
185};
186}
187
188QT_BEGIN_NAMESPACE
189Q_DECLARE_TYPEINFO(KSyntaxHighlighting::Format, Q_RELOCATABLE_TYPE);
190QT_END_NAMESPACE
191
192#endif // KSYNTAXHIGHLIGHTING_FORMAT_H
Describes the format to be used for a specific text fragment.
Definition format.h:28
Color theme definition used for highlighting.
Definition theme.h:65
TextStyle
Default styles that can be referenced from syntax definition XML files.
Definition theme.h:75
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 May 17 2024 11:49:59 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.