1/*
2 SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org>
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 * Abstract base class for highlighters.
26 *
27 * @section abshl_intro Introduction
28 *
29 * The AbstractHighlighter provides an interface to highlight text.
30 *
31 * The SyntaxHighlighting framework already ships with one implementation,
32 * namely the SyntaxHighlighter, which also derives from QSyntaxHighlighter,
33 * meaning that it can be used to highlight a QTextDocument or a QML TextEdit.
34 * In order to use the SyntaxHighlighter, just call setDefinition() and
35 * setTheme(), and the associated documents will automatically be highlighted.
36 *
37 * However, if you want to use the SyntaxHighlighting framework to implement
38 * your own syntax highlighter, you need to sublcass from AbstractHighlighter.
39 *
40 * @section abshl_impl Implementing your own Syntax Highlighter
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 * @see 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 * @see 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 AbstractHighlighter();
104 KSYNTAXHIGHLIGHTING_NO_EXPORT explicit AbstractHighlighter(AbstractHighlighterPrivate *dd);
105
106 /**
107 * Highlight the given line. Call this from your derived class
108 * where appropriate. This will result in any number of applyFormat()
109 * and applyFolding() calls as a result.
110 * @param text A string containing the text of the line to highlight.
111 * @param state The highlighting state handle returned by the call
112 * to highlightLine() for the previous line. For the very first line,
113 * just pass a default constructed State().
114 * @returns The state of the highlighting engine after processing the
115 * given line. This needs to passed into highlightLine() for the
116 * next line. You can store the state for efficient partial
117 * re-highlighting for example during editing.
118 *
119 * @see applyFormat(), applyFolding()
120 */
121 State highlightLine(QStringView text, const State &state);
122
123 /**
124 * Reimplement this to apply formats to your output. The provided @p format
125 * is valid for the interval [@p offset, @p offset + @p length).
126 *
127 * @param offset The start column of the interval for which @p format matches
128 * @param length The length of the matching text
129 * @param format The Format that applies to the range [offset, offset + length)
130 *
131 * @note Make sure to set a valid Definition, otherwise the parameter
132 * @p format is invalid for the entire line passed to highlightLine()
133 * (cf. Format::isValid()).
134 *
135 * @see applyFolding(), highlightLine()
136 */
137 virtual void applyFormat(int offset, int length, const Format &format) = 0;
138
139 /**
140 * Reimplement this to apply folding to your output. The provided
141 * FoldingRegion @p region either stars or ends a code folding region in the
142 * interval [@p offset, @p offset + @p length).
143 *
144 * @param offset The start column of the FoldingRegion
145 * @param length The length of the matching text that starts / ends a
146 * folding region
147 * @param region The FoldingRegion that applies to the range [offset, offset + length)
148 *
149 * @note The FoldingRegion @p region is @e always either of type
150 * FoldingRegion::Type::Begin or FoldingRegion::Type::End.
151 *
152 * @see applyFormat(), highlightLine(), FoldingRegion
153 */
154 virtual void applyFolding(int offset, int length, FoldingRegion region);
155
156protected:
157 AbstractHighlighterPrivate *d_ptr;
158
159private:
160 Q_DECLARE_PRIVATE(AbstractHighlighter)
161 Q_DISABLE_COPY(AbstractHighlighter)
162};
163}
164
165QT_BEGIN_NAMESPACE
166Q_DECLARE_INTERFACE(KSyntaxHighlighting::AbstractHighlighter, "org.kde.SyntaxHighlighting.AbstractHighlighter")
167QT_END_NAMESPACE
168
169#endif // KSYNTAXHIGHLIGHTING_ABSTRACTHIGHLIGHTERM_H
170

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