KSyntaxHighlighting

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

KDE's Doxygen guidelines are available online.