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 // TODO KF6: add an optional void* context argument that is passed through
107 // to the applyX() calls, so highlighters dealing with some form of line object
108 // (such as QSyntaxHighlighter or KTextEditor) can avoid some ugly hacks to have
109 // this context available in their applyX methods
110 /**
111 * Highlight the given line. Call this from your derived class
112 * where appropriate. This will result in any number of applyFormat()
113 * and applyFolding() calls as a result.
114 * @param text A string containing the text of the line to highlight.
115 * @param state The highlighting state handle returned by the call
116 * to highlightLine() for the previous line. For the very first line,
117 * just pass a default constructed State().
118 * @returns The state of the highlighting engine after processing the
119 * given line. This needs to passed into highlightLine() for the
120 * next line. You can store the state for efficient partial
121 * re-highlighting for example during editing.
122 *
123 * @see applyFormat(), applyFolding()
124 */
125 State highlightLine(QStringView text, const State &state);
126
127 /**
128 * Reimplement this to apply formats to your output. The provided @p format
129 * is valid for the interval [@p offset, @p offset + @p length).
130 *
131 * @param offset The start column of the interval for which @p format matches
132 * @param length The length of the matching text
133 * @param format The Format that applies to the range [offset, offset + length)
134 *
135 * @note Make sure to set a valid Definition, otherwise the parameter
136 * @p format is invalid for the entire line passed to highlightLine()
137 * (cf. Format::isValid()).
138 *
139 * @see applyFolding(), highlightLine()
140 */
141 virtual void applyFormat(int offset, int length, const Format &format) = 0;
142
143 /**
144 * Reimplement this to apply folding to your output. The provided
145 * FoldingRegion @p region either stars or ends a code folding region in the
146 * interval [@p offset, @p offset + @p length).
147 *
148 * @param offset The start column of the FoldingRegion
149 * @param length The length of the matching text that starts / ends a
150 * folding region
151 * @param region The FoldingRegion that applies to the range [offset, offset + length)
152 *
153 * @note The FoldingRegion @p region is @e always either of type
154 * FoldingRegion::Type::Begin or FoldingRegion::Type::End.
155 *
156 * @see applyFormat(), highlightLine(), FoldingRegion
157 */
158 virtual void applyFolding(int offset, int length, FoldingRegion region);
159
160protected:
161 AbstractHighlighterPrivate *d_ptr;
162
163private:
164 Q_DECLARE_PRIVATE(AbstractHighlighter)
165 Q_DISABLE_COPY(AbstractHighlighter)
166};
167}
168
169QT_BEGIN_NAMESPACE
170Q_DECLARE_INTERFACE(KSyntaxHighlighting::AbstractHighlighter, "org.kde.SyntaxHighlighting.AbstractHighlighter")
171QT_END_NAMESPACE
172
173#endif // KSYNTAXHIGHLIGHTING_ABSTRACTHIGHLIGHTERM_H
174

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