KSyntaxHighlighting

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

KDE's Doxygen guidelines are available online.