|Definition||definition () const|
|virtual void||setDefinition (const Definition &def)|
|virtual void||setTheme (const Theme &theme)|
|Theme||theme () const|
|AbstractHighlighter (AbstractHighlighterPrivate *dd)|
|virtual void||applyFolding (int offset, int length, FoldingRegion region)|
|virtual void||applyFormat (int offset, int length, const Format &format)=0|
|State||highlightLine (const QString &text, const State &state)|
Abstract base class for highlighters.
The AbstractHighlighter provides an interface to highlight text.
The SyntaxHighlighting framework already ships with one implementation, namely the SyntaxHighlighter, which also derives from QSyntaxHighlighter, meaning that it can be used to highlight a QTextDocument or a QML TextEdit. In order to use the SyntaxHighlighter, just call setDefinition() and setTheme(), and the associated documents will automatically be highlighted.
However, if you want to use the SyntaxHighlighting framework to implement your own syntax highlighter, you need to sublcass from AbstractHighlighter.
In order to implement your own syntax highlighter, you need to inherit from AbstractHighlighter. Then, pass each text line that needs to be highlighted in order to highlightLine(). Internally, highlightLine() uses the Definition initially set through setDefinition() and the State of the previous text line to parse and highlight the given text line. For each visual highlighting change, highlightLine() will call applyFormat(). Therefore, reimplement applyFormat() to get notified of the Format that is valid in the range starting at the given offset with the specified length. Similarly, for each text part that starts or ends a code folding region, highlightLine() will call applyFolding(). Therefore, if you are interested in code folding, reimplement applyFolding() to get notified of the starting and ending code folding regions, again specified in the range starting at the given offset with the given length.
- See also
Member Function Documentation
Reimplement this to apply folding to your output.
The provided FoldingRegion
region either stars or ends a code folding region in the interval [
offset The start column of the FoldingRegion length The length of the matching text that starts / ends a folding region region The FoldingRegion that applies to the range [offset, offset + length)
- The FoldingRegion
regionis always either of type FoldingRegion::Type::Begin or FoldingRegion::Type::End.
Reimplemented in KSyntaxHighlighting::SyntaxHighlighter.
Reimplement this to apply formats to your output.
format is valid for the interval [
offset The start column of the interval for which
length The length of the matching text format The Format that applies to the range [offset, offset + length)
- Make sure to set a valid Definition, otherwise the parameter
formatis invalid for the entire line passed to highlightLine() (cf. Format::isValid()).
Implemented in KSyntaxHighlighting::SyntaxHighlighter.
Highlight the given line.
text A string containing the text of the line to highlight. state The highlighting state handle returned by the call to highlightLine() for the previous line. For the very first line, just pass a default constructed State().
- The state of the highlighing engine after processing the given line. This needs to passed into highlightLine() for the next line. You can store the state for efficient partial re-highlighting for example during editing.
handle line empty context switches guard against endless loops see https://phabricator.kde.org/D18509
line empty context switches
end when trying to #pop the main context
line end context switches only when lineEmptyContext is #stay. This avoids skipping empty lines after a line continuation character (see bug 405903)
for expensive rules like regexes we do:
- match them for the complete line, as this is faster than re-trying them at all positions
- store the result of the first position that matches (or -1 for no match in the full line) in the skipOffsets hash for re-use
- have capturesForLastDynamicSkipOffset as guard for dynamic regexes to invalidate the cache if they might have changed
current active format stored as pointer to avoid deconstruction/constructions inside the internal loop the pointers are stable, the formats are either in the contexts or rules
cached first non-space character, needs to be computed if < 0
avoid that we loop endless for some broken hl definitions
try to match all rules in the context in order of declaration in XML
filter out rules that require a specific column
filter out rules that only match for leading whitespace
compute the first non-space lazy avoids computing it for contexts without any such rules
can we skip?
shall we skip application of this rule? two cases:
- rule can't match at all => currentSkipOffset < 0
- rule will only match for some higher offset => currentSkipOffset > offset
we need to invalidate this if we are dynamic and have different captures then last time
update skip offset if new one rules out any later match or is larger than current one
apply folding. special cases:
- rule with endRegion + beginRegion: in endRegion, the length is 0
- rule with lookAhead: length is 0
if we arrive here, some new format has to be set!
on format change, apply the last one and switch to new one
we must have made progress if we arrive here!
apply format for remaining text, if any
handle line end context switches guard against endless loops see https://phabricator.kde.org/D18509
The documentation for this class was generated from the following files: