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

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