KSyntaxHighlighting::Definition

Search for usage in LXR

KSyntaxHighlighting::Definition Class Reference

#include <definition.h>

Properties

QString author
 
QString license
 
QString name
 
QString section
 
QString translatedName
 
QString translatedSection
 

Public Member Functions

 Definition ()
 
 Definition (const Definition &other)
 
 Definition (Definition &&other) noexcept
 
 ~Definition ()
 
bool operator!= (const Definition &other) const
 
Definitionoperator= (const Definition &rhs)
 
Definitionoperator= (Definition &&other) noexcept
 
bool operator== (const Definition &other) const
 
General Header Data
bool isValid () const
 
QString filePath () const
 
QString name () const
 
QStringList alternativeNames () const
 
QString translatedName () const
 
QString section () const
 
QString translatedSection () const
 
QList< QStringmimeTypes () const
 
QList< QStringextensions () const
 
int version () const
 
int priority () const
 
bool isHidden () const
 
QString style () const
 
QString indenter () const
 
QString author () const
 
QString license () const
 
Advanced Definition Data
bool isWordDelimiter (QChar c) const
 
bool isWordWrapDelimiter (QChar c) const
 
bool foldingEnabled () const
 
bool indentationBasedFoldingEnabled () const
 
QStringList foldingIgnoreList () const
 
QStringList keywordLists () const
 
QStringList keywordList (const QString &name) const
 
bool setKeywordList (const QString &name, const QStringList &content)
 
QList< Formatformats () const
 
QList< DefinitionincludedDefinitions () const
 
QString singleLineCommentMarker () const
 
CommentPosition singleLineCommentPosition () const
 
QPair< QString, QStringmultiLineCommentMarker () const
 
QList< QPair< QChar, QString > > characterEncodings () const
 

Detailed Description

Represents a syntax definition.

Introduction to Definitions

A Definition is the short term for a syntax highlighting definition. It typically is defined in terms of an XML syntax highlighting file, containing all information about a particular syntax highlighting. This includes the highlighting of keywords, information about code folding regions, and indentation preferences.

General Header Data

Each Definition contains a non-translated unique name() and a section(). In addition, for putting this information e.g. into menus, the functions translatedName() and translatedSection() are provided. However, if isHidden() returns true, the Definition should not be visible in the UI. The location of the Definition can be obtained through filePath(), which either is the location on disk or a path to a compiled-in Qt resource.

The supported files of a Definition are defined by the list of extensions(), and additionally by the list of mimeTypes(). Note, that extensions() returns wildcards that need to be matched against the filename of the file that requires highlighting. If multiple Definitions match the file, then the one with higher priority() wins.

Advanced Definition Data

Advanced text editors such as Kate require additional information from a Definition. For instance, foldingEnabled() defines whether a Definition has code folding regions that can be shown in a code folding pane. Or singleLineCommentMarker() and multiLineCommentMarker() provide comment markers that can be used for commenting/uncommenting code. Similarly, formats() returns a list of Format items defined by this Definition (which equal the itemDatas of a highlighting definition file). includedDefinitions() returns a list of all included Definitions referenced by this Definition via the rule IncludeRules, which is useful for displaying all Format items for color configuration in the user interface.

See also
Repository
Since
5.28

Definition at line 82 of file definition.h.

Property Documentation

◆ author

QString KSyntaxHighlighting::Definition::author
read

Definition at line 89 of file definition.h.

◆ license

QString KSyntaxHighlighting::Definition::license
read

Definition at line 90 of file definition.h.

◆ name

QString KSyntaxHighlighting::Definition::name
read

Definition at line 85 of file definition.h.

◆ section

QString KSyntaxHighlighting::Definition::section
read

Definition at line 87 of file definition.h.

◆ translatedName

QString KSyntaxHighlighting::Definition::translatedName
read

Definition at line 86 of file definition.h.

◆ translatedSection

QString KSyntaxHighlighting::Definition::translatedSection
read

Definition at line 88 of file definition.h.

Constructor & Destructor Documentation

◆ Definition() [1/3]

Definition::Definition ( )

Default constructor, creating an empty (invalid) Definition instance.

isValid() for this instance returns false.

Use the Repository instead to obtain valid instances.

Definition at line 44 of file definition.cpp.

◆ Definition() [2/3]

Definition::Definition ( Definition && other)
defaultnoexcept

Move constructor.

This definition takes the Definition data from other.

Note
other may only be assigned to or destroyed afterwards.
Since
5.86

◆ Definition() [3/3]

Definition::Definition ( const Definition & other)
default

