Debian Codegraph @

docs/util/dicontheme.zh_CN.dox

raw
1 /*!
2 @~chinese
3 @file include/util/dicontheme.h
4 @ingroup dci
5 @brief Dtk 图标主题工具类
6
7 @namespace Dtk::Gui::DIconTheme dicontheme.h
8 @details 用于提供一些接口,包括查找图标(包括 QIcon 和 DCI 图标 ),图标搜索路径等。
9
10 @enum Dtk::Gui::DIconTheme::Option
11 @brief 查找图标时的选项
12 @var Dtk::Gui::DIconTheme::DontFallbackToQIconFromTheme
13 @brief 是否**不使用** QIcon::fromTheme 的方式去查找图标,当设置此 flag 时查找图标失败时直接返回空图标对象,否则回退到通过 QIcon::fromTheme 查找图标
14 @var Dtk::Gui::DIconTheme::IgnoreBuiltinIcons
15 @brief 是否忽略通过内置图标引擎方式查找图标资源,当设置此 flag 时查找图标会跳过内置图标引擎的方式查找图标资源,否则优先尝试内置图标引擎查找资源。
16
17 @class Dtk::Gui::DIconTheme::Cached
18 @details 图标查找缓存类,提供的查找图标接口,如果找到会加入缓存,下次查找会更快。
19
20 @fn Dtk::Gui::DIconTheme::Cached::Cached()
21 @details 图标缓存构造函数
22
23 @fn Dtk::Gui::DIconTheme::Cached::~Cached()
24 @details 图标缓存析构函数
25
26 @fn Dtk::Gui::DIconTheme::Cached::maxCost() const
27 @details 返回允许的最大缓存数量
28
29 @fn Dtk::Gui::DIconTheme::Cached::setMaxCost(int cost)
30 @details 将最大允许的缓存数量设置为 cost 。如果当前的缓存数量大于 cost ,则某些缓存对象会立即删除。
31
32 @fn Dtk::Gui::DIconTheme::Cached::clear()
33 @details 清理所有缓存
34
35 @fn Dtk::Gui::DIconTheme::Cached::findQIcon(const QString &iconName, Options options, const QIcon &fallback)
36 @details 通过 iconName 查找 QIcon 的接口,找到时会加入缓存
37 @param[in] iconName 要查找的图标名称
38 @param[in] options 要查找的选项
39 @param[in] fallback 图标查找失败时可以返回用户指定的 fallback 对象,默认为空
40 @sa DIconTheme::findQIcon
41
42 @fn Dtk::Gui::DIconTheme::Cached::findDciIconFile(const QString &iconName, const QString &themeName, const QString &fallback)
43 @details 通过指定图标名 iconName 和主题名 themeName 查找 DCI 图标文件路径的接口,找到时会加入缓存
44 @param[in] iconName 要查找的图标名称
45 @param[in] options 指定 DCI 图标主题
46 @param[in] fallback 图标查找失败时可以返回用户指定的 fallback ,默认为空
47
48 @fn Dtk::Gui::DIconTheme::cached()
49 @details 获取(首次次调用时构造)缓存对象。
50
51 @fn Dtk::Gui::DIconTheme::findQIcon(const QString &iconName, Options options)
52 @details 返回 DIconTheme::createIconEngine 接口创建的图标引擎构造 QIcon,当没有设置 DontFallbackToQIconFromTheme 和 createIconEngine 失败时回退到 QIcon::fromTheme
53 @param[in] iconName 要查找的图标名称
54 @param[in] options 要查找的选项, 选项默认为空
55 @sa DIconTheme::Cached::findQIcon
56 @sa DIconTheme::createIconEngine
57
58 @fn Dtk::Gui::DIconTheme::findQIcon(const QString &iconName, const QIcon &fallback, Options options)
59 @details 重载 DIconTheme::findQIcon, 当查找图标失败时返回调用者中提供的 fallback 图标
60 @param[in] iconName 要查找的图标名称
61 @param[in] options 要查找的选项, 选项默认为空
62 @param[in] fallback 如果 iconName 无法找到, 返回此图标
63 @sa DIconTheme::Cached::findQIcon
64 @sa DIconTheme::createIconEngine
65
66 @fn Dtk::Gui::DIconTheme::createIconEngine(const QString &iconName, Options options)
67 @details 通过图标名构造图标引擎, 如果未设置 IgnoreBuiltinIcons 标志则优先尝试 qrc:/icons/deepin/builtin 目录查找图标来构造内置图标引擎,否则构造 XDG 图标引擎。
68 @param[in] iconName 图标名称
69 @param[in] options 选项, 选项默认为 DIconTheme::DontFallbackToQIconFromTheme
70 @return QIconEngine 对象指针,注意图标查找失败时返回 nullptr。
71
72 @fn Dtk::Gui::DIconTheme::findDciIconFile(const QString &iconName, const QString &themeName)
73 @details 通过指定图标名 iconName 和主题名 themeName 查找 DCI 图标文件路径的接口
74 @param[in] iconName 要查找的图标名称
75 @param[in] options 指定 DCI 图标主题
76 @return 返回找到的 DCI 图标文件路径
77 @sa DDciIcon::fromTheme
78 @sa DIconTheme::dciThemeSearchPaths()
79
80 @fn Dtk::Gui::DIconTheme::dciThemeSearchPaths()
81 @details 返回 DCI 图标的搜索路径。默认会从这些路径查找 /usr/share/dsg/icons/$theme_name, qrc:/dsg/icons/$theme_name, qrc:/dsg/built-in-icons
82 @sa DIconTheme::findDciIconFile
83
84 @fn Dtk::Gui::DIconTheme::setDciThemeSearchPaths(const QStringList &path)
85 @details 设置查找 DCI 图标的搜索路径
86 @sa DIconTheme::dciThemeSearchPaths
87
88 @fn Dtk::Gui::DIconTheme::isBuiltinIcon(const QIcon &icon)
89 @details 返回 QIcon 是否为内置图标,`内置图标` 是 DTK 中规定的一类集成在二进制内部的图标资源,其一般放置于 qrc:/icons/deepin/builtin 的路径下,在使用 findQIcon 或 createIconEngine 时,如找到此路径下对应的图标文件,则会为其使用一个自定义的 QIconEngine 进行渲染。此方法即通过判断 icon 所使用的 QIconEngine 确认其是否为内置图标。
90
91 @fn Dtk::Gui::DIconTheme::isXdgIcon(const QIcon &icon)
92 @details 返回 QIcon 是否为 XDG 图标, XDG 图标一般放置于系统图标主题目录(如:/usr/share/icons)。和 isBuiltinIcon 类似,此方法是通过判断 icon 所使用的 QIconEngine 确认其是否为 XDG 图标。
93
94 */