File indexing completed on 2024-05-12 04:02:19
0001 /* 0002 SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org> 0003 0004 SPDX-License-Identifier: MIT 0005 */ 0006 0007 #ifndef KSYNTAXHIGHLIGHTING_REPOSITORY_H 0008 #define KSYNTAXHIGHLIGHTING_REPOSITORY_H 0009 0010 #include "ksyntaxhighlighting_export.h" 0011 0012 #include <QList> 0013 #include <QObject> 0014 #include <QtGlobal> 0015 0016 #include <memory> 0017 0018 QT_BEGIN_NAMESPACE 0019 class QString; 0020 class QPalette; 0021 QT_END_NAMESPACE 0022 0023 /** 0024 * @namespace KSyntaxHighlighting 0025 * 0026 * Syntax highlighting engine for Kate syntax definitions. 0027 * In order to access the syntax highlighting Definition files, use the 0028 * class Repository. 0029 * 0030 * @see Repository 0031 */ 0032 namespace KSyntaxHighlighting 0033 { 0034 class Definition; 0035 class RepositoryPrivate; 0036 class Theme; 0037 0038 /** 0039 * @brief Syntax highlighting repository. 0040 * 0041 * @section repo_intro Introduction 0042 * 0043 * The Repository gives access to all syntax Definitions available on the 0044 * system, typically described in *.xml files. The Definition files are read 0045 * from the resource that is compiled into the executable, and from the file 0046 * system. If a Definition exists in the resource and on the file system, 0047 * then the one from the file system is chosen. 0048 * 0049 * @section repo_access Definitions and Themes 0050 * 0051 * Typically, only one instance of the Repository is needed. This single 0052 * instance can be thought of as a singleton you keep alive throughout the 0053 * lifetime of your application. Then, either call definitionForName() with the 0054 * given language name (e.g. "QML" or "Java"), or definitionForFileName() to 0055 * obtain a Definition based on the filename/mimetype of the file. The 0056 * function definitions() returns a list of all available syntax Definition%s. 0057 * 0058 * In addition to Definitions, the Repository also provides a list of Themes. 0059 * A Theme is defined by a set of default text style colors as well as editor 0060 * colors. These colors together provide all required colros for drawing all 0061 * primitives of a text editor. All available Theme%s can be queried through 0062 * themes(), and a Theme with a specific name is obtained through theme(). 0063 * Additionally, defaultTheme() provides a way to obtain a default theme for 0064 * either a light or a black color theme. 0065 * 0066 * @section repo_search_paths Search Paths 0067 * 0068 * All highlighting Definition and Theme files are compiled into the shared 0069 * KSyntaxHighlighting library by using the Qt resource system. Loading 0070 * additional files from disk is supported as well. 0071 * 0072 * Loading syntax Definition files works as follows: 0073 * 0074 * -# First, all syntax highlighting files are loaded that are located in 0075 * QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QStringLiteral("org.kde.syntax-highlighting/syntax"), QStandardPaths::LocateDirectory); 0076 * Under Unix, this uses $XDG_DATA_HOME and $XDG_DATA_DIRS, which could 0077 * map to $HOME/.local5/share/org.kde.syntax-highlighting/syntax and 0078 * /usr/share/org.kde.syntax-highlighting/syntax. 0079 * 0080 * -# Then, all files compiled into the library through resources are loaded. 0081 * The internal resource path is ":/org.kde.syntax-highlighting/syntax". 0082 * This path should never be touched by other applications. 0083 * 0084 * -# Then, all custom files compiled into resources are loaded. 0085 * The resource path is ":/org.kde.syntax-highlighting/syntax-addons". 0086 * This path can be used by other libraries/applications to bundle specialized definitions. 0087 * Per default this path isn't used by the framework itself. 0088 * 0089 * -# Finally, the search path can be extended by calling addCustomSearchPath(). 0090 * A custom search path can either be a path on disk or again a path to 0091 * a Qt resource. 0092 * 0093 * Similarly, loading Theme files works as follows: 0094 * 0095 * -# First, all Theme files are loaded that are located in 0096 * QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QStringLiteral("org.kde.syntax-highlighting/themes"), QStandardPaths::LocateDirectory); 0097 * Under Unix, this uses $XDG_DATA_HOME and $XDG_DATA_DIRS, which could 0098 * map to $HOME/.local5/share/org.kde.syntax-highlighting/themes and 0099 * /usr/share/org.kde.syntax-highlighting/themes. 0100 * 0101 * -# Then, all files compiled into the library through resources are loaded. 0102 * The internal resource path is ":/org.kde.syntax-highlighting/themes". 0103 * This path should never be touched by other applications. 0104 * 0105 * -# Then, all custom files compiled into resources are loaded. 0106 * The resource path is ":/org.kde.syntax-highlighting/themes-addons". 0107 * This path can be used by other libraries/applications to bundle specialized themes. 0108 * Per default this path isn't used by the framework itself. 0109 * 0110 * -# Finally, all Theme%s located in the paths added addCustomSearchPath() 0111 * are loaded. 0112 * 0113 * @note Whenever a Definition or a Theme exists twice, the variant with 0114 * higher version is used. 0115 * 0116 * @note The QStandardPaths lookup can be disabled by compiling the framework with the -DNO_STANDARD_PATHS define. 0117 * 0118 * @see Definition, Theme, AbstractHighlighter 0119 * @since 5.28 0120 */ 0121 class KSYNTAXHIGHLIGHTING_EXPORT Repository : public QObject 0122 { 0123 Q_OBJECT 0124 Q_PROPERTY(QList<KSyntaxHighlighting::Definition> definitions READ definitions NOTIFY reloaded) 0125 Q_PROPERTY(QList<KSyntaxHighlighting::Theme> themes READ themes NOTIFY reloaded) 0126 0127 public: 0128 /** 0129 * Create a new syntax definition repository. 0130 * This will read the meta data information of all available syntax 0131 * definition, which is a moderately expensive operation, it's therefore 0132 * recommended to keep a single instance of Repository around as long 0133 * as you need highlighting in your application. 0134 */ 0135 Repository(); 0136 ~Repository(); 0137 0138 /** 0139 * Returns the Definition named @p defName. 0140 * 0141 * If no Definition is found, Definition::isValid() of the returned instance 0142 * returns false. 0143 * 0144 * @note This uses case sensitive, untranslated names. For instance, 0145 * the javascript.xml definition file sets its name to @e JavaScript. 0146 * Therefore, only the string "JavaScript" will return a valid 0147 * Definition file. 0148 */ 0149 Q_INVOKABLE KSyntaxHighlighting::Definition definitionForName(const QString &defName) const; 0150 0151 /** 0152 * Returns the best matching Definition for the file named @p fileName. 0153 * The match is performed based on the \e extensions and @e mimetype of 0154 * the definition files. If multiple matches are found, the one with the 0155 * highest priority is returned. 0156 * 0157 * If no match is found, Definition::isValid() of the returned instance 0158 * returns false. 0159 */ 0160 Q_INVOKABLE KSyntaxHighlighting::Definition definitionForFileName(const QString &fileName) const; 0161 0162 /** 0163 * Returns all Definition%s for the file named @p fileName sorted by priority. 0164 * The match is performed based on the \e extensions and @e mimetype of 0165 * the definition files. 0166 * 0167 * @since 5.56 0168 */ 0169 Q_INVOKABLE QList<KSyntaxHighlighting::Definition> definitionsForFileName(const QString &fileName) const; 0170 0171 /** 0172 * Returns the best matching Definition to the type named @p mimeType 0173 * 0174 * If no match is found, Definition::isValid() of the returned instance 0175 * returns false. 0176 * 0177 * @since 5.50 0178 */ 0179 Q_INVOKABLE KSyntaxHighlighting::Definition definitionForMimeType(const QString &mimeType) const; 0180 0181 /** 0182 * Returns all Definition%s to the type named @p mimeType sorted by priority 0183 * 0184 * @since 5.56 0185 */ 0186 Q_INVOKABLE QList<KSyntaxHighlighting::Definition> definitionsForMimeType(const QString &mimeType) const; 0187 0188 /** 0189 * Returns all available Definition%s. 0190 * Definition%ss are ordered by translated section and translated names, 0191 * for consistent displaying. 0192 */ 0193 Q_INVOKABLE QList<KSyntaxHighlighting::Definition> definitions() const; 0194 0195 /** 0196 * Returns all available color themes. 0197 * The returned list should never be empty. 0198 */ 0199 Q_INVOKABLE QList<KSyntaxHighlighting::Theme> themes() const; 0200 0201 /** 0202 * Returns the theme called @p themeName. 0203 * If the requested theme cannot be found, the retunred Theme is invalid, 0204 * see Theme::isValid(). 0205 */ 0206 Q_INVOKABLE KSyntaxHighlighting::Theme theme(const QString &themeName) const; 0207 0208 /** 0209 * Built-in default theme types. 0210 * @see defaultTheme() 0211 */ 0212 enum DefaultTheme { 0213 //! Theme with a light background color. 0214 LightTheme, 0215 //! Theme with a dark background color. 0216 DarkTheme 0217 }; 0218 Q_ENUM(DefaultTheme) 0219 0220 /** 0221 * Returns a default theme instance of the given type. 0222 * The returned Theme is guaranteed to be a valid theme. 0223 * @since 5.79 0224 */ 0225 Q_INVOKABLE KSyntaxHighlighting::Theme defaultTheme(DefaultTheme t = LightTheme) const; 0226 0227 /** 0228 * Returns the best matching theme for the given palette 0229 * @since 5.79 0230 **/ 0231 Theme themeForPalette(const QPalette &palette) const; 0232 0233 /** 0234 * Reloads the repository. 0235 * This is a moderately expensive operations and should thus only be 0236 * triggered when the installed syntax definition files changed. 0237 */ 0238 void reload(); 0239 0240 /** 0241 * Add a custom search path to the repository. 0242 * This path will be searched in addition to the usual locations for syntax 0243 * and theme definition files. Both locations on disk as well as Qt 0244 * resource paths are supported. 0245 * 0246 * @note Internally, the two sub-folders @p path/syntax as well as 0247 * @p path/themes are searched for additional Definition%s and 0248 * Theme%s. Do not append @e syntax or @e themes to @p path 0249 * yourself. 0250 * 0251 * @note Calling this triggers a reload() of the repository. 0252 * 0253 * @since 5.39 0254 */ 0255 void addCustomSearchPath(const QString &path); 0256 0257 /** 0258 * Returns the list of custom search paths added to the repository. 0259 * By default, this list is empty. 0260 * 0261 * @see addCustomSearchPath() 0262 * @since 5.39 0263 */ 0264 QList<QString> customSearchPaths() const; 0265 0266 Q_SIGNALS: 0267 /** 0268 * This signal is emitted before the reload is started. 0269 * @since 6.0 0270 */ 0271 void aboutToReload(); 0272 0273 /** 0274 * This signal is emitted when the reload is finished. 0275 * @since 6.0 0276 */ 0277 void reloaded(); 0278 0279 private: 0280 Q_DISABLE_COPY(Repository) 0281 friend class RepositoryPrivate; 0282 std::unique_ptr<RepositoryPrivate> d; 0283 }; 0284 0285 } 0286 0287 #endif // KSYNTAXHIGHLIGHTING_REPOSITORY_H