KSyntaxHighlighting::AbstractHighlighter Class
class KSyntaxHighlighting::AbstractHighlighterAbstract base class for highlighters. More...
| Header: | #include <KSyntaxHighlighting/AbstractHighlighter> |
| CMake: | find_package(KF6 REQUIRED COMPONENTS KSyntaxHighlighting)target_link_libraries(mytarget PRIVATE KF6::KSyntaxHighlighting) |
| Since: | 5.28 |
| Inherited By: |
Public Functions
| KSyntaxHighlighting::Definition | definition() const |
| virtual void | setDefinition(const KSyntaxHighlighting::Definition &def) |
| virtual void | setTheme(const KSyntaxHighlighting::Theme &theme) |
| KSyntaxHighlighting::Theme | theme() const |
Protected Functions
| AbstractHighlighter() | |
| virtual void | applyFolding(int offset, int length, KSyntaxHighlighting::FoldingRegion region) |
| virtual void | applyFormat(int offset, int length, const KSyntaxHighlighting::Format &format) = 0 |
| KSyntaxHighlighting::State | highlightLine(QStringView text, const KSyntaxHighlighting::State &state) |
Detailed Description
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.
The Format class itself depends on the current Theme. A theme must be initially set once such that the Format%s 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 SyntaxHighlighter.
Member Function Documentation
[protected] AbstractHighlighter::AbstractHighlighter()
[virtual protected] void AbstractHighlighter::applyFolding(int offset, int length, KSyntaxHighlighting::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).
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)
Note: The FoldingRegion region is @e always either of type FoldingRegion::Type::Begin or FoldingRegion::Type::End.
See also applyFormat(), highlightLine(), and FoldingRegion.
[pure virtual protected] void AbstractHighlighter::applyFormat(int offset, int length, const KSyntaxHighlighting::Format &format)
Reimplement this to apply formats to your output. The provided format is valid for the interval [ offset, offset + length).
offset The start column of the interval for which format matches
length The length of the matching text
format The Format that applies to the range [offset, offset + length)
Note: 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() and highlightLine().
KSyntaxHighlighting::Definition AbstractHighlighter::definition() const
Returns the syntax definition used for highlighting.
See also setDefinition().
[protected] KSyntaxHighlighting::State AbstractHighlighter::highlightLine(QStringView text, const KSyntaxHighlighting::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.
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().
Returns 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() and applyFolding().
[virtual] void AbstractHighlighter::setDefinition(const KSyntaxHighlighting::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.
See also definition().
[virtual] void AbstractHighlighter::setTheme(const KSyntaxHighlighting::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.
See also theme().
KSyntaxHighlighting::Theme AbstractHighlighter::theme() const
Returns the currently selected theme for highlighting.
Note: If no Theme was set through setTheme(), the returned Theme will be invalid, see Theme::isValid().
See also setTheme().