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

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