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