1/*
2 SPDX-FileCopyrightText: 2016 Volker Krause <[email protected]>
3
4 SPDX-License-Identifier: MIT
5*/
6
7#ifndef KSYNTAXHIGHLIGHTING_ABSTRACTHIGHLIGHTERM_H
8#define KSYNTAXHIGHLIGHTING_ABSTRACTHIGHLIGHTERM_H
9
10#include "definition.h"
11#include "ksyntaxhighlighting_export.h"
12
13#include <QObject>
14#include <QStringView>
15
16namespace KSyntaxHighlighting
17{
18class AbstractHighlighterPrivate;
19class FoldingRegion;
20class Format;
21class State;
22class Theme;
23
24/*!
25 * \class KSyntaxHighlighting::AbstractHighlighter
26 * \inheaderfile KSyntaxHighlighting/AbstractHighlighter
27 * \inmodule KSyntaxHighlighting
28 *
29 * \brief Abstract base class for highlighters.
30 *
31 * The AbstractHighlighter provides an interface to highlight text.
32 *
33 * The SyntaxHighlighting framework already ships with one implementation,
34 * namely the SyntaxHighlighter, which also derives from QSyntaxHighlighter,
35 * meaning that it can be used to highlight a QTextDocument or a QML TextEdit.
36 * In order to use the SyntaxHighlighter, just call setDefinition() and
37 * setTheme(), and the associated documents will automatically be highlighted.
38 *
39 * However, if you want to use the SyntaxHighlighting framework to implement
40 * your own syntax highlighter, you need to sublcass from AbstractHighlighter.
41 *
42 * In order to implement your own syntax highlighter, you need to inherit from
43 * AbstractHighlighter. Then, pass each text line that needs to be highlighted
44 * in order to highlightLine(). Internally, highlightLine() uses the Definition
45 * initially set through setDefinition() and the State of the previous text line
46 * to parse and highlight the given text line. For each visual highlighting
47 * change, highlightLine() will call applyFormat(). Therefore, reimplement
48 * applyFormat() to get notified of the Format that is valid in the range
49 * starting at the given offset with the specified length. Similarly, for each
50 * text part that starts or ends a code folding region, highlightLine() will
51 * call applyFolding(). Therefore, if you are interested in code folding,
52 * reimplement applyFolding() to get notified of the starting and ending code
53 * folding regions, again specified in the range starting at the given offset
54 * with the given length.
55 *
56 * The Format class itself depends on the current Theme. A theme must be
57 * initially set once such that the Format%s instances can be queried for
58 * concrete colors.
59 *
60 * Optionally, you can also reimplement setTheme() and setDefinition() to get
61 * notified whenever the Definition or the Theme changes.
62 *
63 * \sa SyntaxHighlighter
64 * \since 5.28
65 */
66class KSYNTAXHIGHLIGHTING_EXPORT AbstractHighlighter
67{
68public:
69 virtual ~AbstractHighlighter();
70
71 /*!
72 * Returns the syntax definition used for highlighting.
73 *
74 * \sa setDefinition()
75 */
76 Definition definition() const;
77
78 /*!
79 * Sets the syntax definition used for highlighting.
80 *
81 * Subclasses can re-implement this method to e.g. trigger
82 * re-highlighting or clear internal data structures if needed.
83 */
84 virtual void setDefinition(const Definition &def);
85
86 /*!
87 * Returns the currently selected theme for highlighting.
88 *
89 * \note If no Theme was set through setTheme(), the returned Theme will be
90 * invalid, see Theme::isValid().
91 */
92 Theme theme() const;
93
94 /*!
95 * Sets the theme used for highlighting.
96 *
97 * Subclasses can re-implement this method to e.g. trigger
98 * re-highlighing or to do general palette color setup.
99 */
100 virtual void setTheme(const Theme &theme);
101
102protected:
103 /*!
104 */
105 AbstractHighlighter();
106
107 KSYNTAXHIGHLIGHTING_NO_EXPORT explicit AbstractHighlighter(AbstractHighlighterPrivate *dd);
108
109 /*!
110 * Highlight the given line. Call this from your derived class
111 * where appropriate. This will result in any number of applyFormat()
112 * and applyFolding() calls as a result.
113 *
114 * \a text A string containing the text of the line to highlight.
115 *
116 * \a state The highlighting state handle returned by the call
117 * to highlightLine() for the previous line. For the very first line,
118 * just pass a default constructed State().
119 *
120 * Returns The state of the highlighting engine after processing the
121 * given line. This needs to passed into highlightLine() for the
122 * next line. You can store the state for efficient partial
123 * re-highlighting for example during editing.
124 *
125 * \sa applyFormat(), applyFolding()
126 */
127 State highlightLine(QStringView text, const State &state);
128
129 /*!
130 * Reimplement this to apply formats to your output. The provided \a format
131 * is valid for the interval [ \a offset, \a offset + \a length).
132 *
133 * \a offset The start column of the interval for which \a format matches
134 *
135 * \a length The length of the matching text
136 *
137 * \a format The Format that applies to the range [offset, offset + length)
138 *
139 * \note Make sure to set a valid Definition, otherwise the parameter
140 * \a format is invalid for the entire line passed to highlightLine()
141 * (cf. Format::isValid()).
142 *
143 * \sa applyFolding(), highlightLine()
144 */
145 virtual void applyFormat(int offset, int length, const Format &format) = 0;
146
147 /*!
148 * Reimplement this to apply folding to your output. The provided
149 * FoldingRegion \a region either stars or ends a code folding region in the
150 * interval [ \a offset, \a offset + \a length).
151 *
152 * \a offset The start column of the FoldingRegion
153 *
154 * \a length The length of the matching text that starts / ends a
155 * folding region
156 *
157 * \a region The FoldingRegion that applies to the range [offset, offset + length)
158 *
159 * \note The FoldingRegion \a region is @e always either of type
160 * FoldingRegion::Type::Begin or FoldingRegion::Type::End.
161 *
162 * \sa applyFormat(), highlightLine(), FoldingRegion
163 */
164 virtual void applyFolding(int offset, int length, FoldingRegion region);
165
166protected:
167 AbstractHighlighterPrivate *d_ptr;
168
169private:
170 Q_DECLARE_PRIVATE(AbstractHighlighter)
171 Q_DISABLE_COPY(AbstractHighlighter)
172};
173}
174
175QT_BEGIN_NAMESPACE
176Q_DECLARE_INTERFACE(KSyntaxHighlighting::AbstractHighlighter, "org.kde.SyntaxHighlighting.AbstractHighlighter")
177QT_END_NAMESPACE
178
179#endif // KSYNTAXHIGHLIGHTING_ABSTRACTHIGHLIGHTERM_H
180

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