KSyntaxHighlighting::Theme Class
class KSyntaxHighlighting::ThemeColor theme definition used for highlighting. More...
| Header: | #include <KSyntaxHighlighting/Theme> |
| CMake: | find_package(KF6 REQUIRED COMPONENTS KSyntaxHighlighting)target_link_libraries(mytarget PRIVATE KF6::KSyntaxHighlighting) |
| Since: | 5.28 |
Public Types
| enum | TextStyle { Normal, Keyword, Function, Variable, ControlFlow, …, Others } |
Properties
- name : const QString
- translatedName : const QString
Public Functions
| Theme() | |
| Theme(const KSyntaxHighlighting::Theme ©) | |
| QRgb | backgroundColor(KSyntaxHighlighting::Theme::TextStyle style) const |
| QRgb | editorColor(KSyntaxHighlighting::Theme::EditorColorRole role) const |
| QString | filePath() const |
| bool | isBold(KSyntaxHighlighting::Theme::TextStyle style) const |
| bool | isItalic(KSyntaxHighlighting::Theme::TextStyle style) const |
| bool | isReadOnly() const |
| bool | isStrikeThrough(KSyntaxHighlighting::Theme::TextStyle style) const |
| bool | isUnderline(KSyntaxHighlighting::Theme::TextStyle style) const |
| bool | isValid() const |
| QString | name() const |
| QRgb | selectedBackgroundColor(KSyntaxHighlighting::Theme::TextStyle style) const |
| QRgb | selectedTextColor(KSyntaxHighlighting::Theme::TextStyle style) const |
| QRgb | textColor(KSyntaxHighlighting::Theme::TextStyle style) const |
| QString | translatedName() const |
| KSyntaxHighlighting::Theme & | operator=(const KSyntaxHighlighting::Theme &other) |
Detailed Description
The Theme provides a full color theme for painting the highlighted text. One Theme is defined either as a *.theme file on disk, or as a file compiled into the SyntaxHighlighting library by using Qt's resource system. Each Theme has a unique name(), including a translatedName() if put into the UI. Themes shipped by default are typically read-only, see isReadOnly().
A Theme defines two sets of colors:
- Text colors, including foreground and background colors, colors for selected text, and properties such as bold and italic. These colors are used e.g. by the SyntaxHighlighter.
- Editor colors, including a background color for the entire editor widget, the line number color, code folding colors, etc.
Text Colors and the Class Format
The text colors are used for syntax highlighting. // TODO: elaborate more and explain relation to Format class
theme_editor_colors Editor Colors
If you want to use the SyntaxHighlighting framework to write your own text editor, you also need to paint the background of the editing widget. In addition, the editor may support showing line numbers, a folding bar, a highlight for the current text line, and similar features. All these colors are defined in terms of the "editor colors" and accessible by calling editorColor() with the desired enum EditorColorRole.
Accessing a Theme
All available Theme%s are accessed through the Repository. These themes are typically valid themes. If you create a Theme on your own, isValid() will return false, and all colors provided by this Theme are in fact invalid and therefore unusable.
See also Format.
Member Type Documentation
enum Theme::TextStyle
Default styles that can be referenced from syntax definition XML files. Make sure to choose readable colors with good contrast especially in combination with the EditorColorRole%s.
| Constant | Value | Description |
|---|---|---|
KSyntaxHighlighting::Theme::Normal | 0 | Default text style for normal text and source code without special highlighting. |
KSyntaxHighlighting::Theme::Keyword | 1 | Text style for language keywords. |
KSyntaxHighlighting::Theme::Function | 2 | Text style for function definitions and function calls. |
KSyntaxHighlighting::Theme::Variable | 3 | Text style for variables, if applicable. For instance, variables in PHP typically start with a '$', so all identifiers following the pattern $foo are highlighted as variable. |
KSyntaxHighlighting::Theme::ControlFlow | 4 | Text style for control flow highlighting, such as if, then, else, return, or continue. |
KSyntaxHighlighting::Theme::Operator | 5 | Text style for operators such as +, -, *, / and :: etc. |
KSyntaxHighlighting::Theme::BuiltIn | 6 | Text style for built-in language classes and functions. |
KSyntaxHighlighting::Theme::Extension | 7 | Text style for well-known extensions, such as Qt or boost. |
KSyntaxHighlighting::Theme::Preprocessor | 8 | Text style for preprocessor statements. |
KSyntaxHighlighting::Theme::Attribute | 9 | Text style for attributes of functions or objects, e.g. @override in Java, or __declspec(...) and __attribute__((...)) in C++. |
KSyntaxHighlighting::Theme::Char | 10 | Text style for single characters such as 'a'. |
KSyntaxHighlighting::Theme::SpecialChar | 11 | Text style for escaped characters in strings, such as "hello\n". |
KSyntaxHighlighting::Theme::String | 12 | Text style for strings, for instance "hello world". |
KSyntaxHighlighting::Theme::VerbatimString | 13 | Text style for verbatim strings such as HERE docs. |
KSyntaxHighlighting::Theme::SpecialString | 14 | Text style for special strings such as regular expressions in ECMAScript or the LaTeX math mode. |
KSyntaxHighlighting::Theme::Import | 15 | Text style for includes, imports, modules, or LaTeX packages. |
KSyntaxHighlighting::Theme::DataType | 16 | Text style for data types such as int, char, float etc. |
KSyntaxHighlighting::Theme::DecVal | 17 | Text style for decimal values. |
KSyntaxHighlighting::Theme::BaseN | 18 | Text style for numbers with base other than 10. |
KSyntaxHighlighting::Theme::Float | 19 | Text style for floating point numbers. |
KSyntaxHighlighting::Theme::Constant | 20 | Text style for language constants, e.g. True, False, None in Python or nullptr in C/C++. |
KSyntaxHighlighting::Theme::Comment | 21 | Text style for normal comments. |
KSyntaxHighlighting::Theme::Documentation | 22 | Text style for comments that reflect API documentation, such as doxygen \/** *\/ comments. |
KSyntaxHighlighting::Theme::Annotation | 23 | Text style for annotations in comments, such as in Doxygen or JavaDoc. |
KSyntaxHighlighting::Theme::CommentVar | 24 | Text style that refers to variables in a comment, such as after <identifier> in Doxygen or JavaDoc. |
KSyntaxHighlighting::Theme::RegionMarker | 25 | Text style for region markers, typically defined by BEGIN/END. |
KSyntaxHighlighting::Theme::Information | 26 | Text style for information, such as the keyword \note in Doxygen. |
KSyntaxHighlighting::Theme::Warning | 27 | Text style for warnings, such as the keyword \warning in Doxygen. |
KSyntaxHighlighting::Theme::Alert | 28 | Text style for comment specials such as TODO and WARNING in comments. |
KSyntaxHighlighting::Theme::Error | 29 | Text style indicating wrong syntax. |
KSyntaxHighlighting::Theme::Others | 30 | Text style for attributes that do not match any of the other default styles. |
Property Documentation
[read-only] name : const QString
Access functions:
| QString | name() const |
[read-only] translatedName : const QString
Access functions:
| QString | translatedName() const |
Member Function Documentation
Theme::Theme()
Default constructor, creating an invalid Theme, see isValid().
Theme::Theme(const KSyntaxHighlighting::Theme ©)
Copy constructor, sharing the Theme data with copy.
QRgb Theme::backgroundColor(KSyntaxHighlighting::Theme::TextStyle style) const
Returns the background color to be used for style. 0 is returned for styles that do not specify a background color, use the default background color in that case.
QRgb Theme::editorColor(KSyntaxHighlighting::Theme::EditorColorRole role) const
Returns the editor color for the requested role.
QString Theme::filePath() const
Returns the full path and file name to this Theme. Themes from the Qt resource return the Qt resource path. Themes from disk return the local path.
If the theme is invalid (isValid()), an empty string is returned.
bool Theme::isBold(KSyntaxHighlighting::Theme::TextStyle style) const
Returns whether the given style should be shown in bold.
bool Theme::isItalic(KSyntaxHighlighting::Theme::TextStyle style) const
Returns whether the given style should be shown in italic.
bool Theme::isReadOnly() const
Returns true if this Theme is read-only.
A Theme is read-only, if the filePath() points to a non-writable file. This is typically the case for Themes that are compiled into the executable as resource file, as well as for theme files that are installed in read-only system locations (e.g. /usr/share/).
bool Theme::isStrikeThrough(KSyntaxHighlighting::Theme::TextStyle style) const
Returns whether the given style should be shown struck through.
bool Theme::isUnderline(KSyntaxHighlighting::Theme::TextStyle style) const
Returns whether the given style should be shown underlined.
bool Theme::isValid() const
Returns true if this is a valid Theme. If the theme is invalid, none of the returned colors are well-defined.
QString Theme::name() const
Returns the unique name of this Theme.
Note: Getter function for property name.
See also translatedName().
QRgb Theme::selectedBackgroundColor(KSyntaxHighlighting::Theme::TextStyle style) const
Returns the background color to be used for selected text for style. 0 is returned for styles that do not specify a background color, use the default backgroundColor() in that case.
QRgb Theme::selectedTextColor(KSyntaxHighlighting::Theme::TextStyle style) const
Returns the selected text color to be used for style. 0 is returned for styles that do not specify a selected text color, use the default textColor() in that case.
QRgb Theme::textColor(KSyntaxHighlighting::Theme::TextStyle style) const
Returns the text color to be used for style. 0 is returned for styles that do not specify a text color, use the default text color in that case.
QString Theme::translatedName() const
Returns the translated name of this Theme. The translated name can be used in the user interface.
Note: Getter function for property translatedName.
KSyntaxHighlighting::Theme &Theme::operator=(const KSyntaxHighlighting::Theme &other)
Assignment operator, sharing the Theme data with other.