Visindigo
ThemeManager

Visindigo::Widgets::ThemeManager Class

class Visindigo::Widgets::ThemeManager

ThemeManager提供了比QPalette更宽泛的主题管理功能. 详情...

头文件：	`#include <Widgets/ThemeManager.h>`
自以下版本：	Visindigo 0.13.0

所有成员列表（包含继承成员）
ThemeManager 是该集合的一部分：VITheme主题系统子模块.

公开类型

(自 Visindigo 0.13.0 引入) enum ThemeID { __InAnimation__, Unknown, Light, Dark, White, …, __UserMin__ }

公开成员函数

`(自 Visindigo 0.13.0 引入)`	~ThemeManager()
`(自 Visindigo 0.13.0 引入)` bool	addColorSchemeToPriority(const QString &ID)
`(自 Visindigo 0.13.0 引入)` bool	addStyleTemplateToPriority(const QString &ID)
`(自 Visindigo 0.13.0 引入)` bool	changeColorTheme(Visindigo::Widgets::ThemeManager::ThemeID id)
`(自 Visindigo 0.13.0 引入)` bool	changeColorTheme(const QString &themeID)
`(自 Visindigo 0.13.0 引入)` void	clearColorSchemePriority()
`(自 Visindigo 0.13.0 引入)` void	clearStyleTemplatePriority()
`(自 Visindigo 0.13.0 引入)` QStringList	getAllColorSchemes()
`(自 Visindigo 0.13.0 引入)` QStringList	getAllStyleTemplates()
`(自 Visindigo 0.13.0 引入)` qint32	getAnimationDuration()
`(自 Visindigo 0.13.0 引入)` qint32	getAnimationFrameRate()
`(自 Visindigo 0.13.0 引入)` QStringList	getAvailableColorSchemes()
`(自 Visindigo 0.13.0 引入)` QStringList	getAvailableStyleTemplates()
`(自 Visindigo 0.13.0 引入)` QColor	getColor(const QString &key)
`(自 Visindigo 0.13.0 引入)` QStringList	getColorThemes()
`(自 Visindigo 0.13.0 引入)` QString	getCurrentColorTheme()
`(自 Visindigo 0.13.0 引入)` Visindigo::Utility::JsonConfig	getMergedColorScheme()
`(自 Visindigo 0.13.0 引入)` Visindigo::Widgets::StyleSheetTemplate	getMergedStyleSheetTemplate()
`(自 Visindigo 0.13.0 引入)` QString	getRawTemplate(const QString &key)
`(自 Visindigo 0.13.0 引入)` QStringList	getStyleNamespaces()
`(自 Visindigo 0.13.0 引入)` QString	getTemplate(const QString &key, QWidget *getter = nullptr)
`(自 Visindigo 0.13.0 引入)` bool	isAutoAdjustThemeToSystem()
`(自 Visindigo 0.13.0 引入)` bool	isColorSchemeFromPlugin(const QString &ID)
`(自 Visindigo 0.13.0 引入)` bool	isColorfulWidgetRegistered(Visindigo::Widgets::ColorfulWidget *widget)
`(自 Visindigo 0.13.0 引入)` bool	isStyleTemplateFromPlugin(const QString &ID)
`(自 Visindigo 0.13.0 引入)` void	loadAndRefresh(bool autoMergeAndApply = true)
`(自 Visindigo 0.13.0 引入)` void	mergeAndApply()
`(自 Visindigo 0.13.0 引入)` bool	pluginRegisterColorScheme(Visindigo::General::Plugin *plugin, const QString &jsonStr)
`(自 Visindigo 0.13.0 引入)` bool	pluginRegisterStyleTemplate(Visindigo::General::Plugin *plugin, QString vstStr)
`(自 Visindigo 0.13.0 引入)` void	registerColorfulWidget(Visindigo::Widgets::ColorfulWidget *widget)
`(自 Visindigo 0.13.0 引入)` bool	removeColorSchemeFromPriority(const QString &ID)
`(自 Visindigo 0.13.0 引入)` bool	removeStyleTemplateFromPriority(const QString &ID)
`(自 Visindigo 0.13.0 引入)` void	setAutoAdjustThemeToSystem(bool autoAdjust)
`(自 Visindigo 0.13.0 引入)` void	setColorSchemePriority(const QStringList &schemeIDList)
`(自 Visindigo 0.13.0 引入)` void	setStyleTemplatePriority(const QStringList &templateIDList)
`(自 Visindigo 0.13.0 引入)` void	unregisterColorfulWidget(Visindigo::Widgets::ColorfulWidget *widget)