Copy constructor.

Both this definition as well as other share the Definition data.

◆ ~Definition()

Definition::~Definition ( )
default

Destructor.

Member Function Documentation

◆ alternativeNames()

QStringList Definition::alternativeNames ( ) const

Alternate names the syntax can be referred to by.

Since
6.1

Definition at line 86 of file definition.cpp.

◆ author()

QString Definition::author ( ) const

Name and email of the author of this syntax definition.

Definition at line 148 of file definition.cpp.

◆ characterEncodings()

QList< QPair< QChar, QString > > Definition::characterEncodings ( ) const

Returns a list of character/string mapping that can be used for spell checking.

This is useful for instance when spell checking LaTeX, where the string "{A} represents the character Ä.

Since
5.50

Definition at line 279 of file definition.cpp.

◆ extensions()

QList< QString > Definition::extensions ( ) const

File extensions associated with this syntax definition.

The returned list contains wildcards.

Definition at line 118 of file definition.cpp.

◆ filePath()

QString Definition::filePath ( ) const

Returns the full path to the definition XML file containing the syntax definition.

Note that this can be a path to QRC content.

Definition at line 76 of file definition.cpp.

◆ foldingEnabled()

bool Definition::foldingEnabled ( ) const

Returns whether the highlighting supports code folding.

Code folding is supported either if the highlighting defines code folding regions or if indentationBasedFoldingEnabled() returns true.

Since
5.50
See also
indentationBasedFoldingEnabled()

Definition at line 170 of file definition.cpp.

◆ foldingIgnoreList()

QStringList Definition::foldingIgnoreList ( ) const

If indentationBasedFoldingEnabled() returns true, this function returns a list of regular expressions that represent empty lines.

That is, all lines matching entirely one of the regular expressions should be treated as empty lines when calculating the indentation-based folding ranges.

Note
This list is only of relevance, if indentationBasedFoldingEnabled() returns true.
See also
indentationBasedFoldingEnabled()

Definition at line 185 of file definition.cpp.

◆ formats()

QList< Format > Definition::formats ( ) const

Returns a list of all Format items used by this definition.

The order of the Format items equals the order of the itemDatas in the xml file.

Since
5.49

Definition at line 216 of file definition.cpp.

◆ includedDefinitions()

QList< Definition > Definition::includedDefinitions ( ) const

Returns a list of Definitions that are referenced with the IncludeRules rule.

The returned list does not include this Definition. In case no other Definitions are referenced via IncludeRules, the returned list is empty.

Since
5.49

Definition at line 229 of file definition.cpp.

◆ indentationBasedFoldingEnabled()

bool Definition::indentationBasedFoldingEnabled ( ) const

Returns whether indentation-based folding is enabled.

An example for indentation-based folding is Python. When indentation-based folding is enabled, make sure to also check foldingIgnoreList() for lines that should be treated as empty.

See also
foldingIgnoreList(), State::indentationBasedFoldingEnabled()

Definition at line 179 of file definition.cpp.

◆ indenter()

QString Definition::indenter ( ) const

Indentation style to be used for this syntax.

Definition at line 143 of file definition.cpp.

◆ isHidden()

bool Definition::isHidden ( ) const

Returns true if this is an internal definition that should not be displayed to the user.

Definition at line 133 of file definition.cpp.

◆ isValid()

bool Definition::isValid ( ) const

Checks whether this object refers to a valid syntax definition.

Definition at line 71 of file definition.cpp.

◆ isWordDelimiter()

bool Definition::isWordDelimiter ( QChar c) const

Returns whether the character c is a word delimiter.

A delimiter defines whether a characters is a word boundary. Internally, delimiters are used for matching keyword lists. As example, typically the dot '.' is a word delimiter. However, if you have a keyword in a keyword list that contains a dot, you have to add the dot to the weakDeliminator attribute of the general section in your highlighting definition. Similarly, sometimes additional delimiters are required, which can be specified in additionalDeliminator.

Checking whether a character is a delimiter is useful for instance if text is selected with double click. Typically, the whole word should be selected in this case. Similarly to the example above, the dot '.' usually acts as word delimiter. However, using this function you can implement text selection in such a way that keyword lists are correctly selected.

Note
By default, the list of delimiters contains the following characters: \t !%&()*+,-./:;<=>?[\]^{|}~
Since
5.50
See also
isWordWrapDelimiter()

Definition at line 158 of file definition.cpp.

◆ isWordWrapDelimiter()

bool Definition::isWordWrapDelimiter ( QChar c) const

Returns whether it is safe to break a line at before the character .

