YSSCore::Editor::ColorThemeProvider Class
class YSSCore::Editor::ColorThemeProvider颜色主题提供者，负责维护一组颜色主题及其样式数据. 详情...
| 头文件： | #include <ColorThemeProvider> |
| 自以下版本： | YSS 0.16.0 |
- 所有成员列表（包含继承成员）
- ColorThemeProvider 是该集合的一部分：语言服务框架.
公开成员函数
(自 YSS 0.16.0 引入) | ColorThemeProvider(YSSCore::Editor::LangServer *parent) |
(自 YSS 0.16.0 引入) | ~ColorThemeProvider() |
(自 YSS 0.16.0 引入) void | createNewTheme(const QString &themeName, const QString ©FromTheme) |
(自 YSS 0.16.0 引入) QString | deriveUserThemeToJson(const QString &themeName) |
(自 YSS 0.16.0 引入) QString | getCurrentTheme() |
(自 YSS 0.16.0 引入) QMap<QString, YSSCore::Editor::StyleData> | getCurrentThemeStyleData() |
(自 YSS 0.16.0 引入) YSSCore::Editor::StyleData | getCurrentThemeStyleData(const QString &styleName) |
(自 YSS 0.16.0 引入) YSSCore::Editor::StyleData | getStyleData(const QString &themeName, const QString &styleName) |
(自 YSS 0.16.0 引入) QStringList | getSupportedThemes() |
(自 YSS 0.16.0 引入) QString | getTemplateTextPath() |
(自 YSS 0.16.0 引入) QMap<QString, YSSCore::Editor::StyleData> | getThemeStyleData(const QString &themeName) |
(自 YSS 0.16.0 引入) bool | isStaticTheme(const QString &themeName) |
(自 YSS 0.16.0 引入) void | parseStaticThemeFrom(const QString &jsonStr) |
(自 YSS 0.16.0 引入) void | parseUserThemeFrom(const QString &jsonStr) |
(自 YSS 0.16.0 引入) void | removeTheme(const QString &themeName) |
(自 YSS 0.16.0 引入) void | setCurrentTheme(const QString &themeName) |
(自 YSS 0.16.0 引入) void | setTemplateTextPath(const QString &filePath) |
(自 YSS 0.16.0 引入) void | setThemeStyleData(const QString &themeName, const QMap<QString, YSSCore::Editor::StyleData> &styleData) |
信号
(自 YSS 0.16.0 引入) void | currentThemeChanged(const QString &themeName) |
(自 YSS 0.16.0 引入) void | themeAdded(const QString &themeName) |
(自 YSS 0.16.0 引入) void | themeModified(const QString &themeName) |
(自 YSS 0.16.0 引入) void | themeRemoved(const QString &themeName) |
详细说明
ColorThemeProvider是YSSCore::Editor::LangServer使用的颜色主题管理器，为语言服务器提供颜色主题服务。
请注意，这个颜色主题与Visindigo中的颜色主题与模板不是相同的概念。此处颜色主题仅提供给 编辑器使用，且一般来说，是给SyntaxHighlighter使用的。它与Visindigo中的颜色主题和模板没有直接关系。
SyntaxHighlighter可以通过ColorThemeProvider获取当前主题的样式数据，并据此设置编辑器中不同语法元素的颜色和样式。
每个颜色主题都通过一个主题名来唯一标识，主题名下保存了一组样式数据（YSSCore::Editor::StyleData）， 每个样式数据通过一个配置节点键（configNodeName）来索引。配置节点键是程序内部使用的索引，而 样式数据中的styleName是用于显示的可读字符串，二者并不相同。
主题可以通过JSON字符串解析和派生（参见parseStaticThemeFrom、parseUserThemeFrom和deriveUserThemeToJson）。 主题分为静态主题和用户主题：静态主题通过parseStaticThemeFrom解析，不允许被删除或修改； 用户主题可以通过createNewTheme创建、通过removeTheme删除，并可以通过setThemeStyleData修改。
持久化数据的自动管理
值得指出的是，这个类在实际使用中，有关持久化的需求大多已经由关联的其他类在后台自动完成，用户一般不需要再额外处理持久化数据。 为了方便维护，我们披露关联逻辑的一些细节如下：
- 1. 主题的样式数据会在切换当前主题时自动缓存到currentTheme中，以加速getCurrentThemeStyleData的访问。 用户一般不需要再缓存一次。
- 2. 用户数据的读取与保存在后台自动完成：当LangServer初始化时，会自动从 插件文件夹/_yss_auto_/LangServer/LangServerID 文件夹 读取*.theme.json文件并解析为用户主题，当用户主题发生变更时，LangServer也会在内部通过监听信号themeModified自动保存用户主题到文件中。
- 3. 在LangServer被注册到EditorPlugin后，EditorPlugin会自动从插件配置的 _yss_auto_.LangServer.LangServerId.CurrentTheme 配置项中读取当前设置的主题名， 并调用setCurrentTheme设置当前主题。且在currentTheme发生变化时，EditorPlugin也会自动将新的当前主题名写入该配置项。
因此，一般来说，在使用这个类时，理应只需在自己所派生的LangServer类的构造函数直接用parseStaticThemeFrom加载静态主题即可， 用户主题的读取和保存、当前主题的读取和保存都不需要额外处理。
在SyntaxHighlighter中应用样式
我们不推荐手动监听相关信号来做额外的持久化处理，因为这可能会导致重复保存或读取，造成不必要的性能开销。也不推荐通过 这些信号来在SyntaxHighlighter中应用样式，SyntaxHighlighter中已经提供了YSSCore::Editor::SyntaxHighlighter::onThemeChanged 虚函数来确保在所有需要SyntaxHighlighter更新样式的时机都能正确触发。
这里需要披露的具体差异是，当用户在配置页面中手动修改主题时，相关页面会直接调用配置页面预览编辑器内部的SyntaxHighlighter::onThemeChanged函数来更新样式， 而不实际改动任何现有主题数据，以避免不必要的持久化操作。只有当用户点击“保存”按钮时，才会真正修改主题数据并触发themeModified信号。
因此，为了使配置页面预览编辑器能正确相应用户在编辑中的修改，就必须且只能依赖onThemeChanged函数。
成员函数文档
[since YSS 0.16.0] ColorThemeProvider::ColorThemeProvider(YSSCore::Editor::LangServer *parent)
parent 所属的语言服务器。
构造一个颜色主题提供者。parent 将作为此对象的QObject父对象，同时用于关联所属的语言服务器。
这个function 从 YSS 0.16.0 开始支持。
[noexcept, since YSS 0.16.0] ColorThemeProvider::~ColorThemeProvider()
析构颜色主题提供者。
这个function 从 YSS 0.16.0 开始支持。
[since YSS 0.16.0] void ColorThemeProvider::createNewTheme(const QString &themeName, const QString ©FromTheme)
themeName 要创建的新主题的主题名。 copyFromTheme 要复制样式的源主题的主题名。
创建一个新的主题。如果 themeName 为空或已存在同名的主题，则不做任何操作。 如果 copyFromTheme 指定了一个已存在的主题，则新主题会复制该主题的全部样式数据， 否则新主题将不含任何样式数据。新创建的主题不会被视为静态主题。
这个function 从 YSS 0.16.0 开始支持。
[signal, since YSS 0.16.0] void ColorThemeProvider::currentThemeChanged(const QString &themeName)
themeName 新的当前主题的主题名。如果当前主题被删除导致没有当前主题，则为空字符串。
当前主题发生变化时发出此信号。当前主题发生变化的情况包括：通过setCurrentTheme切换当前主题， 或通过removeTheme删除当前主题。
这个function 从 YSS 0.16.0 开始支持。
[since YSS 0.16.0] QString ColorThemeProvider::deriveUserThemeToJson(const QString &themeName)
themeName 要派生为JSON的主题名。 return 表示指定主题的JSON字符串。如果主题不存在，则返回空字符串。
将指定主题派生为JSON字符串。JSON的结构与加载时的结构一致："name" 字段取 themeName 的值， "datas"下的每个键为配置节点键，对应的子对象通过Visindigo::Utility::JsonConfig::fromMetable 从YSSCore::Editor::StyleData生成。此函数不接触文件系统，由调用方自行决定如何保存返回的字符串。
这个function 从 YSS 0.16.0 开始支持。
[since YSS 0.16.0] QString ColorThemeProvider::getCurrentTheme()
return 当前主题的主题名。如果没有设置当前主题，则返回空字符串。
返回当前主题的主题名。
这个function 从 YSS 0.16.0 开始支持。
[since YSS 0.16.0] QMap<QString, YSSCore::Editor::StyleData> ColorThemeProvider::getCurrentThemeStyleData()
return 当前主题下所有配置节点键对应的样式数据。如果当前主题未设置，则返回空的QMap。
这个function 从 YSS 0.16.0 开始支持。
[since YSS 0.16.0] YSSCore::Editor::StyleData ColorThemeProvider::getCurrentThemeStyleData(const QString &styleName)
styleName 配置节点键。 return 当前主题下指定配置节点键对应的样式数据。如果当前主题未设置或配置节点不存在，则返回默认构造的StyleData。
返回当前主题下指定配置节点键对应的样式数据。
这个function 从 YSS 0.16.0 开始支持。
[since YSS 0.16.0] YSSCore::Editor::StyleData ColorThemeProvider::getStyleData(const QString &themeName, const QString &styleName)
themeName 主题名。 styleName 配置节点键。 return 指定主题下指定配置节点键对应的样式数据。如果主题或配置节点不存在，则返回默认构造的StyleData。
返回指定主题下指定配置节点键对应的样式数据。
这个function 从 YSS 0.16.0 开始支持。
[since YSS 0.16.0] QStringList ColorThemeProvider::getSupportedThemes()
return 所有已加载主题的主题名列表。
返回当前所有已加载主题的主题名列表，包括静态主题和用户主题。
如果没有任何主题，则列表是空的。
键的顺序与加载顺序无关，也不保证按照任何特定顺序排列。
这个function 从 YSS 0.16.0 开始支持。
[since YSS 0.16.0] QString ColorThemeProvider::getTemplateTextPath()
return 用作样式样本的文件的路径。
返回用作样式样本的文件的路径。
这个function 从 YSS 0.16.0 开始支持。
[since YSS 0.16.0] QMap<QString, YSSCore::Editor::StyleData> ColorThemeProvider::getThemeStyleData(const QString &themeName)
themeName 主题名。 return 指定主题的全部样式数据。如果主题不存在，则返回空的QMap。
返回指定主题下所有配置节点键对应的样式数据。
这个function 从 YSS 0.16.0 开始支持。
[since YSS 0.16.0] bool ColorThemeProvider::isStaticTheme(const QString &themeName)
themeName 主题名。 return 如果该主题是静态主题，返回true；否则返回false。
判断指定主题是否为静态主题。静态主题不允许被删除或修改。
这个function 从 YSS 0.16.0 开始支持。
[since YSS 0.16.0] void ColorThemeProvider::parseStaticThemeFrom(const QString &jsonStr)
jsonStr 静态主题的JSON字符串。
从JSON字符串解析一个静态主题。静态主题不允许被删除或修改（removeTheme和setThemeStyleData 对静态主题无效）。JSON的结构与parseUserThemeFrom相同，区别在于解析出的主题会被标记为静态主题。
此函数直接接收JSON字符串而不接触文件系统。
这个function 从 YSS 0.16.0 开始支持。
[since YSS 0.16.0] void ColorThemeProvider::parseUserThemeFrom(const QString &jsonStr)
jsonStr 用户主题的JSON字符串。
从JSON字符串解析一个用户主题。JSON的结构与parseStaticThemeFrom相同，区别在于此函数 不会将该主题标记为静态主题。
这个function 从 YSS 0.16.0 开始支持。
[since YSS 0.16.0] void ColorThemeProvider::removeTheme(const QString &themeName)
themeName 要删除的主题的主题名。
删除指定的主题。如果该主题是静态主题（参见isStaticTheme），则不允许删除，此函数不做任何操作。 如果被删除的主题是当前主题，则当前主题会被清空。
这个function 从 YSS 0.16.0 开始支持。
[since YSS 0.16.0] void ColorThemeProvider::setCurrentTheme(const QString &themeName)
themeName 要设为当前主题的主题名。
将指定主题设为当前主题。如果 themeName 对应的主题不存在，则不做任何操作。
这个function 从 YSS 0.16.0 开始支持。
[since YSS 0.16.0] void ColorThemeProvider::setTemplateTextPath(const QString &filePath)
filePath 用作样式样本的文件的路径。
设置用作样式样本的文件的路径。样式样本用于在配置页面预览编辑器中显示当前主题的样式效果。 此函数不检查文件是否存在，由调用方自行保证路径有效。
建议在此文件中尽可能多的展示所支持的全部配置节点键的样式，以便在配置页面预览编辑器中能完整展示当前主题的样式效果。
这个function 从 YSS 0.16.0 开始支持。
[since YSS 0.16.0] void ColorThemeProvider::setThemeStyleData(const QString &themeName, const QMap<QString, YSSCore::Editor::StyleData> &styleData)
themeName 主题名。 styleData 要设置的样式数据。
设置指定主题的全部样式数据。如果该主题是静态主题（参见isStaticTheme），则不允许修改， 此函数不做任何操作。如果主题不存在，则会创建该主题。
这个function 从 YSS 0.16.0 开始支持。
[signal, since YSS 0.16.0] void ColorThemeProvider::themeAdded(const QString &themeName)
themeName 新添加的主题的主题名。
当一个新的主题被添加时发出此信号。新主题可以通过createNewTheme创建，或通过parseStaticThemeFrom/parseUserThemeFrom解析。
这个function 从 YSS 0.16.0 开始支持。
[signal, since YSS 0.16.0] void ColorThemeProvider::themeModified(const QString &themeName)
themeName 被修改的主题的主题名。
当一个主题被修改时发出。通过setThemeStyleData修改主题的样式数据时会发出此信号，此外，setCurrentTheme也会在切换当前主题时发出此信号。
这个function 从 YSS 0.16.0 开始支持。
[signal, since YSS 0.16.0] void ColorThemeProvider::themeRemoved(const QString &themeName)
themeName 被删除的主题的主题名。
当一个主题被删除时发出此信号。主题可以通过removeTheme删除。 这个信号在removeTheme函数中发出，且在发出此信号时，主题已经被删除。
这个function 从 YSS 0.16.0 开始支持。