信号

`(自 Visindigo 0.13.0 引入)` void	programThemeChanged(const QString &themeID)
`(自 Visindigo 0.13.0 引入)` void	systemThemeChanged(Qt::ColorScheme newScheme)

静态公开成员

`(自 Visindigo 0.13.0 引入)` Visindigo::Widgets::ThemeManager *	getInstance()
`(自 Visindigo 0.13.0 引入)` void	registerUserThemeID(const QString &id, Visindigo::Widgets::ThemeManager::ThemeID themeID)
`(自 Visindigo 0.13.0 引入)` Visindigo::Widgets::ThemeManager::ThemeID	stringToThemeID(const QString &str)
`(自 Visindigo 0.13.0 引入)` QString	themeIDToString(Visindigo::Widgets::ThemeManager::ThemeID id)

宏

`(自 Visindigo 0.13.0 引入)`	VISTM
`(自 Visindigo 0.13.0 引入)`	VISTMGRT
`(自 Visindigo 0.13.0 引入)`	VISTMGT

详细说明

Note: 这是一个从旧版Visindigo继承下来的功能（VIWidgets/VIDynamicStyleSheet），但已经重新实现，因此行为和接口与旧版有所不同。建议用户参考本类的文档和示例代码，以了解如何使用新版本。

Qt的主题管理功能主要通过QPalette实现，这是个非常好的设计，但它主要假定应用程序的主题是由程序全权决定的，而忽略了用户对主题的个性化需求。而ThemeManager则提供了复杂的主题管理功能，允许用户动态使用配色方案（Color Scheme）和样式模板（Style Template）。且允许通过配置加载顺序来组合多个配色方案和样式模板，从而实现更复杂的主题效果。

值得指出的是，这类通过操纵QStyleHints控制那些不属于VITheme的默认Qt组件外观，因此如果你要使用这个功能，就不能独自调用QStyleHints::setColorScheme方法和QStyleHints::unsetColorScheme方法。请使用ThemeManager::changeColorTheme方法变更主题。

基本概念 - 配色方案 (Color Scheme)

ThemeManager的主题管理功能主要基于两个概念：配色方案（Color Scheme）和样式模板（Style Template）。

Warning: 请注意，ThemeManager里面的Color Scheme和Color Theme是两个拼读相近（中文含义也相近）的概念，但它们是不同的东西。 Color Scheme是配色方案，一个方案里面可以包括多个Color Theme（色彩主题）。配色方案提供的若干个色彩主题（Color Theme）中只有一个会处于激活状态，ThemeManager会根据当前激活的色彩主题来获取颜色值。此外，Qt的配色方案（Color Scheme）和 ThemeManager的Color Theme（色彩主题）是同级概念，而非与ThemeManager的Color Scheme是同级概念。ThemeManager的Color Scheme大于Qt的Color Scheme。

配色方案是一组预定义的颜色集合，定义了应用程序中各种UI元素的颜色属性，如背景色、前景色、按钮色等。配色方案以JSON格式存储，结构如下：

{
        "SchemeID": "YSSDefault",
        "SchemeName": "Yayin Story Studio Default Color Scheme",
        "Themes": {
                "Dark":{
                        "Background_Light": "#3A3A3A",
                        ...
                },
                "...": { ... }
        }
}

即，配色方案包含一个SchemeID（主题ID），一个SchemeName（主题名称），以及一个Themes对象（色彩主题），这Theme对象内包含了多个色彩主题，每个色彩主题对应一组颜色键值对。主题的名称必须是ThemeManager::ThemeID枚举中的一个值（如"Dark"、"Light"等），也可以是用户自定义的主题名称。但需要通过ThemeManager::registerUserThemeID 方法注册才能正确识别。

基本概念 - 样式模板 (Style Template)

样式模板（Style Template）是若干组预定义的样式表（Style Sheet）的集合，这些样式表定义了应用程序中各种UI组件的外观和风格。

它为Qt Style Sheet 提供了两个重要的扩展：变量代换和命名空间。

变量代换允许在样式表中使用颜色主题中的颜色键作为变量，从而实现样式表与颜色主题的动态绑定。变量代换也允许使用此样式表的QWidget组件动态带入自己的property属性值作为变量，从而实现更灵活的样式定义。例如在下面的这个例子里，border-radius属性的值是通过${borderRadius}变量代换实现的，这个变量的值由使用此样式表的QWidget 组件的borderRadius属性决定。

!TemplateName: Default_Template
!TemplateID: YSS
------
!Namespace: General
@Default
QWidget{
        border: 1px solid $(Background_Light);
        border-radius: ${borderRadius}px;
}