This is useful when wrapping a line e.g. by applying static word wrap.

As example, consider the LaTeX code

\command1\command2

Applying static word wrap could lead to the following code:

\command1\
command2

command2 without a leading backslash is invalid in LaTeX. If '\' is set as word wrap delimiter, isWordWrapDelimiter('\') then returns true, meaning that it is safe to break the line before . The resulting code then would be

\command1
\command2
Note
By default, the word wrap delimiters are equal to the word delimiters in isWordDelimiter().
Since
5.50
See also
isWordDelimiter()

Definition at line 164 of file definition.cpp.

◆ keywordList()

QStringList Definition::keywordList ( const QString & name) const

Returns the list of keywords for the keyword list name.

Since
5.49
See also
keywordLists(), setKeywordList()

Definition at line 197 of file definition.cpp.

◆ keywordLists()

QStringList Definition::keywordLists ( ) const

Returns the section names of keywords.

Since
5.49
See also
keywordList()

Definition at line 191 of file definition.cpp.

◆ license()

QString Definition::license ( ) const

License of this syntax definition.

Definition at line 153 of file definition.cpp.

◆ mimeTypes()

QList< QString > Definition::mimeTypes ( ) const

Mime types associated with this syntax definition.

Definition at line 113 of file definition.cpp.

◆ multiLineCommentMarker()

QPair< QString, QString > Definition::multiLineCommentMarker ( ) const

Returns the markers that start and end multiline comments.

For instance, in XML this is defined as "<!--" and "-->".

Since
5.50

Definition at line 273 of file definition.cpp.

◆ name()

QString Definition::name ( ) const

Name of the syntax.

Used for internal references, prefer translatedName() for display.

Definition at line 81 of file definition.cpp.

◆ operator!=()

bool Definition::operator!= ( const Definition & other) const

Checks two definitions for inequality.

Definition at line 66 of file definition.cpp.

◆ operator=() [1/2]

Definition & Definition::operator= ( const Definition & rhs)
default

Copy assignment operator.

Both this definition as well as rhs share the Definition data.

◆ operator=() [2/2]

Definition & Definition::operator= ( Definition && other)
defaultnoexcept

Move assignment operator.

This definition takes the Definition data from other.

Note
other may only be assigned to or destroyed afterwards.
Since
5.86

◆ operator==()

bool Definition::operator== ( const Definition & other) const

Checks two definitions for equality.

Definition at line 61 of file definition.cpp.

◆ priority()

int Definition::priority ( ) const

Returns the definition priority.

A Definition with higher priority wins over Definitions with lower priorities.

Definition at line 128 of file definition.cpp.

◆ section()

QString Definition::section ( ) const

The group this syntax definition belongs to.

For display, consider translatedSection().

Definition at line 99 of file definition.cpp.

◆ setKeywordList()

bool Definition::setKeywordList ( const QString & name,
const QStringList & content )

Set the contents of the keyword list name to content.

Only existing keywordLists() can be changed. For non-existent keyword lists, false is returned.

Whenever you change a keyword list, make sure to trigger a rehighlight of your documents. In case you are using QSyntaxHighlighter via SyntaxHighlighter, this can be done by calling SyntaxHighlighter::rehighlight().

Note
In general, changing keyword lists via setKeywordList() is discouraged, since if a keyword list name in the syntax highlighting definition file changes, the call setKeywordList() may suddenly fail.
See also
keywordList(), keywordLists()
Since
5.62

Definition at line 204 of file definition.cpp.

◆ singleLineCommentMarker()

QString Definition::singleLineCommentMarker ( ) const

Returns the marker that starts a single line comment.

For instance, in C++ the single line comment marker is "//".

Since
5.50
See also
singleLineCommentPosition();

Definition at line 261 of file definition.cpp.

◆ singleLineCommentPosition()

CommentPosition Definition::singleLineCommentPosition ( ) const

Returns the insert position of the comment marker for sinle line comments.

Since
5.50
See also
singleLineCommentMarker();

Definition at line 267 of file definition.cpp.

◆ style()

QString Definition::style ( ) const

Generalized language style, used for indentation.

Definition at line 138 of file definition.cpp.

◆ translatedName()

QString Definition::translatedName ( ) const

Translated name for display.

Definition at line 91 of file definition.cpp.

◆ translatedSection()

QString Definition::translatedSection ( ) const

Translated group name for display.

Definition at line 104 of file definition.cpp.

◆ version()

int Definition::version ( ) const

Returns the definition version.

Definition at line 123 of file definition.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Mon Nov 4 2024 16:38:04 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.