1 | /* |
2 | SPDX-FileCopyrightText: 2018 Eike Hein <hein@kde.org> |
3 | SPDX-FileCopyrightText: 2021 Volker Krause <vkrause@kde.org> |
4 | |
5 | SPDX-License-Identifier: MIT |
6 | */ |
7 | |
8 | #ifndef KQUICKSYNTAXHIGHLIGHTER_H |
9 | #define KQUICKSYNTAXHIGHLIGHTER_H |
10 | |
11 | #include <KSyntaxHighlighting/Definition> |
12 | #include <KSyntaxHighlighting/Theme> |
13 | |
14 | #include <QObject> |
15 | #include <QVariant> |
16 | |
17 | namespace KSyntaxHighlighting |
18 | { |
19 | class Repository; |
20 | class SyntaxHighlighter; |
21 | } |
22 | |
23 | /*! |
24 | * \qmltype SyntaxHighlighter |
25 | * \inqmlmodule org.kde.syntaxhighlighting |
26 | * \brief Add syntax highlighting to QML text fields. |
27 | * |
28 | * Syntax highlighting may be added to a text field by specifying a \l textEdit id and a \l definition. |
29 | * |
30 | * The list of available definitions can be seen on the \l {https://kate-editor.org/syntax/} {Kate website}. |
31 | * |
32 | * You can learn more about syntax highlighting definitions on the \l {https://invent.kde.org/frameworks/syntax-highlighting} {syntax-highlighting repository}. |
33 | * |
34 | * A custom \l repository containing syntax highlighting definitions may be set. See \l KSyntaxHighlighting::Repository for details. |
35 | * |
36 | * A custom \l theme for the highlighting definitions may be set. The list of available themes can be seen on the |
37 | * \l {https://invent.kde.org/frameworks/syntax-highlighting/-/tree/master/data/themes} {repository's data/themes/ folder}. |
38 | * The name to be used should match the name specified in the JSON metadata, and is case sensitive. For example: |
39 | * |
40 | * \code |
41 | * { |
42 | * "metadata": { |
43 | * "name": "GitHub Dark" |
44 | * } |
45 | * } |
46 | * \endcode |
47 | * |
48 | * Basic usage: |
49 | * |
50 | * \qml |
51 | * import org.kde.syntaxhighlighting |
52 | * |
53 | * // ... |
54 | * |
55 | * SyntaxHighlighter { |
56 | * textEdit: sourceTextArea |
57 | * definition: "INI Files" |
58 | * theme: Repository.theme("GitHub Dark") |
59 | * } |
60 | * \endqml |
61 | * |
62 | * For more complex uses, the syntax definition might not be fixed but depend on input data (for example, |
63 | * derived from its mimetype or file name), or a user selection. In the C++ API this is enabled |
64 | * by the \l KSyntaxHighlighting::Repository class, which is available in QML as a singleton object. |
65 | * |
66 | * The following example shows how to use this for a simple syntax selection combobox: |
67 | * |
68 | * \qml |
69 | * ComboBox { |
70 | * model: Repository.definitions |
71 | * displayText: currentValue.translatedName + " (" + currentValue.translatedSection + ")" |
72 | * textRole: "translatedName" |
73 | * onCurrentIndexChanged: myHighlighter.definition = currentValue |
74 | * } |
75 | * \endqml |
76 | * |
77 | * Handling color themes is also possible, similarly to syntax definitions. Themes can be listed, |
78 | * their properties can be accessed and they can be set by theme object or name on the highlighter. |
79 | * Like in the C++ API it's also possible to just ask for the light or dark default theme. |
80 | * |
81 | * More examples can be seen in the \l {https://invent.kde.org/frameworks/syntax-highlighting/-/tree/master/examples} {repository's examples/ folder}. |
82 | */ |
83 | class KQuickSyntaxHighlighter : public QObject |
84 | { |
85 | Q_OBJECT |
86 | |
87 | /*! |
88 | * \qmlproperty QtObject SyntaxHighlighter::textEdit |
89 | * \brief The id of the text edit component that will have syntax highlighting. |
90 | */ |
91 | Q_PROPERTY(QObject *textEdit READ textEdit WRITE setTextEdit NOTIFY textEditChanged) |
92 | |
93 | /*! |
94 | * \qmlproperty variant SyntaxHighlighter::definition |
95 | * \brief The syntax highlighting definition to be used. |
96 | * \sa {https://kate-editor.org/syntax/} {Available Syntax Highlighting language names} |
97 | */ |
98 | Q_PROPERTY(QVariant definition READ definition WRITE setDefinition NOTIFY definitionChanged) |
99 | |
100 | /*! |
101 | * \qmlproperty variant SyntaxHighlighter::theme |
102 | * \brief The theme to be used for the syntax highlighting. |
103 | * |
104 | * The theme name to be used should match the name specified in the JSON metadata, and is case sensitive. |
105 | * |
106 | * The Repository singleton exposes the API from \l KSyntaxHighlighting::Repository |
107 | * that is necessary to manage themes in your application: |
108 | * |
109 | * \list |
110 | * \li Repository.themes |
111 | * \li Repository.theme |
112 | * \li Repository.defaultTheme() |
113 | * \li Repository.DefaultTheme |
114 | * \endlist |
115 | */ |
116 | Q_PROPERTY(QVariant theme READ theme WRITE setTheme NOTIFY themeChanged) |
117 | |
118 | /*! |
119 | * \qmlproperty Repository SyntaxHighlighter::repository |
120 | * \brief The repository from where syntax highlighting definitions will be pulled. |
121 | * |
122 | * Defaults to the default repository provided by the KSyntaxHighlighting framework. |
123 | * |
124 | * The selected repository can be accessed via the Repository singleton, |
125 | * which exposes the API from \l KSyntaxHighlighting::Repository. |
126 | * |
127 | * The most commonly accessed API is: |
128 | * |
129 | * \list |
130 | * \li Repository.definitions |
131 | * \li Repository.definition |
132 | * \li Repository.definitionForName() |
133 | * \li Repository.definitionForFileName() |
134 | * \li Repository.themes |
135 | * \li Repository.theme |
136 | * \li Repository.defaultTheme() |
137 | * \li Repository.DefaultTheme |
138 | * \endlist |
139 | * \sa {https://invent.kde.org/frameworks/syntax-highlighting/-/blob/master/examples/qml/example.qml} {QML Example} |
140 | */ |
141 | Q_PROPERTY(KSyntaxHighlighting::Repository *repository READ repository WRITE setRepository NOTIFY repositoryChanged) |
142 | |
143 | public: |
144 | explicit KQuickSyntaxHighlighter(QObject *parent = nullptr); |
145 | ~KQuickSyntaxHighlighter() override; |
146 | |
147 | QObject *textEdit() const; |
148 | void setTextEdit(QObject *textEdit); |
149 | |
150 | QVariant definition() const; |
151 | void setDefinition(const QVariant &definition); |
152 | |
153 | QVariant theme() const; |
154 | void setTheme(const QVariant &theme); |
155 | |
156 | KSyntaxHighlighting::Repository *repository() const; |
157 | void setRepository(KSyntaxHighlighting::Repository *repository); |
158 | |
159 | Q_SIGNALS: |
160 | void textEditChanged() const; |
161 | void definitionChanged() const; |
162 | void themeChanged(); |
163 | void repositoryChanged(); |
164 | |
165 | private: |
166 | KSyntaxHighlighting::Repository *unwrappedRepository() const; |
167 | |
168 | QObject *m_textEdit; |
169 | KSyntaxHighlighting::Definition m_definition; |
170 | KSyntaxHighlighting::Theme m_theme; |
171 | KSyntaxHighlighting::Repository *m_repository = nullptr; |
172 | KSyntaxHighlighting::SyntaxHighlighter *m_highlighter = nullptr; |
173 | }; |
174 | |
175 | #endif // KQUICKSYNTAXHIGHLIGHTER_H |
176 | |