File indexing completed on 2024-05-12 04:02:20
0001 /* 0002 SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org> 0003 0004 SPDX-License-Identifier: MIT 0005 */ 0006 0007 #ifndef KSYNTAXHIGHLIGHTING_THEME_H 0008 #define KSYNTAXHIGHLIGHTING_THEME_H 0009 0010 #include "ksyntaxhighlighting_export.h" 0011 0012 #include <QColor> 0013 #include <QExplicitlySharedDataPointer> 0014 #include <QTypeInfo> 0015 #include <qobjectdefs.h> 0016 0017 namespace KSyntaxHighlighting 0018 { 0019 class ThemeData; 0020 class RepositoryPrivate; 0021 0022 /** 0023 * Color theme definition used for highlighting. 0024 * 0025 * @section theme_intro Introduction 0026 * 0027 * The Theme provides a full color theme for painting the highlighted text. 0028 * One Theme is defined either as a *.theme file on disk, or as a file compiled 0029 * into the SyntaxHighlighting library by using Qt's resource system. Each 0030 * Theme has a unique name(), including a translatedName() if put into the UI. 0031 * Themes shipped by default are typically read-only, see isReadOnly(). 0032 * 0033 * A Theme defines two sets of colors: 0034 * - Text colors, including foreground and background colors, colors for 0035 * selected text, and properties such as bold and italic. These colors are 0036 * used e.g. by the SyntaxHighlighter. 0037 * - Editor colors, including a background color for the entire editor widget, 0038 * the line number color, code folding colors, etc. 0039 * 0040 * @section theme_text_colors Text Colors and the Class Format 0041 * 0042 * The text colors are used for syntax highlighting. 0043 * // TODO: elaborate more and explain relation to Format class 0044 * 0045 * @section theme_editor_colors Editor Colors 0046 * 0047 * If you want to use the SyntaxHighlighting framework to write your own text 0048 * editor, you also need to paint the background of the editing widget. In 0049 * addition, the editor may support showing line numbers, a folding bar, a 0050 * highlight for the current text line, and similar features. All these colors 0051 * are defined in terms of the "editor colors" and accessible by calling 0052 * editorColor() with the desired enum EditorColorRole. 0053 * 0054 * @section theme_access Accessing a Theme 0055 * 0056 * All available Theme%s are accessed through the Repository. These themes are 0057 * typically valid themes. If you create a Theme on your own, isValid() will 0058 * return @e false, and all colors provided by this Theme are in fact invalid 0059 * and therefore unusable. 0060 * 0061 * @see Format 0062 * @since 5.28 0063 */ 0064 class KSYNTAXHIGHLIGHTING_EXPORT Theme 0065 { 0066 Q_GADGET 0067 Q_PROPERTY(QString name READ name) 0068 Q_PROPERTY(QString translatedName READ translatedName) 0069 public: 0070 /** 0071 * Default styles that can be referenced from syntax definition XML files. 0072 * Make sure to choose readable colors with good contrast especially in 0073 * combination with the EditorColorRole%s. 0074 */ 0075 enum TextStyle { 0076 //! Default text style for normal text and source code without 0077 //! special highlighting. 0078 Normal = 0, 0079 //! Text style for language keywords. 0080 Keyword, 0081 //! Text style for function definitions and function calls. 0082 Function, 0083 //! Text style for variables, if applicable. For instance, variables in 0084 //! PHP typically start with a '$', so all identifiers following the 0085 //! pattern $foo are highlighted as variable. 0086 Variable, 0087 //! Text style for control flow highlighting, such as @e if, @e then, 0088 //! @e else, @e return, or @e continue. 0089 ControlFlow, 0090 //! Text style for operators such as +, -, *, / and :: etc. 0091 Operator, 0092 //! Text style for built-in language classes and functions. 0093 BuiltIn, 0094 //! Text style for well-known extensions, such as Qt or boost. 0095 Extension, 0096 //! Text style for preprocessor statements. 0097 Preprocessor, 0098 //! Text style for attributes of functions or objects, e.g. \@override 0099 //! in Java, or __declspec(...) and __attribute__((...)) in C++. 0100 Attribute, 0101 //! Text style for single characters such as 'a'. 0102 Char, 0103 //! Text style for escaped characters in strings, such as "hello\n". 0104 SpecialChar, 0105 //! Text style for strings, for instance "hello world". 0106 String, 0107 //! Text style for verbatim strings such as HERE docs. 0108 VerbatimString, 0109 //! Text style for special strings such as regular expressions in 0110 //! ECMAScript or the LaTeX math mode. 0111 SpecialString, 0112 //! Text style for includes, imports, modules, or LaTeX packages. 0113 Import, 0114 //! Text style for data types such as int, char, float etc. 0115 DataType, 0116 //! Text style for decimal values. 0117 DecVal, 0118 //! Text style for numbers with base other than 10. 0119 BaseN, 0120 //! Text style for floating point numbers. 0121 Float, 0122 //! Text style for language constants, e.g. True, False, None in Python 0123 //! or nullptr in C/C++. 0124 Constant, 0125 //! Text style for normal comments. 0126 Comment, 0127 //! Text style for comments that reflect API documentation, such as 0128 //! doxygen /** */ comments. 0129 Documentation, 0130 //! Text style for annotations in comments, such as \@param in Doxygen 0131 //! or JavaDoc. 0132 Annotation, 0133 //! Text style that refers to variables in a comment, such as after 0134 //! \@param \<identifier\> in Doxygen or JavaDoc. 0135 CommentVar, 0136 //! Text style for region markers, typically defined by BEGIN/END. 0137 RegionMarker, 0138 //! Text style for information, such as the keyword \@note in Doxygen. 0139 Information, 0140 //! Text style for warnings, such as the keyword \@warning in Doxygen. 0141 Warning, 0142 //! Text style for comment specials such as TODO and WARNING in 0143 //! comments. 0144 Alert, 0145 //! Text style indicating wrong syntax. 0146 Error, 0147 //! Text style for attributes that do not match any of the other default 0148 //! styles. 0149 Others 0150 }; 0151 Q_ENUM(TextStyle) 0152 0153 /** 0154 * Editor color roles, used to paint line numbers, editor background etc. 0155 * The colors typically should have good contrast with the colors used 0156 * in the TextStyle%s. 0157 */ 0158 enum EditorColorRole { 0159 //! Background color for the editing area. 0160 BackgroundColor = 0, 0161 //! Background color for selected text. 0162 TextSelection, 0163 //! Background color for the line of the current text cursor. 0164 CurrentLine, 0165 //! Background color for matching text while searching. 0166 SearchHighlight, 0167 //! Background color for replaced text for a search & replace action. 0168 ReplaceHighlight, 0169 //! Background color for matching bracket pairs (including quotes) 0170 BracketMatching, 0171 //! Foreground color for visualizing tabs and trailing spaces. 0172 TabMarker, 0173 //! Color used to underline spell check errors. 0174 SpellChecking, 0175 //! Color used to draw vertical indentation levels, typically a line. 0176 IndentationLine, 0177 //! Background color for the icon border. 0178 IconBorder, 0179 //! Background colors for code folding regions in the text area, as well 0180 //! as code folding indicators in the code folding border. 0181 CodeFolding, 0182 //! Foreground color for drawing the line numbers. This should have a 0183 //! good contrast with the IconBorder background color. 0184 LineNumbers, 0185 //! Foreground color for drawing the current line number. This should 0186 //! have a good contrast with the IconBorder background color. 0187 CurrentLineNumber, 0188 //! Color used in the icon border to indicate dynamically wrapped lines. 0189 //! This color should have a good contrast with the IconBorder 0190 //! background color. 0191 WordWrapMarker, 0192 //! Color used to draw a vertical line for marking changed lines. 0193 ModifiedLines, 0194 //! Color used to draw a vertical line for marking saved lines. 0195 SavedLines, 0196 //! Line color used to draw separator lines, e.g. at column 80 in the 0197 //! text editor area. 0198 Separator, 0199 //! Background color for bookmarks. 0200 MarkBookmark, 0201 //! Background color for active breakpoints. 0202 MarkBreakpointActive, 0203 //! Background color for a reached breakpoint. 0204 MarkBreakpointReached, 0205 //! Background color for inactive (disabled) breakpoints. 0206 MarkBreakpointDisabled, 0207 //! Background color for marking the current execution position. 0208 MarkExecution, 0209 //! Background color for general warning marks. 0210 MarkWarning, 0211 //! Background color for general error marks. 0212 MarkError, 0213 //! Background color for text templates (snippets). 0214 TemplateBackground, 0215 //! Background color for all editable placeholders in text templates. 0216 TemplatePlaceholder, 0217 //! Background color for the currently active placeholder in text 0218 //! templates. 0219 TemplateFocusedPlaceholder, 0220 //! Background color for read-only placeholders in text templates. 0221 TemplateReadOnlyPlaceholder 0222 }; 0223 Q_ENUM(EditorColorRole) 0224 0225 /** 0226 * Default constructor, creating an invalid Theme, see isValid(). 0227 */ 0228 Theme(); 0229 0230 /** 0231 * Copy constructor, sharing the Theme data with @p copy. 0232 */ 0233 Theme(const Theme ©); 0234 0235 /** 0236 * Destructor. 0237 */ 0238 ~Theme(); 0239 0240 /** 0241 * Assignment operator, sharing the Theme data with @p other. 0242 */ 0243 Theme &operator=(const Theme &other); 0244 0245 /** 0246 * Returns @c true if this is a valid Theme. 0247 * If the theme is invalid, none of the returned colors are well-defined. 0248 */ 0249 bool isValid() const; 0250 0251 /** 0252 * Returns the unique name of this Theme. 0253 * @see translatedName() 0254 */ 0255 QString name() const; 0256 0257 /** 0258 * Returns the translated name of this Theme. The translated name can be 0259 * used in the user interface. 0260 */ 0261 QString translatedName() const; 0262 0263 /** 0264 * Returns @c true if this Theme is read-only. 0265 * 0266 * A Theme is read-only, if the filePath() points to a non-writable file. 0267 * This is typically the case for Themes that are compiled into the executable 0268 * as resource file, as well as for theme files that are installed in read-only 0269 * system locations (e.g. /usr/share/). 0270 */ 0271 bool isReadOnly() const; 0272 0273 /** 0274 * Returns the full path and file name to this Theme. 0275 * Themes from the Qt resource return the Qt resource path. 0276 * Themes from disk return the local path. 0277 * 0278 * If the theme is invalid (isValid()), an empty string is returned. 0279 */ 0280 QString filePath() const; 0281 0282 /** 0283 * Returns the text color to be used for @p style. 0284 * @c 0 is returned for styles that do not specify a text color, 0285 * use the default text color in that case. 0286 */ 0287 QRgb textColor(TextStyle style) const; 0288 0289 /** 0290 * Returns the selected text color to be used for @p style. 0291 * @c 0 is returned for styles that do not specify a selected text color, 0292 * use the default textColor() in that case. 0293 */ 0294 QRgb selectedTextColor(TextStyle style) const; 0295 0296 /** 0297 * Returns the background color to be used for @p style. 0298 * @c 0 is returned for styles that do not specify a background color, 0299 * use the default background color in that case. 0300 */ 0301 QRgb backgroundColor(TextStyle style) const; 0302 0303 /** 0304 * Returns the background color to be used for selected text for @p style. 0305 * @c 0 is returned for styles that do not specify a background color, 0306 * use the default backgroundColor() in that case. 0307 */ 0308 QRgb selectedBackgroundColor(TextStyle style) const; 0309 0310 /** 0311 * Returns whether the given style should be shown in bold. 0312 */ 0313 bool isBold(TextStyle style) const; 0314 0315 /** 0316 * Returns whether the given style should be shown in italic. 0317 */ 0318 bool isItalic(TextStyle style) const; 0319 0320 /** 0321 * Returns whether the given style should be shown underlined. 0322 */ 0323 bool isUnderline(TextStyle style) const; 0324 0325 /** 0326 * Returns whether the given style should be shown struck through. 0327 */ 0328 bool isStrikeThrough(TextStyle style) const; 0329 0330 public: 0331 /** 0332 * Returns the editor color for the requested @p role. 0333 */ 0334 QRgb editorColor(EditorColorRole role) const; 0335 0336 private: 0337 /** 0338 * Constructor taking a shared ThemeData instance. 0339 */ 0340 KSYNTAXHIGHLIGHTING_NO_EXPORT explicit Theme(ThemeData *data); 0341 friend class RepositoryPrivate; 0342 friend class ThemeData; 0343 0344 private: 0345 /** 0346 * Shared data holder. 0347 */ 0348 QExplicitlySharedDataPointer<ThemeData> m_data; 0349 }; 0350 0351 } 0352 0353 QT_BEGIN_NAMESPACE 0354 Q_DECLARE_TYPEINFO(KSyntaxHighlighting::Theme, Q_RELOCATABLE_TYPE); 0355 QT_END_NAMESPACE 0356 0357 #endif // KSYNTAXHIGHLIGHTING_THEME_H