样式模板文件以.vst扩展名存储，它总是遵照这样的格式，即首先使用模板名称、模板ID以及六条横线分隔符作为文件开头然后使用!Namespace定义命名空间，接着使用@StyleSheetName定义样式组名称，最后是样式组内容。

!Namespace是可选的，如果不定义，则样式表命名空间等同于模板ID。但样式组名称必须定义，用于引用这个样式组。一个样式组内可以有多个样式表，它们会被一同应用到使用此样式模板的组件上。

!TemplateName: Default_Template
!TemplateID: YSS
------
!Namespace: General
@Default
QWidget{
        border: 1px solid $(Background_Light);
        border-radius: ${borderRadius}px;
}
QPushButton{
        background-color: $(Button_Background);
        color: $(Button_Foreground);
}
@someOtherStyle
...

一个样式模板文件可以包含多个命名空间，每个命名空间内可以包含多个样式组：

!TemplateName: Default_Template
!TemplateID: YSS
------
!Namespace: General
@Default
...
@someOtherStyle
...

!Namespace: Special
@SpecialButton
...

要使用某个样式表，必须通过ThemeManager::getTemplate方法，传入样式表的完整键名，格式为 Namespace::StyleSheetName，例如 "General::Default"。请注意，模板ID不影响键名，模板ID只是在程序内部区分不同模板文件而已。

除此之外，当样式组的第一行是以#开头时，表示这一行是注释行，会被忽略掉。

加载与应用

ThemeManager在初始化时会从配置文件中读取上次保存的配色方案、样式模板优先级列表和主题并进行加载。然后在恰当时机根据优先级列表合并所有配色方案和样式模板，生成一个最终的配色方案和样式模板，并应用到应用程序中。

有关ThemeManager默认配置文件的位置，请参考Visindigo::General::VIApplication::EnvKey。

如果各插件需要向程序注册配色方案或样式模板，使用函数ThemeManager::pluginRegisterColorScheme和 ThemeManager::pluginRegisterStyleTemplate即可。注意它不提供卸载方法（是设计缺陷，但暂时不打算更改）。

如果需要在程序运行时重载从文件系统中读取的配色方案和样式模板，可以使用函数loadAndRefresh。它默认在读取后重新合并（即调用mergeAndApply方法）并触发信号programThemeChanged。如果不需要自动合并和应用，可以传入 false参数。

如果插件需要在程序运行时动态更改颜色方案或样式模板，则重新调用对应的注册函数即可，但之后还需要手动调用mergeAndApply方法重新合并和应用主题。

更改颜色主题以及系统颜色感知

如果只是需要更改配色方案，则使用函数changeColorTheme即可。使用changeColorTheme时，如果传入参数是Auto，则自动启用系统主题感知功能。请注意，Auto这个值比较特殊，不在ColorSheme的枚举里，因此你不能通过ThemeID版本的重载函数来使用这个值，必须使用字符串版本的函数，并传入"Auto"。

如果你不信任字面量，也可以通过setAutoAdjustThemeToSystem(true)来启用系统主题感知功能。

此外，由于系统颜色感知依赖QStyleHints的特性，这里有个功能缺陷：systemThemeChanged信号在 autoAdjustThemeToSystem为false时不会触发，因此不可能既手动指定主题，又感知系统变化。除非Qt更改，这问题无法解决。

使用样式模板

要将ThemeManager的结果应用到应用程序中，可以在setStyleSheet时使用ThemeManager::getTemplate方法获取样式表字符串，例如

Label->setStyleSheet(ThemeManager::getInstance()->getTemplate("General::Default", Label));

当然，这太长了，因此我们提供了宏VISTMGT来简化这个过程，使用方法如下：

Label->setStyleSheet(VISTMGT("General::Default", Label));

这里的Label参数是可选的，如果提供了这个参数，ThemeManager会尝试从Label的property属性中获取变量值进行代换。

当然也有更简化的做法，宏applyVIStyleTemplate看上去似乎为QWidget增加了一个成员函数，即：

Label->applyVIStyleTemplate("General::Default");

这个函数等同于调用QWidget::setStyleSheet(VISTMGT(key, this))。

此外，如果你确定一个样式表不需要任何变量代换（包括颜色主题变量和组件property变量），则可以使用 ThemeManager::getRawTemplate方法获取原始样式表字符串，例如

Label->setStyleSheet(ThemeManager::getInstance()->getRawTemplate("General::Default"));
Label->setStyleSheet(VISTMGRT("General::Default"));

