diff --git a/src/lib/abstracthighlighter.h b/src/lib/abstracthighlighter.h index e10e013..0342304 100644 --- a/src/lib/abstracthighlighter.h +++ b/src/lib/abstracthighlighter.h @@ -1,180 +1,181 @@ /* Copyright (C) 2016 Volker Krause This program is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . */ #ifndef KSYNTAXHIGHLIGHTING_ABSTRACTHIGHLIGHTERM_H #define KSYNTAXHIGHLIGHTING_ABSTRACTHIGHLIGHTERM_H #include "ksyntaxhighlighting_export.h" #include #include class QString; namespace KSyntaxHighlighting { class AbstractHighlighterPrivate; class Definition; class FoldingRegion; class Format; class State; class Theme; /** * Abstract base class for highlighters. * * @section abshl_intro Introduction * * The AbstractHighlighter provides an interface to highlight text. * * The SyntaxHighlighting framework already ships with one implementation, * namely the SyntaxHighlighter, which also derives from QSyntaxHighlighter, * meaning that it can be used to highlight a QTextDocument or a QML TextEdit. * In order to use the SyntaxHighlighter, just call setDefinition() and * setTheme(), and the associated documents will automatically be highlighted. * * However, if you want to use the SyntaxHighlighting framework to implement * your own syntax highlighter, you need to sublcass from AbstractHighlighter. * * @section abshl_impl Implementing your own Syntax Highlighter * * In order to implement your own syntax highlighter, you need to inherit from * AbstractHighlighter. Then, pass each text line that needs to be highlighted * in order to highlightLine(). Internally, highlightLine() uses the Definition * initially set through setDefinition() and the State of the previous text line * to parse and highlight the given text line. For each visual highlighting * change, highlightLine() will call applyFormat(). Therefore, reimplement * applyFormat() to get notified of the Format that is valid in the range * starting at the given offset with the specified length. Similarly, for each * text part that starts or ends a code folding region, highlightLine() will * call applyFolding(). Therefore, if you are interested in code folding, * reimplement applyFolding() to get notified of the starting and ending code * folding regions, again specified in the range starting at the given offset * with the given length. * * The Format class itself depends on the current Theme. A theme must be * initially set once such that the Format%s instances can be queried for * concrete colors. * * Optionally, you can also reimplement setTheme() and setDefinition() to get * notified whenever the Definition or the Theme changes. * * @see SyntaxHighlighter + * @since 5.28 */ class KSYNTAXHIGHLIGHTING_EXPORT AbstractHighlighter { public: virtual ~AbstractHighlighter(); /** * Returns the syntax definition used for highlighting. * * @see setDefinition() */ Definition definition() const; /** * Sets the syntax definition used for highlighting. * * Subclasses can re-implement this method to e.g. trigger * re-highlighting or clear internal data structures if needed. */ virtual void setDefinition(const Definition &def); /** * Returns the currently selected theme for highlighting. * * @note If no Theme was set through setTheme(), the returned Theme will be * invalid, see Theme::isValid(). */ Theme theme() const; /** * Sets the theme used for highlighting. * * Subclasses can re-implement this method to e.g. trigger * re-highlighing or to do general palette color setup. */ virtual void setTheme(const Theme &theme); protected: AbstractHighlighter(); AbstractHighlighter(AbstractHighlighterPrivate *dd); /** * Highlight the given line. Call this from your derived class * where appropriate. This will result in any number of applyFormat() * and applyFolding() calls as a result. * @param text A string containing the text of the line to highlight. * @param state The highlighting state handle returned by the call * to highlightLine() for the previous line. For the very first line, * just pass a default constructed State(). * @returns The state of the highlighing engine after processing the * given line. This needs to passed into highlightLine() for the * next line. You can store the state for efficient partial * re-highlighting for example during editing. * * @see applyFormat(), applyFolding() */ State highlightLine(const QString &text, const State &state); /** * Reimplement this to apply formats to your output. The provided @p format * is valid for the interval [@p offset, @p offset + @p length). * * @param offset The start column of the interval for which @p format matches * @param length The length of the matching text * @param format The Format that applies to the range [offset, offset + length) * * @note Make sure to set a valid Definition, otherwise the parameter * @p format is invalid for the entire line passed to highlightLine() * (cf. Format::isValid()). * * @see applyFolding(), highlightLine() */ virtual void applyFormat(int offset, int length, const Format &format) = 0; /** * Reimplement this to apply folding to your output. The provided * FoldingRegion @p region either stars or ends a code folding region in the * interval [@p offset, @p offset + @p length). * * @param offset The start column of the FoldingRegion * @param length The length of the matching text that starts / ends a * folding region * @param region The FoldingRegion that applies to the range [offset, offset + length) * * @note The FoldingRegion @p region is @e always either of type * FoldingRegion::Type::Begin or FoldingRegion::Type::End. * * @see applyFormat(), highlightLine(), FoldingRegion */ virtual void applyFolding(int offset, int length, FoldingRegion region); protected: AbstractHighlighterPrivate *d_ptr; private: Q_DECLARE_PRIVATE(AbstractHighlighter) Q_DISABLE_COPY(AbstractHighlighter) }; } Q_DECLARE_INTERFACE(KSyntaxHighlighting::AbstractHighlighter, "org.kde.SyntaxHighlighting.AbstractHighlighter") #endif // KSYNTAXHIGHLIGHTING_ABSTRACTHIGHLIGHTERM_H diff --git a/src/lib/definition.h b/src/lib/definition.h index d97e0a1..a03d486 100644 --- a/src/lib/definition.h +++ b/src/lib/definition.h @@ -1,185 +1,186 @@ /* Copyright (C) 2016 Volker Krause This program is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . */ #ifndef KSYNTAXHIGHLIGHTING_DEFINITION_H #define KSYNTAXHIGHLIGHTING_DEFINITION_H #include "ksyntaxhighlighting_export.h" #include #include class QString; class QStringList; template class QVector; namespace KSyntaxHighlighting { class Context; class Format; class KeywordList; class DefinitionData; /** * Represents a syntax definition. * * @section def_intro 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. * * @section def_info General Information * * 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 @e 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 Definition%s match the file, then the one * with higher priority() wins. * * @see Repository + * @since 5.28 */ class KSYNTAXHIGHLIGHTING_EXPORT Definition { public: /** * Default constructor, creating an empty (invalid) Definition instance. * isValid() for this instance returns @e false. * * Use the Repository instead to obtain valid instances. */ Definition(); /** * Copy constructor. * Both this definition as well as @p other share the Definition data. */ Definition(const Definition &other); /** * Destructor. */ ~Definition(); /** * Assignment operator. * Both this definition as well as @p rhs share the Definition data. */ Definition& operator=(const Definition &rhs); /** * Checks two definitions for equality. */ bool operator==(const Definition &other) const; /** * Checks two definitions for inequality. */ bool operator!=(const Definition &other) const; /** Checks whether this object refers to a valid syntax definition. */ bool isValid() const; /** Returns the full path to the definition XML file containing * the syntax definition. Note that this can be a path to QRC content. */ QString filePath() const; /** Name of the syntax. * Used for internal references, prefer translatedName() for display. */ QString name() const; /** Translated name for display. */ QString translatedName() const; /** The group this syntax definition belongs to. * For display, consider translatedSection(). */ QString section() const; /** Translated group name for display. */ QString translatedSection() const; /** Mime types associated with this syntax definition. */ QVector mimeTypes() const; /** * File extensions associated with this syntax definition. * The returned list contains wildcards. */ QVector extensions() const; /** Returns the definition version. */ int version() const; /** * Returns the definition priority. * A Definition with higher priority wins over Definitions with lower priorities. */ int priority() const; /** Returns @c true if this is an internal definition that should not be * displayed to the user. */ bool isHidden() const; /** Generalized language style, used for indentation. */ QString style() const; /** Indentation style to be used for this syntax. */ QString indenter() const; /** Name and email of the author of this syntax definition. */ QString author() const; /** License of this syntax definition. */ QString license() 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 foldingIgnoreList(), State::indentationBasedFoldingEnabled() */ bool indentationBasedFoldingEnabled() const; /** * If indentationBasedFoldingEnabled() returns @c 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 @c true. * * @see indentationBasedFoldingEnabled() */ QStringList foldingIgnoreList() const; private: friend class DefinitionData; friend class DefinitionRef; explicit Definition(const std::shared_ptr &dd); std::shared_ptr d; }; } Q_DECLARE_TYPEINFO(KSyntaxHighlighting::Definition, Q_MOVABLE_TYPE); #endif diff --git a/src/lib/definitiondownloader.h b/src/lib/definitiondownloader.h index 70ff227..64c3ea2 100644 --- a/src/lib/definitiondownloader.h +++ b/src/lib/definitiondownloader.h @@ -1,106 +1,107 @@ /* Copyright (C) 2016 Volker Krause This program is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . */ #ifndef KSYNTAXHIGHLIGHTING_DEFINITIONDOWNLOADER_H #define KSYNTAXHIGHLIGHTING_DEFINITIONDOWNLOADER_H #include "ksyntaxhighlighting_export.h" #include #include namespace KSyntaxHighlighting { class DefinitionDownloaderPrivate; class Repository; /** * Helper class to download definition file updates. * * With the DefinitionDownloader you can download new and update existing * syntax highlighting definition files (xml files). * * An example that updates the highlighting Definition%s and prints the current * update progress to the console may look as follows: * * @code * auto downloader = new DefinitionDownloader(repo); // repo is a pointer to a Repository * * // print update progress to console * QObject::connect(downloader, &DefinitionDownloader::informationMessage, [](const QString &msg) { * std::cout << qPrintable(msg) << std::endl; * }); * * // connect to signal done to delete the downloader later * QObject::connect(downloader, &DefinitionDownloader::done, * downloader, &DefinitionDownloader::deleteLater); * downloader->start(); * @endcode * * @see Repository, Definition + * @since 5.28 */ class KSYNTAXHIGHLIGHTING_EXPORT DefinitionDownloader : public QObject { Q_OBJECT public: /** * Constructor. * The Repository @p repo is used as reference to compare the versions of * the existing Definition%s with the ones that are available online. * * Optionally, @p parent is a pointer to the owner of this instance. */ explicit DefinitionDownloader(Repository *repo, QObject *parent = nullptr); /** * Destructor. */ ~DefinitionDownloader(); /** * Starts the update procedure. * Once no more updates are available (i.e. either the local definition files * are up-to-date, or all updates have been downloaded), the signal done() * is emitted. * * During the update process, the signal informationMessage() can be used * to display the current update progress to the user. * * @see done(), informationMessage() */ void start(); Q_SIGNALS: /** * Prints the information about the current state of the definition files. * If all files are up-to-date, this signal is emitted informing you that * all highlighting files are up-to-date. If there are updates, this signal * is emitted for each update being downloaded. */ void informationMessage(const QString &msg); /** * This signal is emitted when there are no pending downloads anymore. */ void done(); private: std::unique_ptr d; }; } #endif // KSYNTAXHIGHLIGHTING_DEFINITIONDOWNLOADER_H diff --git a/src/lib/foldingregion.h b/src/lib/foldingregion.h index 9f44a47..dd8de01 100644 --- a/src/lib/foldingregion.h +++ b/src/lib/foldingregion.h @@ -1,99 +1,100 @@ /* Copyright (C) 2016 Volker Krause This program is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . */ #ifndef KSYNTAXHIGHLIGHTING_FOLDINGREGION_H #define KSYNTAXHIGHLIGHTING_FOLDINGREGION_H #include "ksyntaxhighlighting_export.h" #include namespace KSyntaxHighlighting { -/** Represents a begin or end of a folding region. */ +/** Represents a begin or end of a folding region. + * @since 5.28 */ class KSYNTAXHIGHLIGHTING_EXPORT FoldingRegion { public: /** * Defines whether a FoldingRegion starts or ends a folding region. */ enum Type { //! Used internally as indicator for invalid FoldingRegion%s. None, //! Indicates the start of a FoldingRegion. Begin, //! Indicates the end of a FoldingRegion. End }; /** * Constructs an invalid folding region, meaning that isValid() returns @e false. * To obtain valid instances, see AbstractHighlighter::applyFolding(). */ FoldingRegion(); /** Compares two FoldingRegion instances for equality. */ bool operator==(const FoldingRegion &other) const; /** * Returns @c true if this is a valid folding region. * A valid FoldingRegion is defined by a type() other than Type::None. * * @note The FoldingRegion%s passed in AbstractHighlighter::applyFolding() * are always valid. */ bool isValid() const; /** * Returns a unique identifier for this folding region. * * As example, the C/C++ highlighter starts and ends a folding region for * scopes, e.g.: * \code * void foo() { // '{' starts a folding region * if (bar()) { // '{' starts a (nested) folding region * } // '}' ends the (nested) folding region * } // '}' ends the outer folding region * \endcode * In this example, all braces '{' and '}' have the same id(), meaning that * if you want to find the matching closing region for the first opening * brace, you need to do kind of a reference counting to find the correct * closing brace. */ quint16 id() const; /** * Returns whether this is the begin or end of a region. * * @note The FoldingRegion%s passed in AbstractHighlighter::applyFolding() * are always valid, i.e. either Type::Begin or Type::End. */ Type type() const; private: friend class Rule; FoldingRegion(Type type, quint16 id); quint16 m_type : 2; quint16 m_id: 14; }; } Q_DECLARE_TYPEINFO(KSyntaxHighlighting::FoldingRegion, Q_PRIMITIVE_TYPE); #endif diff --git a/src/lib/format.h b/src/lib/format.h index cf87737..3e9ddb6 100644 --- a/src/lib/format.h +++ b/src/lib/format.h @@ -1,132 +1,133 @@ /* Copyright (C) 2016 Volker Krause This program is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . */ #ifndef KSYNTAXHIGHLIGHTING_FORMAT_H #define KSYNTAXHIGHLIGHTING_FORMAT_H #include "ksyntaxhighlighting_export.h" #include #include class QColor; class QString; class QXmlStreamReader; namespace KSyntaxHighlighting { class DefinitionRef; class FormatPrivate; class Theme; /** Describes the format to be used for a specific text fragment. * The actual format used for displaying is merged from the format information * in the syntax definition file, and a theme. * * @see Theme + * @since 5.28 */ class KSYNTAXHIGHLIGHTING_EXPORT Format { public: /** Creates an empty/invalid format. */ Format(); Format(const Format &other); ~Format(); Format& operator=(const Format &other); /** Returns @c true if this is a valid format, ie. one that * was read from a syntax definition file. */ bool isValid() const; /** The name of this format as used in the syntax definition file. */ QString name() const; /** Returns a unique identifier of this format. * This is useful for efficient storing of formats in a text line. The * identifier is unique per Repository instance, but will change when * the repository is reloaded (which also invalidatess the corresponding * Definition anyway). */ quint16 id() const; /** Returns @c true if the combination of this format and the theme @p theme * do not change the default text format in any way. * This is useful for output formats where changing formatting implies cost, * and thus benefit from optimizing the default case of not having any format * applied. If you make use of this, make sure to set the default text style * to what the corresponding theme sets for Theme::Normal. */ bool isDefaultTextStyle(const Theme &theme) const; /** Returns @c true if the combination of this format and the theme @p theme * change the foreground color compared to the default format. */ bool hasTextColor(const Theme &theme) const; /** Returns the foreground color of the combination of this format and the * given theme. */ QColor textColor(const Theme &theme) const; /** Returns the foreground color for selected text of the combination of * this format and the given theme. */ QColor selectedTextColor(const Theme &theme) const; /** Returns @c true if the combination of this format and the theme @p theme * change the background color compared to the default format. */ bool hasBackgroundColor(const Theme &theme) const; /** Returns the background color of the combination of this format and the * given theme. */ QColor backgroundColor(const Theme &theme) const; /** Returns the background color of selected text of the combination of * this format and the given theme. */ QColor selectedBackgroundColor(const Theme &theme) const; /** Returns @c true if the combination of this format and the given theme * results in bold text formatting. */ bool isBold(const Theme &theme) const; /** Returns @c true if the combination of this format and the given theme * results in italic text formatting. */ bool isItalic(const Theme &theme) const; /** Returns @c true if the combination of this format and the given theme * results in underlined text. */ bool isUnderline(const Theme &theme) const; /** Returns @c true if the combination of this format and the given theme * results in struck through text. */ bool isStrikeThrough(const Theme &theme) const; /** * Returns whether characters with this format should be spell checked. */ bool spellCheck() const; private: friend class FormatPrivate; QExplicitlySharedDataPointer d; }; } Q_DECLARE_TYPEINFO(KSyntaxHighlighting::Format, Q_MOVABLE_TYPE); #endif // KSYNTAXHIGHLIGHTING_FORMAT_H diff --git a/src/lib/repository.h b/src/lib/repository.h index 782c11d..3b9ea9b 100644 --- a/src/lib/repository.h +++ b/src/lib/repository.h @@ -1,163 +1,164 @@ /* Copyright (C) 2016 Volker Krause This program is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . */ #ifndef KSYNTAXHIGHLIGHTING_REPOSITORY_H #define KSYNTAXHIGHLIGHTING_REPOSITORY_H #include "ksyntaxhighlighting_export.h" #include #include class QString; template class QVector; /** * @namespace KSyntaxHighlighting * * Syntax highlighting engine for Kate syntax definitions. * In order to access the syntax highlighting Definition files, use the * class Repository. * * @see Repository */ namespace KSyntaxHighlighting { class Definition; class RepositoryPrivate; class Theme; /** * @brief Syntax highlighting repository. * * @section repo_intro 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. * * @section repo_access 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 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. * * @see Definition, Theme, AbstractHighlighter + * @since 5.28 */ class KSYNTAXHIGHLIGHTING_EXPORT Repository { public: /** * 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. */ Repository(); ~Repository(); /** * Returns the Definition named @p defName. * * If no Definition is found, Definition::isValid() of the returned instance * returns false. * * @note This uses case sensitive, untranslated names. For instance, * the javascript.xml definition file sets its name to @e JavaScript. * Therefore, only the string "JavaScript" will return a valid * Definition file. */ Definition definitionForName(const QString &defName) const; /** * Returns the best matching Definition for the file named @p fileName. * The match is performed based on the \e extensions and @e 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 definitionForFileName(const QString &fileName) const; /** * Returns all available Definition%s. * Definition%ss are ordered by translated section and translated names, * for consistent displaying. */ QVector definitions() const; /** * Returns all available color themes. * The returned list should never be empty. */ QVector themes() const; /** * Returns the theme called @p themeName. * If the requested theme cannot be found, the retunred Theme is invalid, * see Theme::isValid(). */ Theme theme(const QString &themeName) const; /** * Built-in default theme types. * @see defaultTheme() */ enum DefaultTheme { //! Theme with a light background color. LightTheme, //! Theme with a dark background color. DarkTheme }; /** * Returns a default theme instance of the given type. * The returned Theme is guaranteed to be a valid theme. */ Theme defaultTheme(DefaultTheme t = LightTheme); /** * Reloads the repository. * This is a moderately expensive operations and should thus only be * triggered when the installed syntax definition files changed. */ void reload(); private: Q_DISABLE_COPY(Repository) friend class RepositoryPrivate; std::unique_ptr d; }; } #endif // KSYNTAXHIGHLIGHTING_REPOSITORY_H diff --git a/src/lib/state.h b/src/lib/state.h index 576e456..1fb53fc 100644 --- a/src/lib/state.h +++ b/src/lib/state.h @@ -1,76 +1,78 @@ /* Copyright (C) 2016 Volker Krause This program is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . */ #ifndef KSYNTAXHIGHLIGHTING_STATE_H #define KSYNTAXHIGHLIGHTING_STATE_H #include "ksyntaxhighlighting_export.h" #include #include namespace KSyntaxHighlighting { class StateData; /** Opaque handle to the state of the highlighting engine. * This needs to be fed into AbstractHighlighter for every line of text * and allows concrete highlighter implementations to store state per * line for fast re-highlighting of specific lines (e.g. during editing). + * + * @since 5.28 */ class KSYNTAXHIGHLIGHTING_EXPORT State { public: /** Creates an initial state, ie. what should be used for the first line * in a document. */ State(); State(const State &other); ~State(); State& operator=(const State &rhs); /** Compares two states for equality. * For two equal states and identical text input, AbstractHighlighter * guarantees to produce equal results. This can be used to only * re-highlight as many lines as necessary during editing. */ bool operator==(const State &other) const; /** Compares two states for inequality. * This is the opposite of operator==(). */ bool operator!=(const State &other) const; /** * Returns whether or not indentation-based folding is enabled in this state. * When using a Definition with indentation-based folding, use * this method to check if indentation-based folding has been * suspended in the current line. * * @see Definition::indentationBasedFoldingEnabled() */ bool indentationBasedFoldingEnabled() const; private: friend class StateData; QExplicitlySharedDataPointer d; }; } Q_DECLARE_TYPEINFO(KSyntaxHighlighting::State, Q_MOVABLE_TYPE); #endif // KSYNTAXHIGHLIGHTING_STATE_H diff --git a/src/lib/syntaxhighlighter.h b/src/lib/syntaxhighlighter.h index 287e709..d137749 100644 --- a/src/lib/syntaxhighlighter.h +++ b/src/lib/syntaxhighlighter.h @@ -1,77 +1,79 @@ /* Copyright (C) 2016 Volker Krause This program is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . */ #ifndef KSYNTAXHIGHLIGHTING_QSYNTAXHIGHLIGHTER_H #define KSYNTAXHIGHLIGHTING_QSYNTAXHIGHLIGHTER_H #include "ksyntaxhighlighting_export.h" #include "abstracthighlighter.h" #include namespace KSyntaxHighlighting { class SyntaxHighlighterPrivate; /** A QSyntaxHighlighter implementation for use with QTextDocument. * This supports partial re-highlighting during editing and * tracks syntax-based code folding regions. + * + * @since 5.28 */ class KSYNTAXHIGHLIGHTING_EXPORT SyntaxHighlighter : public QSyntaxHighlighter, public AbstractHighlighter { Q_OBJECT public: explicit SyntaxHighlighter(QObject *parent = nullptr); explicit SyntaxHighlighter(QTextDocument *document); ~SyntaxHighlighter(); void setDefinition(const Definition &def) Q_DECL_OVERRIDE; /** Returns whether there is a folding region beginning at @p startBlock. * This only considers syntax-based folding regions, * not indention-based ones as e.g. found in Python. * * @see findFoldingRegionEnd */ bool startsFoldingRegion(const QTextBlock &startBlock) const; /** Finds the end of the folding region starting at @p startBlock. * If multiple folding regions begin at @p startBlock, the end of * the last/innermost one is returned. * This returns an invalid block if no folding region end is found, * which typically indicates an unterminated region and thus folding * until the document end. * This method performs a sequential search starting at @p startBlock * for the matching folding region end, which is a potentially expensive * operation. * * @see startsFoldingRegion */ QTextBlock findFoldingRegionEnd(const QTextBlock &startBlock) const; protected: void highlightBlock(const QString & text) Q_DECL_OVERRIDE; void applyFormat(int offset, int length, const Format &format) Q_DECL_OVERRIDE; void applyFolding(int offset, int length, FoldingRegion region) Q_DECL_OVERRIDE; private: Q_DECLARE_PRIVATE_D(AbstractHighlighter::d_ptr, SyntaxHighlighter) }; } #endif // KSYNTAXHIGHLIGHTING_QSYNTAXHIGHLIGHTER_H diff --git a/src/lib/theme.h b/src/lib/theme.h index 5e22940..e222e78 100644 --- a/src/lib/theme.h +++ b/src/lib/theme.h @@ -1,359 +1,360 @@ /* Copyright (C) 2016 Volker Krause This program is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . */ #ifndef KSYNTAXHIGHLIGHTING_THEME_H #define KSYNTAXHIGHLIGHTING_THEME_H #include "ksyntaxhighlighting_export.h" #include #include #include #include namespace KSyntaxHighlighting { class ThemeData; class RepositoryPrivate; /** * Color theme definition used for highlighting. * * @section theme_intro Introduction * * The Theme provides a full color theme for painting the highlighted text. * One Theme is defined either as a *.theme file on disk, or as a file compiled * into the SyntaxHighlighting library by using Qt's resource system. Each * Theme has a unique name(), including a translatedName() if put into the UI. * Themes shipped by default are typically read-only, see isReadOnly(). * * A Theme defines two sets of colors: * - Text colors, including foreground and background colors, colors for * selected text, and properties such as bold and italic. These colors are * used e.g. by the SyntaxHighlighter. * - Editor colors, including a background color for the entire editor widget, * the line number color, code folding colors, etc. * * @section theme_text_colors Text Colors and the Class Format * * The text colors are used for syntax highlighting. * // TODO: elaborate more and explain relation to Format class * * @section theme_editor_colors Editor Colors * * If you want to use the SyntaxHighlighting framework to write your own text * editor, you also need to paint the background of the editing widget. In * addition, the editor may support showing line numbers, a folding bar, a * highlight for the current text line, and similar features. All these colors * are defined in terms of the "editor colors" and accessible by calling * editorColor() with the desired enum EditorColorRole. * * @section theme_access Accessing a Theme * * All available Theme%s are accessed through the Repository. These themes are * typically valid themes. If you create a Theme on your own, isValid() will * return @e false, and all colors provided by this Theme are in fact invalid * and therefore unusable. * * @see Format + * @since 5.28 */ class KSYNTAXHIGHLIGHTING_EXPORT Theme { Q_GADGET public: /** * Default styles that can be referenced from syntax definition XML files. * Make sure to choose readable colors with good contrast especially in * combination with the EditorColorRole%s. */ enum TextStyle { //! Default text style for normal text and source code without //! special highlighting. Normal = 0, //! Text style for language keywords. Keyword, //! Text style for function definitions and function calls. Function, //! Text style for variables, if applicable. For instance, variables in //! PHP typically start with a '$', so all identifiers following the //! pattern $foo are highlighted as variable. Variable, //! Text style for control flow highlighting, such as @e if, @e then, //! @e else, @e return, or @e continue. ControlFlow, //! Text style for operators such as +, -, *, / and :: etc. Operator, //! Text style for built-in language classes and functions. BuiltIn, //! Text style for well-known extensions, such as Qt or boost. Extension, //! Text style for preprocessor statements. Preprocessor, //! Text style for attributes of functions or objects, e.g. \@override //! in Java, or __declspec(...) and __attribute__((...)) in C++. Attribute, //! Text style for single characters such as 'a'. Char, //! Text style for escaped characters in strings, such as "hello\n". SpecialChar, //! Text style for strings, for instance "hello world". String, //! Text style for verbatim strings such as HERE docs. VerbatimString, //! Text style for special strings such as regular expressions in //! ECMAScript or the LaTeX math mode. SpecialString, //! Text style for includes, imports, modules, or LaTeX packages. Import, //! Text style for data types such as int, char, float etc. DataType, //! Text style for decimal values. DecVal, //! Text style for numbers with base other than 10. BaseN, //! Text style for floating point numbers. Float, //! Text style for language constants, e.g. True, False, None in Python //! or nullptr in C/C++. Constant, //! Text style for normal comments. Comment, //! Text style for comments that reflect API documentation, such as //! doxygen /** */ comments. Documentation, //! Text style for annotations in comments, such as \@param in Doxygen //! or JavaDoc. Annotation, //! Text style that refers to variables in a comment, such as after //! \@param \ in Doxygen or JavaDoc. CommentVar, //! Text style for region markers, typically defined by BEGIN/END. RegionMarker, //! Text style for information, such as the keyword \@note in Doxygen. Information, //! Text style for warnings, such as the keyword \@warning in Doxygen. Warning, //! Text style for comment specials such as TODO and WARNING in //! comments. Alert, //! Text style indicating wrong syntax. Error, //! Text style for attributes that do not match any of the other default //! styles. Others }; Q_ENUM(TextStyle) /** * Editor color roles, used to paint line numbers, editor background etc. * The colors typically should have good contrast with the colors used * in the TextStyle%s. */ enum EditorColorRole { //! Background color for the editing area. BackgroundColor = 0, //! Background color for selected text. TextSelection, //! Background color for the line of the current text cursor. CurrentLine, //! Background color for matching text while searching. SearchHighlight, //! Background color for replaced text for a search & replace action. ReplaceHighlight, //! Background color for matching bracket pairs (including quotes) BracketMatching, //! Foreground color for visualizing tabs and trailing spaces. TabMarker, //! Color used to underline spell check errors. SpellChecking, //! Color used to draw vertical indentation levels, typically a line. IndentationLine, //! Background color for the icon border. IconBorder, //! Background colors for code folding regions in the text area, as well //! as code folding indicators in the code folding border. CodeFolding, //! Foreground color for drawing the line numbers. This should have a //! good contrast with the IconBorder background color. LineNumbers, //! Foreground color for drawing the current line number. This should //! have a good contrast with the IconBorder background color. CurrentLineNumber, //! Color used in the icon border to indicate dynamically wrapped lines. //! This color should have a good contrast with the IconBorder //! background color. WordWrapMarker, //! Color used to draw a vertical line for marking changed lines. ModifiedLines, //! Color used to draw a vertical line for marking saved lines. SavedLines, //! Line color used to draw separator lines, e.g. at column 80 in the //! text editor area. Separator, //! Background color for bookmarks. MarkBookmark, //! Background color for active breakpoints. MarkBreakpointActive, //! Background color for a reached breakpoint. MarkBreakpointReached, //! Background color for inactive (disabled) breakpoints. MarkBreakpointDisabled, //! Background color for marking the current execution position. MarkExecution, //! Background color for general warning marks. MarkWarning, //! Background color for general error marks. MarkError, //! Background color for text templates (snippets). TemplateBackground, //! Background color for all editable placeholders in text templates. TemplatePlaceholder, //! Background color for the currently active placeholder in text //! templates. TemplateFocusedPlaceholder, //! Background color for read-only placeholders in text templates. TemplateReadOnlyPlaceholder }; Q_ENUM(EditorColorRole) /** * Default constructor, creating an invalid Theme, see isValid(). */ Theme(); /** * Copy constructor, sharing the Theme data with @p copy. */ Theme(const Theme ©); /** * Destructor. */ ~Theme(); /** * Assignment operator, sharing the Theme data with @p other. */ Theme &operator=(const Theme &other); /** * Returns @c true if this is a valid Theme. * If the theme is invalid, none of the returned colors are well-defined. */ bool isValid() const; /** * Returns the unique name of this Theme. * @see translatedName() */ QString name() const; /** * Returns the translated name of this Theme. The translated name can be * used in the user interface. */ QString translatedName() const; /** * Returns @c true if this Theme is read-only. * Typically, themes that are shipped by default are read-only. */ bool isReadOnly() const; /** * Returns the full path and file name to this Theme. * Themes from the Qt resource return the Qt resource path. * Themes from disk return the local path. * * If the theme is invalid (isValid()), an empty string is returned. */ QString filePath() const; /** * Returns the text color to be used for @p style. * @c 0 is returned for styles that do not specify a text color, * use the default text color in that case. */ QRgb textColor(TextStyle style) const; /** * Returns the selected text color to be used for @p style. * @c 0 is returned for styles that do not specify a selected text color, * use the default textColor() in that case. */ QRgb selectedTextColor(TextStyle style) const; /** * Returns the background color to be used for @p style. * @c 0 is returned for styles that do not specify a background color, * use the default background color in that case. */ QRgb backgroundColor(TextStyle style) const; /** * Returns the background color to be used for selected text for @p style. * @c 0 is returned for styles that do not specify a background color, * use the default backgroundColor() in that case. */ QRgb selectedBackgroundColor(TextStyle style) const; /** * Returns whether the given style should be shown in bold. */ bool isBold(TextStyle style) const; /** * Returns whether the given style should be shown in italic. */ bool isItalic(TextStyle style) const; /** * Returns whether the given style should be shown underlined. */ bool isUnderline(TextStyle style) const; /** * Returns whether the given style should be shown struck through. */ bool isStrikeThrough(TextStyle style) const; public: /** * Returns the editor color for the requested @p role. */ QRgb editorColor(EditorColorRole role) const; private: /** * Constructor taking a shared ThemeData instance. */ explicit Theme(ThemeData* data); friend class RepositoryPrivate; friend class ThemeData; private: /** * Shared data holder. */ QExplicitlySharedDataPointer m_data; }; } Q_DECLARE_TYPEINFO(KSyntaxHighlighting::Theme, Q_MOVABLE_TYPE); #endif // KSYNTAXHIGHLIGHTING_THEME_H