/*! @~chinese @file include/util/dicontheme.h @ingroup dci @brief Dtk 图标主题工具类 @namespace Dtk::Gui::DIconTheme dicontheme.h @details 用于提供一些接口,包括查找图标(包括 QIcon 和 DCI 图标 ),图标搜索路径等。 @enum Dtk::Gui::DIconTheme::Option @brief 查找图标时的选项 @var Dtk::Gui::DIconTheme::DontFallbackToQIconFromTheme @brief 是否**不使用** QIcon::fromTheme 的方式去查找图标,当设置此 flag 时查找图标失败时直接返回空图标对象,否则回退到通过 QIcon::fromTheme 查找图标 @var Dtk::Gui::DIconTheme::IgnoreBuiltinIcons @brief 是否忽略通过内置图标引擎方式查找图标资源,当设置此 flag 时查找图标会跳过内置图标引擎的方式查找图标资源,否则优先尝试内置图标引擎查找资源。 @class Dtk::Gui::DIconTheme::Cached @details 图标查找缓存类,提供的查找图标接口,如果找到会加入缓存,下次查找会更快。 @fn Dtk::Gui::DIconTheme::Cached::Cached() @details 图标缓存构造函数 @fn Dtk::Gui::DIconTheme::Cached::~Cached() @details 图标缓存析构函数 @fn Dtk::Gui::DIconTheme::Cached::maxCost() const @details 返回允许的最大缓存数量 @fn Dtk::Gui::DIconTheme::Cached::setMaxCost(int cost) @details 将最大允许的缓存数量设置为 cost 。如果当前的缓存数量大于 cost ,则某些缓存对象会立即删除。 @fn Dtk::Gui::DIconTheme::Cached::clear() @details 清理所有缓存 @fn Dtk::Gui::DIconTheme::Cached::findQIcon(const QString &iconName, Options options, const QIcon &fallback) @details 通过 iconName 查找 QIcon 的接口,找到时会加入缓存 @param[in] iconName 要查找的图标名称 @param[in] options 要查找的选项 @param[in] fallback 图标查找失败时可以返回用户指定的 fallback 对象,默认为空 @sa DIconTheme::findQIcon @fn Dtk::Gui::DIconTheme::Cached::findDciIconFile(const QString &iconName, const QString &themeName, const QString &fallback) @details 通过指定图标名 iconName 和主题名 themeName 查找 DCI 图标文件路径的接口,找到时会加入缓存 @param[in] iconName 要查找的图标名称 @param[in] options 指定 DCI 图标主题 @param[in] fallback 图标查找失败时可以返回用户指定的 fallback ,默认为空 @fn Dtk::Gui::DIconTheme::cached() @details 获取(首次次调用时构造)缓存对象。 @fn Dtk::Gui::DIconTheme::findQIcon(const QString &iconName, Options options) @details 返回 DIconTheme::createIconEngine 接口创建的图标引擎构造 QIcon,当没有设置 DontFallbackToQIconFromTheme 和 createIconEngine 失败时回退到 QIcon::fromTheme @param[in] iconName 要查找的图标名称 @param[in] options 要查找的选项, 选项默认为空 @sa DIconTheme::Cached::findQIcon @sa DIconTheme::createIconEngine @fn Dtk::Gui::DIconTheme::findQIcon(const QString &iconName, const QIcon &fallback, Options options) @details 重载 DIconTheme::findQIcon, 当查找图标失败时返回调用者中提供的 fallback 图标 @param[in] iconName 要查找的图标名称 @param[in] options 要查找的选项, 选项默认为空 @param[in] fallback 如果 iconName 无法找到, 返回此图标 @sa DIconTheme::Cached::findQIcon @sa DIconTheme::createIconEngine @fn Dtk::Gui::DIconTheme::createIconEngine(const QString &iconName, Options options) @details 通过图标名构造图标引擎, 如果未设置 IgnoreBuiltinIcons 标志则优先尝试 qrc:/icons/deepin/builtin 目录查找图标来构造内置图标引擎,否则构造 XDG 图标引擎。 @param[in] iconName 图标名称 @param[in] options 选项, 选项默认为 DIconTheme::DontFallbackToQIconFromTheme @return QIconEngine 对象指针,注意图标查找失败时返回 nullptr。 @fn Dtk::Gui::DIconTheme::findDciIconFile(const QString &iconName, const QString &themeName) @details 通过指定图标名 iconName 和主题名 themeName 查找 DCI 图标文件路径的接口 @param[in] iconName 要查找的图标名称 @param[in] options 指定 DCI 图标主题 @return 返回找到的 DCI 图标文件路径 @sa DDciIcon::fromTheme @sa DIconTheme::dciThemeSearchPaths() @fn Dtk::Gui::DIconTheme::dciThemeSearchPaths() @details 返回 DCI 图标的搜索路径。默认会从这些路径查找 /usr/share/dsg/icons/$theme_name, qrc:/dsg/icons/$theme_name, qrc:/dsg/built-in-icons @sa DIconTheme::findDciIconFile @fn Dtk::Gui::DIconTheme::setDciThemeSearchPaths(const QStringList &path) @details 设置查找 DCI 图标的搜索路径 @sa DIconTheme::dciThemeSearchPaths @fn Dtk::Gui::DIconTheme::isBuiltinIcon(const QIcon &icon) @details 返回 QIcon 是否为内置图标,`内置图标` 是 DTK 中规定的一类集成在二进制内部的图标资源,其一般放置于 qrc:/icons/deepin/builtin 的路径下,在使用 findQIcon 或 createIconEngine 时,如找到此路径下对应的图标文件,则会为其使用一个自定义的 QIconEngine 进行渲染。此方法即通过判断 icon 所使用的 QIconEngine 确认其是否为内置图标。 @fn Dtk::Gui::DIconTheme::isXdgIcon(const QIcon &icon) @details 返回 QIcon 是否为 XDG 图标, XDG 图标一般放置于系统图标主题目录(如:/usr/share/icons)。和 isBuiltinIcon 类似,此方法是通过判断 icon 所使用的 QIconEngine 确认其是否为 XDG 图标。 */