KSyntaxHighlighting

repository.h
1 /*
2  SPDX-FileCopyrightText: 2016 Volker Krause <[email protected]>
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 <QVector>
13 #include <QtGlobal>
14 
15 #include <memory>
16 
17 QT_BEGIN_NAMESPACE
18 class QString;
19 class QPalette;
20 QT_END_NAMESPACE
21 
22 /**
23  * @namespace KSyntaxHighlighting
24  *
25  * Syntax highlighting engine for Kate syntax definitions.
26  * In order to access the syntax highlighting Definition files, use the
27  * class Repository.
28  *
29  * @see Repository
30  */
31 namespace KSyntaxHighlighting
32 {
33 class Definition;
34 class RepositoryPrivate;
35 class Theme;
36 
37 /**
38  * @brief Syntax highlighting repository.
39  *
40  * @section repo_intro Introduction
41  *
42  * The Repository gives access to all syntax Definitions available on the
43  * system, typically described in *.xml files. The Definition files are read
44  * from the resource that is compiled into the executable, and from the file
45  * system. If a Definition exists in the resource and on the file system,
46  * then the one from the file system is chosen.
47  *
48  * @section repo_access Definitions and Themes
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  * @section repo_search_paths Search Paths
66  *
67  * All highlighting Definition and Theme files are compiled into the shared
68  * KSyntaxHighlighting library by using the Qt resource system. Loading
69  * additional files from disk is supported as well.
70  *
71  * Loading syntax Definition files works as follows:
72  *
73  * -# First, all syntax highlighting files are loaded that are located in
74  * QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QStringLiteral("org.kde.syntax-highlighting/syntax"), QStandardPaths::LocateDirectory);
75  * Under Unix, this uses $XDG_DATA_HOME and $XDG_DATA_DIRS, which could
76  * map to $HOME/.local5/share/org.kde.syntax-highlighting/syntax and
77  * /usr/share/org.kde.syntax-highlighting/syntax.
78  *
79  * -# Next, for backwards compatibility with Kate, all syntax highlighting
80  * files are loaded that are located in
81  * QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QStringLiteral("katepart5/syntax"), QStandardPaths::LocateDirectory);
82  * Again, under Unix, this uses $XDG_DATA_HOME and $XDG_DATA_DIRS, which
83  * could map to $HOME/.local5/share/katepart5/syntax and
84  * /usr/share/katepart5/syntax.
85  *
86  * -# Then, all files compiled into the library through resources are loaded.
87  * The internal resource path is ":/org.kde.syntax-highlighting/syntax".
88  * This path should never be touched by other applications.
89  *
90  * -# Then, all custom files compiled into resources are loaded.
91  * The resource path is ":/org.kde.syntax-highlighting/syntax-addons".
92  * This path can be used by other libraries/applications to bundle specialized definitions.
93  * Per default this path isn't used by the framework itself.
94  *
95  * -# Finally, the search path can be extended by calling addCustomSearchPath().
96  * A custom search path can either be a path on disk or again a path to
97  * a Qt resource.
98  *
99  * Similarly, loading Theme files works as follows:
100  *
101  * -# First, all Theme files are loaded that are located in
102  * QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QStringLiteral("org.kde.syntax-highlighting/themes"), QStandardPaths::LocateDirectory);
103  * Under Unix, this uses $XDG_DATA_HOME and $XDG_DATA_DIRS, which could
104  * map to $HOME/.local5/share/org.kde.syntax-highlighting/themes and
105  * /usr/share/org.kde.syntax-highlighting/themes.
106  *
107  * -# Then, all files compiled into the library through resources are loaded.
108  * The internal resource path is ":/org.kde.syntax-highlighting/themes".
109  * This path should never be touched by other applications.
110  *
111  * -# Then, all custom files compiled into resources are loaded.
112  * The resource path is ":/org.kde.syntax-highlighting/themes-addons".
113  * This path can be used by other libraries/applications to bundle specialized themes.
114  * Per default this path isn't used by the framework itself.
115  *
116  * -# Finally, all Theme%s located in the paths added addCustomSearchPath()
117  * are loaded.
118  *
119  * @note Whenever a Definition or a Theme exists twice, the variant with
120  * higher version is used.
121  *
122  * @note The QStandardPaths lookup can be disabled by compiling the framework with the -DNO_STANDARD_PATHS define.
123  *
124  * @see Definition, Theme, AbstractHighlighter
125  * @since 5.28
126  */
127 class KSYNTAXHIGHLIGHTING_EXPORT Repository
128 {
129 public:
130  /**
131  * Create a new syntax definition repository.
132  * This will read the meta data information of all available syntax
133  * definition, which is a moderately expensive operation, it's therefore
134  * recommended to keep a single instance of Repository around as long
135  * as you need highlighting in your application.
136  */
137  Repository();
138  ~Repository();
139 
140  /**
141  * Returns the Definition named @p defName.
142  *
143  * If no Definition is found, Definition::isValid() of the returned instance
144  * returns false.
145  *
146  * @note This uses case sensitive, untranslated names. For instance,
147  * the javascript.xml definition file sets its name to @e JavaScript.
148  * Therefore, only the string "JavaScript" will return a valid
149  * Definition file.
150  */
151  Definition definitionForName(const QString &defName) const;
152 
153  /**
154  * Returns the best matching Definition for the file named @p fileName.
155  * The match is performed based on the \e extensions and @e mimetype of
156  * the definition files. If multiple matches are found, the one with the
157  * highest priority is returned.
158  *
159  * If no match is found, Definition::isValid() of the returned instance
160  * returns false.
161  */
162  Definition definitionForFileName(const QString &fileName) const;
163 
164  /**
165  * Returns all Definition%s for the file named @p fileName sorted by priority.
166  * The match is performed based on the \e extensions and @e mimetype of
167  * the definition files.
168  *
169  * @since 5.56
170  */
171  QVector<Definition> definitionsForFileName(const QString &fileName) const;
172 
173  /**
174  * Returns the best matching Definition to the type named @p mimeType
175  *
176  * If no match is found, Definition::isValid() of the returned instance
177  * returns false.
178  *
179  * @since 5.50
180  */
181  Definition definitionForMimeType(const QString &mimeType) const;
182 
183  /**
184  * Returns all Definition%s to the type named @p mimeType sorted by priority
185  *
186  * @since 5.56
187  */
188  QVector<Definition> definitionsForMimeType(const QString &mimeType) const;
189 
190  /**
191  * Returns all available Definition%s.
192  * Definition%ss are ordered by translated section and translated names,
193  * for consistent displaying.
194  */
195  QVector<Definition> definitions() const;
196 
197  /**
198  * Returns all available color themes.
199  * The returned list should never be empty.
200  */
201  QVector<Theme> themes() const;
202 
203  /**
204  * Returns the theme called @p themeName.
205  * If the requested theme cannot be found, the retunred Theme is invalid,
206  * see Theme::isValid().
207  */
208  Theme theme(const QString &themeName) const;
209 
210  /**
211  * Built-in default theme types.
212  * @see defaultTheme()
213  */
215  //! Theme with a light background color.
217  //! Theme with a dark background color.
218  DarkTheme
219  };
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  Theme defaultTheme(DefaultTheme t = LightTheme) const;
227 
228  /**
229  * Returns a default theme instance of the given type.
230  * The returned Theme is guaranteed to be a valid theme.
231  *
232  * KF6: remove in favor of const variant
233  */
234  Theme defaultTheme(DefaultTheme t = LightTheme);
235 
236  /**
237  * Returns the best matching theme for the given palette
238  * @since 5.79
239  **/
240  Theme themeForPalette(const QPalette &palette) const;
241 
242  /**
243  * Returns the best matching theme for the given palette
244  * @since 5.77
245  *
246  * KF6: remove in favor of const variant
247  **/
248  Theme themeForPalette(const QPalette &palette);
249 
250  /**
251  * Reloads the repository.
252  * This is a moderately expensive operations and should thus only be
253  * triggered when the installed syntax definition files changed.
254  */
255  void reload();
256 
257  /**
258  * Add a custom search path to the repository.
259  * This path will be searched in addition to the usual locations for syntax
260  * and theme definition files. Both locations on disk as well as Qt
261  * resource paths are supported.
262  *
263  * @note Internally, the two sub-folders @p path/syntax as well as
264  * @p path/themes are searched for additional Definition%s and
265  * Theme%s. Do not append @e syntax or @e themes to @p path
266  * yourself.
267  *
268  * @note Calling this triggers a reload() of the repository.
269  *
270  * @since 5.39
271  */
272  void addCustomSearchPath(const QString &path);
273 
274  /**
275  * Returns the list of custom search paths added to the repository.
276  * By default, this list is empty.
277  *
278  * @see addCustomSearchPath()
279  * @since 5.39
280  */
281  QVector<QString> customSearchPaths() const;
282 
283 private:
284  Q_DISABLE_COPY(Repository)
285  friend class RepositoryPrivate;
286  std::unique_ptr<RepositoryPrivate> d;
287 };
288 
289 }
290 
291 #endif // KSYNTAXHIGHLIGHTING_REPOSITORY_H
@ LightTheme
Theme with a light background color.
Definition: repository.h:216
Syntax highlighting repository.
Definition: repository.h:127
Represents a syntax definition.
Definition: definition.h:86
Color theme definition used for highlighting.
Definition: theme.h:64
DefaultTheme
Built-in default theme types.
Definition: repository.h:214
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Sep 23 2023 04:01:33 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.