1 | /* |
2 | SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org> |
3 | |
4 | SPDX-License-Identifier: MIT |
5 | */ |
6 | |
7 | #ifndef KSYNTAXHIGHLIGHTING_REPOSITORY_H |
8 | #define KSYNTAXHIGHLIGHTING_REPOSITORY_H |
9 | |
10 | #include "ksyntaxhighlighting_export.h" |
11 | |
12 | #include <QList> |
13 | #include <QObject> |
14 | #include <QtGlobal> |
15 | |
16 | #include <memory> |
17 | |
18 | QT_BEGIN_NAMESPACE |
19 | class QString; |
20 | class QPalette; |
21 | QT_END_NAMESPACE |
22 | |
23 | /*! |
24 | * \namespace KSyntaxHighlighting |
25 | * |
26 | * \brief Syntax highlighting engine for Kate syntax definitions. |
27 | * |
28 | * In order to access the syntax highlighting Definition files, use the |
29 | * class Repository. |
30 | */ |
31 | namespace KSyntaxHighlighting |
32 | { |
33 | class Definition; |
34 | class RepositoryPrivate; |
35 | class Theme; |
36 | |
37 | /*! |
38 | * \class KSyntaxHighlighting::Repository |
39 | * \inheaderfile KSyntaxHighlighting/Repository |
40 | * \inmodule KSyntaxHighlighting |
41 | * |
42 | * \brief Syntax highlighting repository. |
43 | * |
44 | * The Repository gives access to all syntax Definitions available on the |
45 | * system, typically described in *.xml files. The Definition files are read |
46 | * from the resource that is compiled into the executable, and from the file |
47 | * system. If a Definition exists in the resource and on the file system, |
48 | * then the one from the file system is chosen. |
49 | * |
50 | * Typically, only one instance of the Repository is needed. This single |
51 | * instance can be thought of as a singleton you keep alive throughout the |
52 | * lifetime of your application. Then, either call definitionForName() with the |
53 | * given language name (e.g. "QML" or "Java"), or definitionForFileName() to |
54 | * obtain a Definition based on the filename/mimetype of the file. The |
55 | * function definitions() returns a list of all available syntax Definition%s. |
56 | * |
57 | * In addition to Definitions, the Repository also provides a list of Themes. |
58 | * A Theme is defined by a set of default text style colors as well as editor |
59 | * colors. These colors together provide all required colros for drawing all |
60 | * primitives of a text editor. All available Theme%s can be queried through |
61 | * themes(), and a Theme with a specific name is obtained through theme(). |
62 | * Additionally, defaultTheme() provides a way to obtain a default theme for |
63 | * either a light or a black color theme. |
64 | * |
65 | * All highlighting Definition and Theme files are compiled into the shared |
66 | * KSyntaxHighlighting library by using the Qt resource system. Loading |
67 | * additional files from disk is supported as well. |
68 | * |
69 | * Loading syntax Definition files works as follows: |
70 | * \list |
71 | * \li First, all syntax highlighting files are loaded that are located in |
72 | * QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QStringLiteral("org.kde.syntax-highlighting/syntax"), QStandardPaths::LocateDirectory); |
73 | * Under Unix, this uses $XDG_DATA_HOME and $XDG_DATA_DIRS, which could |
74 | * map to $HOME/.local5/share/org.kde.syntax-highlighting/syntax and |
75 | * /usr/share/org.kde.syntax-highlighting/syntax. |
76 | * |
77 | * \li Then, all files compiled into the library through resources are loaded. |
78 | * The internal resource path is ":/org.kde.syntax-highlighting/syntax". |
79 | * This path should never be touched by other applications. |
80 | * |
81 | * \li Then, all custom files compiled into resources are loaded. |
82 | * The resource path is ":/org.kde.syntax-highlighting/syntax-addons". |
83 | * This path can be used by other libraries/applications to bundle specialized definitions. |
84 | * Per default this path isn't used by the framework itself. |
85 | * |
86 | * \li Finally, the search path can be extended by calling addCustomSearchPath(). |
87 | * A custom search path can either be a path on disk or again a path to |
88 | * a Qt resource. |
89 | * \endlist |
90 | * |
91 | * Similarly, loading Theme files works as follows: |
92 | * \list |
93 | * \li First, all Theme files are loaded that are located in |
94 | * QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QStringLiteral("org.kde.syntax-highlighting/themes"), QStandardPaths::LocateDirectory); |
95 | * Under Unix, this uses $XDG_DATA_HOME and $XDG_DATA_DIRS, which could |
96 | * map to $HOME/.local5/share/org.kde.syntax-highlighting/themes and |
97 | * /usr/share/org.kde.syntax-highlighting/themes. |
98 | * |
99 | * \li Then, all files compiled into the library through resources are loaded. |
100 | * The internal resource path is ":/org.kde.syntax-highlighting/themes". |
101 | * This path should never be touched by other applications. |
102 | * |
103 | * \li Then, all custom files compiled into resources are loaded. |
104 | * The resource path is ":/org.kde.syntax-highlighting/themes-addons". |
105 | * This path can be used by other libraries/applications to bundle specialized themes. |
106 | * Per default this path isn't used by the framework itself. |
107 | * |
108 | * \li Finally, all Theme%s located in the paths added addCustomSearchPath() |
109 | * are loaded. |
110 | * \endlist |
111 | * |
112 | * \note Whenever a Definition or a Theme exists twice, the variant with |
113 | * higher version is used. |
114 | * |
115 | * \note The QStandardPaths lookup can be disabled by compiling the framework with the -DNO_STANDARD_PATHS define. |
116 | * |
117 | * \sa Definition, Theme, AbstractHighlighter |
118 | * \since 5.28 |
119 | */ |
120 | class KSYNTAXHIGHLIGHTING_EXPORT Repository : public QObject |
121 | { |
122 | Q_OBJECT |
123 | |
124 | /*! |
125 | * \property KSyntaxHighlighting::Repository::definitions |
126 | */ |
127 | Q_PROPERTY(QList<KSyntaxHighlighting::Definition> definitions READ definitions NOTIFY reloaded) |
128 | |
129 | /*! |
130 | * \property KSyntaxHighlighting::Repository::themes |
131 | */ |
132 | Q_PROPERTY(QList<KSyntaxHighlighting::Theme> themes READ themes NOTIFY reloaded) |
133 | |
134 | public: |
135 | /*! |
136 | * Create a new syntax definition repository. |
137 | * This will read the meta data information of all available syntax |
138 | * definition, which is a moderately expensive operation, it's therefore |
139 | * recommended to keep a single instance of Repository around as long |
140 | * as you need highlighting in your application. |
141 | */ |
142 | Repository(); |
143 | |
144 | ~Repository(); |
145 | |
146 | /*! |
147 | * Returns the Definition named \a defName. |
148 | * |
149 | * If no Definition is found, Definition::isValid() of the returned instance |
150 | * returns false. |
151 | * |
152 | * \note The search is Qt::CaseInsensitive using untranslated names or |
153 | * alternative names. For instance, the cpp.xml definition file sets |
154 | * its name to C++ with an alternative name of CPP. Therefore, the |
155 | * strings "C++", "c++", "CPP" and "cpp" will all return a valid |
156 | * Definition file. |
157 | */ |
158 | Q_INVOKABLE KSyntaxHighlighting::Definition definitionForName(const QString &defName) const; |
159 | |
160 | /*! |
161 | * Returns the best matching Definition for the file named \a fileName. |
162 | * The match is performed based on the \e extensions and mimetype of |
163 | * the definition files. If multiple matches are found, the one with the |
164 | * highest priority is returned. |
165 | * |
166 | * If no match is found, Definition::isValid() of the returned instance |
167 | * returns false. |
168 | */ |
169 | Q_INVOKABLE KSyntaxHighlighting::Definition definitionForFileName(const QString &fileName) const; |
170 | |
171 | /*! |
172 | * Returns all Definition%s for the file named \a fileName sorted by priority. |
173 | * The match is performed based on the \e extensions and mimetype of |
174 | * the definition files. |
175 | * |
176 | * \since 5.56 |
177 | */ |
178 | Q_INVOKABLE QList<KSyntaxHighlighting::Definition> definitionsForFileName(const QString &fileName) const; |
179 | |
180 | /*! |
181 | * Returns the best matching Definition to the type named \a mimeType |
182 | * |
183 | * If no match is found, Definition::isValid() of the returned instance |
184 | * returns false. |
185 | * |
186 | * \since 5.50 |
187 | */ |
188 | Q_INVOKABLE KSyntaxHighlighting::Definition definitionForMimeType(const QString &mimeType) const; |
189 | |
190 | /*! |
191 | * Returns all Definition%s to the type named \a mimeType sorted by priority |
192 | * |
193 | * \since 5.56 |
194 | */ |
195 | Q_INVOKABLE QList<KSyntaxHighlighting::Definition> definitionsForMimeType(const QString &mimeType) const; |
196 | |
197 | /*! |
198 | * Returns all available Definition%s. |
199 | * Definition%ss are ordered by translated section and translated names, |
200 | * for consistent displaying. |
201 | */ |
202 | Q_INVOKABLE QList<KSyntaxHighlighting::Definition> definitions() const; |
203 | |
204 | /*! |
205 | * Returns all available color themes. |
206 | * The returned list should never be empty. |
207 | */ |
208 | Q_INVOKABLE QList<KSyntaxHighlighting::Theme> themes() const; |
209 | |
210 | /*! |
211 | * Returns the theme called \a themeName. |
212 | * If the requested theme cannot be found, the retunred Theme is invalid, |
213 | * see Theme::isValid(). |
214 | */ |
215 | Q_INVOKABLE KSyntaxHighlighting::Theme theme(const QString &themeName) const; |
216 | |
217 | /*! |
218 | * \enum ResolveState |
219 | * |
220 | * Built-in default theme types. |
221 | * \sa defaultTheme() |
222 | * |
223 | * \value LightTheme |
224 | * \value DarkTheme |
225 | */ |
226 | enum DefaultTheme { |
227 | LightTheme, |
228 | DarkTheme |
229 | }; |
230 | Q_ENUM(DefaultTheme) |
231 | |
232 | /*! |
233 | * Returns a default theme instance of the given type. |
234 | * The returned Theme is guaranteed to be a valid theme. |
235 | * \since 5.79 |
236 | */ |
237 | Q_INVOKABLE KSyntaxHighlighting::Theme defaultTheme(DefaultTheme t = LightTheme) const; |
238 | |
239 | /*! |
240 | * Returns the best matching theme for the given palette |
241 | * \since 5.79 |
242 | **/ |
243 | Theme themeForPalette(const QPalette &palette) const; |
244 | |
245 | /*! |
246 | * Reloads the repository. |
247 | * This is a moderately expensive operations and should thus only be |
248 | * triggered when the installed syntax definition files changed. |
249 | */ |
250 | void reload(); |
251 | |
252 | /*! |
253 | * Add a custom search path to the repository. |
254 | * This path will be searched in addition to the usual locations for syntax |
255 | * and theme definition files. Both locations on disk as well as Qt |
256 | * resource paths are supported. |
257 | * |
258 | * \note Internally, the two sub-folders \a path/syntax as well as |
259 | * \a path/themes are searched for additional Definition%s and |
260 | * Theme%s. Do not append syntax or themes to \a path |
261 | * yourself. |
262 | * |
263 | * \note Calling this triggers a reload() of the repository. |
264 | * |
265 | * \since 5.39 |
266 | */ |
267 | void addCustomSearchPath(const QString &path); |
268 | |
269 | /*! |
270 | * Returns the list of custom search paths added to the repository. |
271 | * By default, this list is empty. |
272 | * |
273 | * \sa addCustomSearchPath() |
274 | * \since 5.39 |
275 | */ |
276 | QList<QString> customSearchPaths() const; |
277 | |
278 | Q_SIGNALS: |
279 | /*! |
280 | * This signal is emitted before the reload is started. |
281 | * \since 6.0 |
282 | */ |
283 | void aboutToReload(); |
284 | |
285 | /*! |
286 | * This signal is emitted when the reload is finished. |
287 | * \since 6.0 |
288 | */ |
289 | void reloaded(); |
290 | |
291 | private: |
292 | Q_DISABLE_COPY(Repository) |
293 | friend class RepositoryPrivate; |
294 | std::unique_ptr<RepositoryPrivate> d; |
295 | }; |
296 | |
297 | } |
298 | |
299 | #endif // KSYNTAXHIGHLIGHTING_REPOSITORY_H |
300 | |