KSyntaxHighlighting::Repository Class Reference

#include <repository.h>

Inheritance diagram for KSyntaxHighlighting::Repository:

Public Types
enum	DefaultTheme { LightTheme , DarkTheme }
Public Types inherited from QObject
typedef	QObjectList

Properties
QList< KSyntaxHighlighting::Definition >	definitions
QList< KSyntaxHighlighting::Theme >	themes
Properties inherited from QObject
	objectName

Signals
void	aboutToReload ()
void	reloaded ()

Public Member Functions
	Repository ()
void	addCustomSearchPath (const QString &path)
QList< QString >	customSearchPaths () const
Q_INVOKABLE KSyntaxHighlighting::Theme	defaultTheme (DefaultTheme t=LightTheme) const
Q_INVOKABLE KSyntaxHighlighting::Definition	definitionForFileName (const QString &fileName) const
Q_INVOKABLE KSyntaxHighlighting::Definition	definitionForMimeType (const QString &mimeType) const
Q_INVOKABLE KSyntaxHighlighting::Definition	definitionForName (const QString &defName) const
Q_INVOKABLE QList< KSyntaxHighlighting::Definition >	definitions () const
Q_INVOKABLE QList< KSyntaxHighlighting::Definition >	definitionsForFileName (const QString &fileName) const
Q_INVOKABLE QList< KSyntaxHighlighting::Definition >	definitionsForMimeType (const QString &mimeType) const
void	reload ()
Q_INVOKABLE KSyntaxHighlighting::Theme	theme (const QString &themeName) const
Theme	themeForPalette (const QPalette &palette) const
Q_INVOKABLE QList< KSyntaxHighlighting::Theme >	themes () const
Public Member Functions inherited from QObject
	QObject (QObject *parent)
QBindable< QString >	bindableObjectName ()
bool	blockSignals (bool block)
const QObjectList &	children () const const
QMetaObject::Connection	connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
void	deleteLater ()
void	destroyed (QObject *obj)
bool	disconnect (const char *signal, const QObject *receiver, const char *method) const const
bool	disconnect (const QObject *receiver, const char *method) const const
void	dumpObjectInfo () const const
void	dumpObjectTree () const const
QList< QByteArray >	dynamicPropertyNames () const const
virtual bool	event (QEvent *e)
virtual bool	eventFilter (QObject *watched, QEvent *event)
T	findChild (const QString &name, Qt::FindChildOptions options) const const
QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const
QList< T >	findChildren (Qt::FindChildOptions options) const const
bool	inherits (const char *className) const const
void	installEventFilter (QObject *filterObj)
bool	isQuickItemType () const const
bool	isWidgetType () const const
bool	isWindowType () const const
void	killTimer (int id)
virtual const QMetaObject *	metaObject () const const
void	moveToThread (QThread *targetThread)
QString	objectName () const const
void	objectNameChanged (const QString &objectName)
QObject *	parent () const const
QVariant	property (const char *name) const const
	Q_CLASSINFO (Name, Value)
	Q_EMIT Q_EMIT
	Q_ENUM (...)
	Q_ENUM_NS (...)
	Q_ENUMS (...)
	Q_FLAG (...)
	Q_FLAG_NS (...)
	Q_FLAGS (...)
	Q_GADGET Q_GADGET
	Q_GADGET_EXPORT (EXPORT_MACRO)
	Q_INTERFACES (...)
	Q_INVOKABLE Q_INVOKABLE
	Q_MOC_INCLUDE Q_MOC_INCLUDE
	Q_NAMESPACE Q_NAMESPACE
	Q_NAMESPACE_EXPORT (EXPORT_MACRO)
	Q_OBJECT Q_OBJECT
	Q_PROPERTY (...)
	Q_REVISION Q_REVISION
	Q_SET_OBJECT_NAME (Object)
	Q_SIGNAL Q_SIGNAL
	Q_SIGNALS Q_SIGNALS
	Q_SLOT Q_SLOT
	Q_SLOTS Q_SLOTS
T	qobject_cast (const QObject *object)
T	qobject_cast (QObject *object)
	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
void	removeEventFilter (QObject *obj)
void	setObjectName (const QString &name)
void	setObjectName (QAnyStringView name)
void	setParent (QObject *parent)
bool	setProperty (const char *name, const QVariant &value)
bool	setProperty (const char *name, QVariant &&value)
bool	signalsBlocked () const const
int	startTimer (int interval, Qt::TimerType timerType)
int	startTimer (std::chrono::milliseconds interval, Qt::TimerType timerType)
QThread *	thread () const const