使用原始样式表字符串可以略微提升性能，因为省去了变量代换的过程。

配色方案和样式模板优先级

ThemeManager允许用户通过配置配色方案和样式模板的加载优先级来控制最终的主题效果。使用函数 setColorSchemePriority和setStyleTemplatePriority可以设置优先级列表，列表中靠后的主题或模板会覆盖前面的主题或模板的同名属性，并最终生成一个合并后的主题或模板。

工作顺序

ThemeManager的工作顺序如下：

1. 在程序主插件启用前，ThemeManager会被初始化，并加载配置文件中的配色方案和样式模板优先级列表。同时将文件系统中的配色方案和样式模板加载到内存中。
2. 主程序插件应在启用时（onPluginEnable），向ThemeManager注册默认的配色方案和样式模板。
3. 各插件应在构造函数中，向ThemeManager注册自己的配色方案和样式模板。

Warning: 请务必注意主程序插件和插件的注册在时机上的差别，如果插件的注册时间延后到onPluginEnable，会错过合并和应用主题的时机，从而导致主题不完整。
4. 在所有插件启用前，ThemeManager会调用mergeAndApply方法，合并所有注册的配色方案和样式模板，并应用到应用程序中。

ThemeManager在主题变更时的工作顺序如下：

1. 如果启用了自动适应系统主题（通过autoAdjustThemeToSystem方法），则在系统主题变化时准备执行后续步骤。或者用户调用changeColorTheme方法，准备执行后续步骤。
2. 如果未启用渐变动画，则直接触发programThemeChanged信号，结束。如果启用渐变动画，则进入后续步骤。
3. 计算当前主题和目标主题之间的颜色差值，并启动一个定时器以设定的帧率周期性地更新主题颜色。
4. 在动画期间，ThemeManager会周期性地调用所有启用主题变化动画支持的ColorfulWidget组件的onThemeChanged方法，并传入当前动画帧的主题ID（始终为ThemeID::__InAnimation__）。组件应在此方法中重新设置样式表。
5. 动画结束后，触发programThemeChanged信号，表示主题变化完成。

响应主题变化

用户可以自行决定是否相应主题变化，以及主题变化后的处理方式（例如是立即重设样式表，还是要求用户重启程序）。

如果不需要主题变化时的颜色渐变动画效果，可以直接连接programThemeChanged信号，并在槽函数中处理主题变化，这个信号会在主题变化时（如果有动画则会在动画结束后）被触发。

但如果用户希望在切换主题时有颜色渐变动画效果，则需要扩展ColorfulWidget接口，并实现onThemeChanged方法。这个方法会在主题变化时的每一个动画帧调用。动画渐变过程处理是对用户封闭的，这个函数里只需要正常设置样式表即可，由ThemeManager内部变更实际的赋值。

因此需要注意的是，ColorfulWidget的接口在动画期间的调用频率基本等价于设置的动画帧率，因此其中不应该有任何耗时操作，否则会影响动画流畅度。

ColorfulWidget需要通过函数Visindigo::Widgets::ColorfulWidget::setEnable()方法启用主题变化动画支持。未启用支持的ColorfulWidget组件永远不会被调用onThemeChanged方法。

成员类型文档

`[since Visindigo 0.13.0]` enum ThemeManager::ThemeID

Constant	Value	Description
`Visindigo::Widgets::ThemeManager::__InAnimation__`	`-1`	动画过渡中的临时主题ID，用于表示主题正在变化中。（启用动画过渡时使用）。虽然这是个特殊值，但它可以正常和字符串相互转换。用户不应该占用这个名称作为自定义主题ID。
`Visindigo::Widgets::ThemeManager::Unknown`	`0`	未知主题
`Visindigo::Widgets::ThemeManager::Light`	`1`	明亮主题
`Visindigo::Widgets::ThemeManager::Dark`	`2`	黑暗主题
`Visindigo::Widgets::ThemeManager::White`	`3`	白色主题（更浅的明亮主题）
`Visindigo::Widgets::ThemeManager::Black`	`4`	黑色主题（更暗的黑暗主题）
`Visindigo::Widgets::ThemeManager::__UserMin__`	`1000`	用户自定义主题ID的起始值。这个值及其之后的值保留给用户自定义主题ID使用。它不能直接作为主题ID使用。因此不能和字符串相互转换。从枚举转换到字符串以及从字符串转换到枚举都会变成Unknown。 ThemeID枚举定义了ThemeManager支持的预定义主题ID。

用户也可以通过ThemeManager::registerUserThemeID方法注册自定义主题ID。

这个enum 从 Visindigo 0.13.0 开始支持。