KSyntaxHighlighting

repository.h
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
18QT_BEGIN_NAMESPACE
19class QString;
20class QPalette;
21QT_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 */
32namespace KSyntaxHighlighting
33{
34class Definition;
35class RepositoryPrivate;
36class 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 * -# Then, all files compiled into the library through resources are loaded.
81 * The internal resource path is ":/org.kde.syntax-highlighting/syntax".
82 * This path should never be touched by other applications.
83 *
84 * -# Then, all custom files compiled into resources are loaded.
85 * The resource path is ":/org.kde.syntax-highlighting/syntax-addons".
86 * This path can be used by other libraries/applications to bundle specialized definitions.
87 * Per default this path isn't used by the framework itself.
88 *
89 * -# Finally, the search path can be extended by calling addCustomSearchPath().
90 * A custom search path can either be a path on disk or again a path to
91 * a Qt resource.
92 *
93 * Similarly, loading Theme files works as follows:
94 *
95 * -# First, all Theme files are loaded that are located in
96 * QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QStringLiteral("org.kde.syntax-highlighting/themes"), QStandardPaths::LocateDirectory);
97 * Under Unix, this uses $XDG_DATA_HOME and $XDG_DATA_DIRS, which could
98 * map to $HOME/.local5/share/org.kde.syntax-highlighting/themes and
99 * /usr/share/org.kde.syntax-highlighting/themes.
100 *
101 * -# Then, all files compiled into the library through resources are loaded.
102 * The internal resource path is ":/org.kde.syntax-highlighting/themes".
103 * This path should never be touched by other applications.
104 *
105 * -# Then, all custom files compiled into resources are loaded.
106 * The resource path is ":/org.kde.syntax-highlighting/themes-addons".
107 * This path can be used by other libraries/applications to bundle specialized themes.
108 * Per default this path isn't used by the framework itself.
109 *
110 * -# Finally, all Theme%s located in the paths added addCustomSearchPath()
111 * are loaded.
112 *
113 * @note Whenever a Definition or a Theme exists twice, the variant with
114 * higher version is used.
115 *
116 * @note The QStandardPaths lookup can be disabled by compiling the framework with the -DNO_STANDARD_PATHS define.
117 *
118 * @see Definition, Theme, AbstractHighlighter
119 * @since 5.28
120 */
121class KSYNTAXHIGHLIGHTING_EXPORT Repository : public QObject
122{
123 Q_OBJECT
124 Q_PROPERTY(QList<KSyntaxHighlighting::Definition> definitions READ definitions NOTIFY reloaded)
125 Q_PROPERTY(QList<KSyntaxHighlighting::Theme> themes READ themes NOTIFY reloaded)
126
127public:
128 /**
129 * Create a new syntax definition repository.
130 * This will read the meta data information of all available syntax
131 * definition, which is a moderately expensive operation, it's therefore
132 * recommended to keep a single instance of Repository around as long
133 * as you need highlighting in your application.
134 */
135 Repository();
136 ~Repository();
137
138 /**
139 * Returns the Definition named @p defName.
140 *
141 * If no Definition is found, Definition::isValid() of the returned instance
142 * returns false.
143 *
144 * @note The search is @e Qt::CaseInsensitive using untranslated names or
145 * alternative names. For instance, the cpp.xml definition file sets
146 * its name to @e C++ with an alternative name of @e CPP. Therefore, the
147 * strings "C++", "c++", "CPP" and "cpp" will all return a valid
148 * Definition file.
149 */
150 Q_INVOKABLE KSyntaxHighlighting::Definition definitionForName(const QString &defName) const;
151
152 /**
153 * Returns the best matching Definition for the file named @p fileName.
154 * The match is performed based on the \e extensions and @e mimetype of
155 * the definition files. If multiple matches are found, the one with the
156 * highest priority is returned.
157 *
158 * If no match is found, Definition::isValid() of the returned instance
159 * returns false.
160 */
161 Q_INVOKABLE KSyntaxHighlighting::Definition definitionForFileName(const QString &fileName) const;
162
163 /**
164 * Returns all Definition%s for the file named @p fileName sorted by priority.
165 * The match is performed based on the \e extensions and @e mimetype of
166 * the definition files.
167 *
168 * @since 5.56
169 */
170 Q_INVOKABLE QList<KSyntaxHighlighting::Definition> definitionsForFileName(const QString &fileName) const;
171
172 /**
173 * Returns the best matching Definition to the type named @p mimeType
174 *
175 * If no match is found, Definition::isValid() of the returned instance
176 * returns false.
177 *
178 * @since 5.50
179 */
180 Q_INVOKABLE KSyntaxHighlighting::Definition definitionForMimeType(const QString &mimeType) const;
181
182 /**
183 * Returns all Definition%s to the type named @p mimeType sorted by priority
184 *
185 * @since 5.56
186 */
187 Q_INVOKABLE QList<KSyntaxHighlighting::Definition> definitionsForMimeType(const QString &mimeType) const;
188
189 /**
190 * Returns all available Definition%s.
191 * Definition%ss are ordered by translated section and translated names,
192 * for consistent displaying.
193 */
194 Q_INVOKABLE QList<KSyntaxHighlighting::Definition> definitions() const;
195
196 /**
197 * Returns all available color themes.
198 * The returned list should never be empty.
199 */
200 Q_INVOKABLE QList<KSyntaxHighlighting::Theme> themes() const;
201
202 /**
203 * Returns the theme called @p themeName.
204 * If the requested theme cannot be found, the retunred Theme is invalid,
205 * see Theme::isValid().
206 */
207 Q_INVOKABLE KSyntaxHighlighting::Theme theme(const QString &themeName) const;
208
209 /**
210 * Built-in default theme types.
211 * @see defaultTheme()
212 */
214 //! Theme with a light background color.
216 //! Theme with a dark background color.
217 DarkTheme
218 };
219 Q_ENUM(DefaultTheme)
220
221 /**
222 * Returns a default theme instance of the given type.
223 * The returned Theme is guaranteed to be a valid theme.
224 * @since 5.79
225 */
226 Q_INVOKABLE KSyntaxHighlighting::Theme defaultTheme(DefaultTheme t = LightTheme) const;
227
228 /**
229 * Returns the best matching theme for the given palette
230 * @since 5.79
231 **/
232 Theme themeForPalette(const QPalette &palette) const;
233
234 /**
235 * Reloads the repository.
236 * This is a moderately expensive operations and should thus only be
237 * triggered when the installed syntax definition files changed.
238 */
239 void reload();
240
241 /**
242 * Add a custom search path to the repository.
243 * This path will be searched in addition to the usual locations for syntax
244 * and theme definition files. Both locations on disk as well as Qt
245 * resource paths are supported.
246 *
247 * @note Internally, the two sub-folders @p path/syntax as well as
248 * @p path/themes are searched for additional Definition%s and
249 * Theme%s. Do not append @e syntax or @e themes to @p path
250 * yourself.
251 *
252 * @note Calling this triggers a reload() of the repository.
253 *
254 * @since 5.39
255 */
256 void addCustomSearchPath(const QString &path);
257
258 /**
259 * Returns the list of custom search paths added to the repository.
260 * By default, this list is empty.
261 *
262 * @see addCustomSearchPath()
263 * @since 5.39
264 */
265 QList<QString> customSearchPaths() const;
266
267Q_SIGNALS:
268 /**
269 * This signal is emitted before the reload is started.
270 * @since 6.0
271 */
273
274 /**
275 * This signal is emitted when the reload is finished.
276 * @since 6.0
277 */
278 void reloaded();
279
280private:
281 Q_DISABLE_COPY(Repository)
282 friend class RepositoryPrivate;
283 std::unique_ptr<RepositoryPrivate> d;
284};
285
286}
287
288#endif // KSYNTAXHIGHLIGHTING_REPOSITORY_H
Represents a syntax definition.
Definition definition.h:83
Syntax highlighting repository.
Definition repository.h:122
DefaultTheme
Built-in default theme types.
Definition repository.h:213
@ LightTheme
Theme with a light background color.
Definition repository.h:215
void aboutToReload()
This signal is emitted before the reload is started.
void reloaded()
This signal is emitted when the reload is finished.
Color theme definition used for highlighting.
Definition theme.h:65
Syntax highlighting engine for Kate syntax definitions.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Oct 11 2024 12:09:06 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.