Additional Inherited Members
Static Public Member Functions inherited from QObject
QMetaObject::Connection	connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
QMetaObject::Connection	connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
bool	disconnect (const QMetaObject::Connection &connection)
bool	disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
bool	disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
bool	disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
QString	tr (const char *sourceText, const char *disambiguation, int n)
Protected Member Functions inherited from QObject
virtual void	childEvent (QChildEvent *event)
virtual void	connectNotify (const QMetaMethod &signal)
virtual void	customEvent (QEvent *event)
virtual void	disconnectNotify (const QMetaMethod &signal)
bool	isSignalConnected (const QMetaMethod &signal) const const
int	receivers (const char *signal) const const
QObject *	sender () const const
int	senderSignalIndex () const const
virtual void	timerEvent (QTimerEvent *event)

Detailed Description

Syntax highlighting repository.

Introduction

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.

Definitions and Themes

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 Definitions.

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 Themes 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.

Search Paths

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:

1. 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.
2. 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.
3. 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.
4. 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:

1. 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.
2. 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.
3. 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.
4. Finally, all Themes located in the paths added addCustomSearchPath() are loaded.

Note

Whenever a Definition or a Theme exists twice, the variant with higher version is used.

The QStandardPaths lookup can be disabled by compiling the framework with the -DNO_STANDARD_PATHS define.

See also

Definition, Theme, AbstractHighlighter

Since

5.28

Definition at line 121 of file repository.h.

Member Enumeration Documentation

DefaultTheme

enum KSyntaxHighlighting::Repository::DefaultTheme

Built-in default theme types.

See also

defaultTheme()

Enumerator
LightTheme	Theme with a light background color.
DarkTheme	Theme with a dark background color.

Definition at line 213 of file repository.h.

Property Documentation

definitions

QList<KSyntaxHighlighting::Definition> KSyntaxHighlighting::Repository::definitions

read

Definition at line 124 of file repository.h.

themes

QList<KSyntaxHighlighting::Theme> KSyntaxHighlighting::Repository::themes

read

Definition at line 125 of file repository.h.

Constructor & Destructor Documentation

Repository()

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.

Definition at line 103 of file repository.cpp.

~Repository()

Repository::~Repository

(

)

Definition at line 110 of file repository.cpp.

Member Function Documentation

aboutToReload

void KSyntaxHighlighting::Repository::aboutToReload ( )

signal

This signal is emitted before the reload is started.

Since

6.0

addCustomSearchPath()

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 Definitions and Themes. Do not append syntax or themes to path yourself.

Calling this triggers a reload() of the repository.

Since

5.39

Definition at line 420 of file repository.cpp.

customSearchPaths()

QList< QString > Repository::customSearchPaths

(

)

const

Returns the list of custom search paths added to the repository.

By default, this list is empty.

See also

addCustomSearchPath()

Since

5.39

Definition at line 432 of file repository.cpp.

defaultTheme()

Theme Repository::defaultTheme

(

Repository::DefaultTheme

t = LightTheme

)

const

Returns a default theme instance of the given type.

The returned Theme is guaranteed to be a valid theme.

Since

5.79

Definition at line 171 of file repository.cpp.

definitionForFileName()

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.

Definition at line 124 of file repository.cpp.

definitionForMimeType()

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.

Since

5.50

Definition at line 134 of file repository.cpp.

definitionForName()

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.

Definition at line 119 of file repository.cpp.

definitions()

QList< Definition > Repository::definitions

(

)

const

Returns all available Definitions.

Definitionss are ordered by translated section and translated names, for consistent displaying.

Definition at line 144 of file repository.cpp.

definitionsForFileName()

QList< Definition > Repository::definitionsForFileName

(

const QString &

fileName

)

const

Returns all Definitions for the file named fileName sorted by priority.

The match is performed based on the extensions and mimetype of the definition files.

Since

5.56

Definition at line 129 of file repository.cpp.

definitionsForMimeType()

QList< Definition > Repository::definitionsForMimeType

(

const QString &

mimeType

)

const

Returns all Definitions to the type named mimeType sorted by priority.

Since

5.56

Definition at line 139 of file repository.cpp.

reload()

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.

Definition at line 396 of file repository.cpp.

reloaded

void KSyntaxHighlighting::Repository::reloaded ( )

signal

This signal is emitted when the reload is finished.

Since

6.0

theme()

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().

Definition at line 161 of file repository.cpp.

themeForPalette()

Theme Repository::themeForPalette

(

const QPalette &

palette

)

const

Returns the best matching theme for the given palette.

Since

5.79

Definition at line 179 of file repository.cpp.

themes()

QList< Theme > Repository::themes

(

)

const

Returns all available color themes.

The returned list should never be empty.

Definition at line 149 of file repository.cpp.

---

The documentation for this class was generated from the following files:

• repository.h
• repository.cpp