1/*
2 SPDX-FileCopyrightText: 2018 Eike Hein <[email protected]>
3 SPDX-FileCopyrightText: 2021 Volker Krause <[email protected]>
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
17namespace KSyntaxHighlighting
18{
19class Repository;
20class 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 */
83class 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
143public:
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
159Q_SIGNALS:
160 void textEditChanged() const;
161 void definitionChanged() const;
162 void themeChanged();
163 void repositoryChanged();
164
165private:
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

source code of syntax-highlighting/src/quick/kquicksyntaxhighlighter.h