Search for usage in LXR

KSyntaxHighlighting::AbstractHighlighter Class Referenceabstract

#include <abstracthighlighter.h>

Inheritance diagram for KSyntaxHighlighting::AbstractHighlighter:

Public Member Functions

Definition definition () const
virtual void setDefinition (const Definition &def)
virtual void setTheme (const Theme &theme)
Theme theme () const

Protected Member Functions

KSYNTAXHIGHLIGHTING_NO_EXPORT 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 (QStringView text, const State &state)

Protected Attributes

AbstractHighlighterPrivate * d_ptr

Detailed Description

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.

Implementing your own Syntax Highlighter

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.

The Format class itself depends on the current Theme. A theme must be initially set once such that the Formats instances can be queried for concrete colors.

Optionally, you can also reimplement setTheme() and setDefinition() to get notified whenever the Definition or the Theme changes.

See also

Definition at line 71 of file abstracthighlighter.h.

Member Function Documentation

◆ applyFolding()

void AbstractHighlighter::applyFolding ( int  offset,
int  length,
FoldingRegion  region 

Reimplement this to apply folding to your output.

The provided FoldingRegion region either stars or ends a code folding region in the interval [offset, offset + length).

offsetThe start column of the FoldingRegion
lengthThe length of the matching text that starts / ends a folding region
regionThe FoldingRegion that applies to the range [offset, offset + length)
The FoldingRegion region is always either of type FoldingRegion::Type::Begin or FoldingRegion::Type::End.
See also
applyFormat(), highlightLine(), FoldingRegion

Reimplemented in KSyntaxHighlighting::SyntaxHighlighter.

Definition at line 416 of file abstracthighlighter.cpp.

◆ applyFormat()

virtual void KSyntaxHighlighting::AbstractHighlighter::applyFormat ( int  offset,
int  length,
const Format format 
protectedpure virtual

Reimplement this to apply formats to your output.

The provided format is valid for the interval [offset, offset + length).

offsetThe start column of the interval for which format matches
lengthThe length of the matching text
formatThe Format that applies to the range [offset, offset + length)
Make sure to set a valid Definition, otherwise the parameter format is invalid for the entire line passed to highlightLine() (cf. Format::isValid()).
See also
applyFolding(), highlightLine()

Implemented in KSyntaxHighlighting::SyntaxHighlighter.

◆ definition()

Definition AbstractHighlighter::definition ( ) const

Returns the syntax definition used for highlighting.

See also

Definition at line 63 of file abstracthighlighter.cpp.

◆ highlightLine()

State AbstractHighlighter::highlightLine ( QStringView  text,
const State state 

Highlight the given line.

Call this from your derived class where appropriate. This will result in any number of applyFormat() and applyFolding() calls as a result.

textA string containing the text of the line to highlight.
stateThe 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 highlighting 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.
See also
applyFormat(), applyFolding()

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

Definition at line 107 of file abstracthighlighter.cpp.

◆ setDefinition()

void AbstractHighlighter::setDefinition ( const Definition def)

Sets the syntax definition used for highlighting.

Subclasses can re-implement this method to e.g. trigger re-highlighting or clear internal data structures if needed.

Reimplemented in KSyntaxHighlighting::SyntaxHighlighter.

Definition at line 68 of file abstracthighlighter.cpp.

◆ setTheme()

void AbstractHighlighter::setTheme ( const Theme theme)

Sets the theme used for highlighting.

Subclasses can re-implement this method to e.g. trigger re-highlighing or to do general palette color setup.

Definition at line 80 of file abstracthighlighter.cpp.

◆ theme()

Theme AbstractHighlighter::theme ( ) const

Returns the currently selected theme for highlighting.

If no Theme was set through setTheme(), the returned Theme will be invalid, see Theme::isValid().

Definition at line 74 of file abstracthighlighter.cpp.

The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon May 8 2023 04:03:37 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.