KSyntaxHighlighting::Repository Class
class KSyntaxHighlighting::RepositorySyntax highlighting repository. More...
| Header: | #include <KSyntaxHighlighting/Repository> |
| CMake: | find_package(KF6 REQUIRED COMPONENTS KSyntaxHighlighting)target_link_libraries(mytarget PRIVATE KF6::KSyntaxHighlighting) |
| Since: | 5.28 |
| Inherits: | QObject |
Properties
- definitions : const QList<KSyntaxHighlighting::Definition>
- themes : const QList<KSyntaxHighlighting::Theme>
Public Functions
| Repository() | |
(since 5.39) void | addCustomSearchPath(const QString &path) |
(since 5.39) QList<QString> | customSearchPaths() const |
(since 5.79) KSyntaxHighlighting::Theme | defaultTheme(KSyntaxHighlighting::Repository::DefaultTheme t = LightTheme) const |
| KSyntaxHighlighting::Definition | definitionForFileName(const QString &fileName) const |
(since 5.50) KSyntaxHighlighting::Definition | definitionForMimeType(const QString &mimeType) const |
| KSyntaxHighlighting::Definition | definitionForName(const QString &defName) const |
| QList<KSyntaxHighlighting::Definition> | definitions() const |
(since 5.56) QList<KSyntaxHighlighting::Definition> | definitionsForFileName(const QString &fileName) const |
(since 5.56) QList<KSyntaxHighlighting::Definition> | definitionsForMimeType(const QString &mimeType) const |
| void | reload() |
| KSyntaxHighlighting::Theme | theme(const QString &themeName) const |
(since 5.79) KSyntaxHighlighting::Theme | themeForPalette(const QPalette &palette) const |
| QList<KSyntaxHighlighting::Theme> | themes() const |
Signals
(since 6.0) void | aboutToReload() |
(since 6.0) void | reloaded() |
Detailed Description
The Repository gives access to all syntax Definitions available on the system, typically described in *.xml files. The Definition files are read from the resource that is compiled into the executable, and from the file system. If a Definition exists in the resource and on the file system, then the one from the file system is chosen.
Typically, only one instance of the Repository is needed. This single instance can be thought of as a singleton you keep alive throughout the lifetime of your application. Then, either call definitionForName() with the given language name (e.g. "QML" or "Java"), or definitionForFileName() to obtain a Definition based on the filename/mimetype of the file. The function definitions() returns a list of all available syntax Definition%s.
In addition to Definitions, the Repository also provides a list of Themes. A Theme is defined by a set of default text style colors as well as editor colors. These colors together provide all required colros for drawing all primitives of a text editor. All available Theme%s can be queried through themes(), and a Theme with a specific name is obtained through theme(). Additionally, defaultTheme() provides a way to obtain a default theme for either a light or a black color theme.
All highlighting Definition and Theme files are compiled into the shared KSyntaxHighlighting library by using the Qt resource system. Loading additional files from disk is supported as well.
Loading syntax Definition files works as follows:
- First, all syntax highlighting files are loaded that are located in QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QStringLiteral("org.kde.syntax-highlighting/syntax"), QStandardPaths::LocateDirectory); Under Unix, this uses $XDG_DATA_HOME and $XDG_DATA_DIRS, which could map to $HOME/.local5/share/org.kde.syntax-highlighting/syntax and /usr/share/org.kde.syntax-highlighting/syntax.
- Then, all files compiled into the library through resources are loaded. The internal resource path is ":/org.kde.syntax-highlighting/syntax". This path should never be touched by other applications.
- Then, all custom files compiled into resources are loaded. The resource path is ":/org.kde.syntax-highlighting/syntax-addons". This path can be used by other libraries/applications to bundle specialized definitions. Per default this path isn't used by the framework itself.
- Finally, the search path can be extended by calling addCustomSearchPath(). A custom search path can either be a path on disk or again a path to a Qt resource.
Similarly, loading Theme files works as follows:
- First, all Theme files are loaded that are located in QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QStringLiteral("org.kde.syntax-highlighting/themes"), QStandardPaths::LocateDirectory); Under Unix, this uses $XDG_DATA_HOME and $XDG_DATA_DIRS, which could map to $HOME/.local5/share/org.kde.syntax-highlighting/themes and /usr/share/org.kde.syntax-highlighting/themes.
- Then, all files compiled into the library through resources are loaded. The internal resource path is ":/org.kde.syntax-highlighting/themes". This path should never be touched by other applications.
- Then, all custom files compiled into resources are loaded. The resource path is ":/org.kde.syntax-highlighting/themes-addons". This path can be used by other libraries/applications to bundle specialized themes. Per default this path isn't used by the framework itself.
- Finally, all Theme%s located in the paths added addCustomSearchPath() are loaded.
Note: Whenever a Definition or a Theme exists twice, the variant with higher version is used.
Note: The QStandardPaths lookup can be disabled by compiling the framework with the -DNO_STANDARD_PATHS define.
See also Definition, Theme, and AbstractHighlighter.
Property Documentation
[read-only] definitions : const QList<KSyntaxHighlighting::Definition>
Access functions:
| QList<KSyntaxHighlighting::Definition> | definitions() const | [see note below] |
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
Notifier signal:
| void | reloaded() |
[read-only] themes : const QList<KSyntaxHighlighting::Theme>
Access functions:
| QList<KSyntaxHighlighting::Theme> | themes() const | [see note below] |
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
Notifier signal:
| void | reloaded() |
Member Function Documentation
Repository::Repository()
Create a new syntax definition repository. This will read the meta data information of all available syntax definition, which is a moderately expensive operation, it's therefore recommended to keep a single instance of Repository around as long as you need highlighting in your application.
[signal, since 6.0] void Repository::aboutToReload()
This signal is emitted before the reload is started.
This function was introduced in 6.0.
[since 5.39] void Repository::addCustomSearchPath(const QString &path)
Add a custom search path to the repository. This path will be searched in addition to the usual locations for syntax and theme definition files. Both locations on disk as well as Qt resource paths are supported.
Note: Internally, the two sub-folders path/syntax as well as path/themes are searched for additional Definition%s and Theme%s. Do not append syntax or themes to path yourself.
Note: Calling this triggers a reload() of the repository.
This function was introduced in 5.39.
[since 5.39] QList<QString> Repository::customSearchPaths() const
Returns the list of custom search paths added to the repository. By default, this list is empty.
This function was introduced in 5.39.
See also addCustomSearchPath().
[invokable, since 5.79] KSyntaxHighlighting::Theme Repository::defaultTheme(KSyntaxHighlighting::Repository::DefaultTheme t = LightTheme) const
Returns a default theme instance of the given type. The returned Theme is guaranteed to be a valid theme.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
This function was introduced in 5.79.
[invokable] KSyntaxHighlighting::Definition Repository::definitionForFileName(const QString &fileName) const
Returns the best matching Definition for the file named fileName. The match is performed based on the extensions and mimetype of the definition files. If multiple matches are found, the one with the highest priority is returned.
If no match is found, Definition::isValid() of the returned instance returns false.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable, since 5.50] KSyntaxHighlighting::Definition Repository::definitionForMimeType(const QString &mimeType) const
Returns the best matching Definition to the type named mimeType
If no match is found, Definition::isValid() of the returned instance returns false.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
This function was introduced in 5.50.
[invokable] KSyntaxHighlighting::Definition Repository::definitionForName(const QString &defName) const
Returns the Definition named defName.
If no Definition is found, Definition::isValid() of the returned instance returns false.
Note: The search is Qt::CaseInsensitive using untranslated names or alternative names. For instance, the cpp.xml definition file sets its name to C++ with an alternative name of CPP. Therefore, the strings "C++", "c++", "CPP" and "cpp" will all return a valid Definition file.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable] QList<KSyntaxHighlighting::Definition> Repository::definitions() const
Returns all available Definition%s. Definition%ss are ordered by translated section and translated names, for consistent displaying.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
Note: Getter function for property definitions.
[invokable, since 5.56] QList<KSyntaxHighlighting::Definition> Repository::definitionsForFileName(const QString &fileName) const
Returns all Definition%s for the file named fileName sorted by priority. The match is performed based on the extensions and mimetype of the definition files.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
This function was introduced in 5.56.
[invokable, since 5.56] QList<KSyntaxHighlighting::Definition> Repository::definitionsForMimeType(const QString &mimeType) const
Returns all Definition%s to the type named mimeType sorted by priority
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
This function was introduced in 5.56.
void Repository::reload()
Reloads the repository. This is a moderately expensive operations and should thus only be triggered when the installed syntax definition files changed.
[signal, since 6.0] void Repository::reloaded()
This signal is emitted when the reload is finished.
Note: Notifier signal for property definitions. Notifier signal for property themes.
This function was introduced in 6.0.
[invokable] KSyntaxHighlighting::Theme Repository::theme(const QString &themeName) const
Returns the theme called themeName. If the requested theme cannot be found, the retunred Theme is invalid, see Theme::isValid().
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[since 5.79] KSyntaxHighlighting::Theme Repository::themeForPalette(const QPalette &palette) const
Returns the best matching theme for the given palette
This function was introduced in 5.79.
[invokable] QList<KSyntaxHighlighting::Theme> Repository::themes() const
Returns all available color themes. The returned list should never be empty.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
Note: Getter function for property themes.