File indexing completed on 2024-05-12 04:02:16
0001 /* 0002 SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org> 0003 0004 SPDX-License-Identifier: MIT 0005 */ 0006 0007 #ifndef KSYNTAXHIGHLIGHTING_ABSTRACTHIGHLIGHTERM_H 0008 #define KSYNTAXHIGHLIGHTING_ABSTRACTHIGHLIGHTERM_H 0009 0010 #include "definition.h" 0011 #include "ksyntaxhighlighting_export.h" 0012 0013 #include <QObject> 0014 #include <QStringView> 0015 0016 namespace KSyntaxHighlighting 0017 { 0018 class AbstractHighlighterPrivate; 0019 class FoldingRegion; 0020 class Format; 0021 class State; 0022 class Theme; 0023 0024 /** 0025 * Abstract base class for highlighters. 0026 * 0027 * @section abshl_intro Introduction 0028 * 0029 * The AbstractHighlighter provides an interface to highlight text. 0030 * 0031 * The SyntaxHighlighting framework already ships with one implementation, 0032 * namely the SyntaxHighlighter, which also derives from QSyntaxHighlighter, 0033 * meaning that it can be used to highlight a QTextDocument or a QML TextEdit. 0034 * In order to use the SyntaxHighlighter, just call setDefinition() and 0035 * setTheme(), and the associated documents will automatically be highlighted. 0036 * 0037 * However, if you want to use the SyntaxHighlighting framework to implement 0038 * your own syntax highlighter, you need to sublcass from AbstractHighlighter. 0039 * 0040 * @section abshl_impl Implementing your own Syntax Highlighter 0041 * 0042 * In order to implement your own syntax highlighter, you need to inherit from 0043 * AbstractHighlighter. Then, pass each text line that needs to be highlighted 0044 * in order to highlightLine(). Internally, highlightLine() uses the Definition 0045 * initially set through setDefinition() and the State of the previous text line 0046 * to parse and highlight the given text line. For each visual highlighting 0047 * change, highlightLine() will call applyFormat(). Therefore, reimplement 0048 * applyFormat() to get notified of the Format that is valid in the range 0049 * starting at the given offset with the specified length. Similarly, for each 0050 * text part that starts or ends a code folding region, highlightLine() will 0051 * call applyFolding(). Therefore, if you are interested in code folding, 0052 * reimplement applyFolding() to get notified of the starting and ending code 0053 * folding regions, again specified in the range starting at the given offset 0054 * with the given length. 0055 * 0056 * The Format class itself depends on the current Theme. A theme must be 0057 * initially set once such that the Format%s instances can be queried for 0058 * concrete colors. 0059 * 0060 * Optionally, you can also reimplement setTheme() and setDefinition() to get 0061 * notified whenever the Definition or the Theme changes. 0062 * 0063 * @see SyntaxHighlighter 0064 * @since 5.28 0065 */ 0066 class KSYNTAXHIGHLIGHTING_EXPORT AbstractHighlighter 0067 { 0068 public: 0069 virtual ~AbstractHighlighter(); 0070 0071 /** 0072 * Returns the syntax definition used for highlighting. 0073 * 0074 * @see setDefinition() 0075 */ 0076 Definition definition() const; 0077 0078 /** 0079 * Sets the syntax definition used for highlighting. 0080 * 0081 * Subclasses can re-implement this method to e.g. trigger 0082 * re-highlighting or clear internal data structures if needed. 0083 */ 0084 virtual void setDefinition(const Definition &def); 0085 0086 /** 0087 * Returns the currently selected theme for highlighting. 0088 * 0089 * @note If no Theme was set through setTheme(), the returned Theme will be 0090 * invalid, see Theme::isValid(). 0091 */ 0092 Theme theme() const; 0093 0094 /** 0095 * Sets the theme used for highlighting. 0096 * 0097 * Subclasses can re-implement this method to e.g. trigger 0098 * re-highlighing or to do general palette color setup. 0099 */ 0100 virtual void setTheme(const Theme &theme); 0101 0102 protected: 0103 AbstractHighlighter(); 0104 KSYNTAXHIGHLIGHTING_NO_EXPORT explicit AbstractHighlighter(AbstractHighlighterPrivate *dd); 0105 0106 /** 0107 * Highlight the given line. Call this from your derived class 0108 * where appropriate. This will result in any number of applyFormat() 0109 * and applyFolding() calls as a result. 0110 * @param text A string containing the text of the line to highlight. 0111 * @param state The highlighting state handle returned by the call 0112 * to highlightLine() for the previous line. For the very first line, 0113 * just pass a default constructed State(). 0114 * @returns The state of the highlighting engine after processing the 0115 * given line. This needs to passed into highlightLine() for the 0116 * next line. You can store the state for efficient partial 0117 * re-highlighting for example during editing. 0118 * 0119 * @see applyFormat(), applyFolding() 0120 */ 0121 State highlightLine(QStringView text, const State &state); 0122 0123 /** 0124 * Reimplement this to apply formats to your output. The provided @p format 0125 * is valid for the interval [@p offset, @p offset + @p length). 0126 * 0127 * @param offset The start column of the interval for which @p format matches 0128 * @param length The length of the matching text 0129 * @param format The Format that applies to the range [offset, offset + length) 0130 * 0131 * @note Make sure to set a valid Definition, otherwise the parameter 0132 * @p format is invalid for the entire line passed to highlightLine() 0133 * (cf. Format::isValid()). 0134 * 0135 * @see applyFolding(), highlightLine() 0136 */ 0137 virtual void applyFormat(int offset, int length, const Format &format) = 0; 0138 0139 /** 0140 * Reimplement this to apply folding to your output. The provided 0141 * FoldingRegion @p region either stars or ends a code folding region in the 0142 * interval [@p offset, @p offset + @p length). 0143 * 0144 * @param offset The start column of the FoldingRegion 0145 * @param length The length of the matching text that starts / ends a 0146 * folding region 0147 * @param region The FoldingRegion that applies to the range [offset, offset + length) 0148 * 0149 * @note The FoldingRegion @p region is @e always either of type 0150 * FoldingRegion::Type::Begin or FoldingRegion::Type::End. 0151 * 0152 * @see applyFormat(), highlightLine(), FoldingRegion 0153 */ 0154 virtual void applyFolding(int offset, int length, FoldingRegion region); 0155 0156 protected: 0157 AbstractHighlighterPrivate *d_ptr; 0158 0159 private: 0160 Q_DECLARE_PRIVATE(AbstractHighlighter) 0161 Q_DISABLE_COPY(AbstractHighlighter) 0162 }; 0163 } 0164 0165 QT_BEGIN_NAMESPACE 0166 Q_DECLARE_INTERFACE(KSyntaxHighlighting::AbstractHighlighter, "org.kde.SyntaxHighlighting.AbstractHighlighter") 0167 QT_END_NAMESPACE 0168 0169 #endif // KSYNTAXHIGHLIGHTING_ABSTRACTHIGHLIGHTERM_H