Debian Codegraph @

docs/global/ddesktopentry.zh_CN.dox

raw
1 /*!
2 @~chinese
3 @file include/global/ddesktopentry.h
4 @ingroup dglobal
5
6 @class Dtk::Core::DDesktopEntry ddesktopentry.h
7 @brief 处理desktop文件的接口
8 @details
9 ## 概述
10
11 DDesktopEntry提供了处理XDG desktop读写的方法的接口,这个Class类似于QSettings。
12
13 有关该规范本身的更多详细信息,请参阅:
14 https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html
15
16
17 项目目录结构在同一目录下
18
19 ## CMakeLists.txt
20
21 ```cmake
22 cmake_minimum_required(VERSION 3.1.0) # 指定cmake最低版本
23
24 project(example1 VERSION 1.0.0 LANGUAGES CXX) # 指定项目名称, 版本, 语言 cxx就是c++
25
26 set(CMAKE_CXX_STANDARD 11) # 指定c++标准
27 set(CMAKE_CXX_STANDARD_REQUIRED ON) # 指定c++标准要求,至少为11以上
28 set(target example1) # 指定目标名称
29
30 set(CMAKE_AUTOMOC ON) # support qt moc # 支持qt moc
31 set(CMAKE_AUTORCC ON) # support qt resource file # 支持qt资源文件
32 set(CMAKE_AUTOUIC ON) # support qt ui file # 支持qt ui文件(非必须)
33
34 set(CMAKE_EXPORT_COMPILE_COMMANDS ON) # support clangd # 支持 clangd
35
36 if (CMAKE_VERSION VERSION_LESS "3.7.0") # 如果cmake版本小于3.7.0
37 set(CMAKE_INCLUDE_CURRENT_DIR ON) # 设置包含当前目录
38 endif()
39 find_package(Qt5 COMPONENTS Core REQUIRED) # 寻找Qt5组件Core
40 find_package(Dtk COMPONENTS Core REQUIRED) # 寻找Dtk组件Core
41
42 add_executable(${target} # 生成可执行文件
43 main.cpp
44 )
45
46 target_link_libraries(${target} PRIVATE # 添加需要链接的共享库
47 Qt5::Core
48 dtkcore
49 )
50 ```
51
52 ## main.cpp
53
54 ```cpp
55 #include <QDebug>
56 #include <QString>
57 #include <DDesktopEntry>
58 #include <QFile>
59
60 DCORE_USE_NAMESPACE // 使用Dtk Core命名空间
61
62 const QString fileContent = { QStringLiteral(R"desktop(# A. Example Desktop Entry File
63 [Desktop Entry]
64 Version=1.0
65 Type=Application
66 Name=Foo Viewer
67 Name[zh_CN]=福查看器
68 Comment=The best viewer for Foo objects available!
69 # Next line have an extra " character
70 Comment[zh_CN]=最棒的 "福 查看器!
71 TryExec=fooview
72 Exec=fooview %F
73 Icon=fooview
74 MimeType=image/x-foo;
75 Actions=Gallery;Create;
76
77 [Desktop Action Gallery]
78 Exec=fooview --gallery
79 Name=Browse Gallery
80
81 [Desktop Action Create]
82 Exec=fooview --create-new
83 Name=Create a new Foo!
84 Icon=fooview-new
85 )desktop") };
86
87 int main(int argc, char *argv[])
88 {
89 QFile file("example1.desktop");
90 // 尝试打开文件
91 if(!file.open(QIODevice::WriteOnly | QIODevice::Text)){
92 qDebug()<<"文件打开失败";
93 }
94 const QString fileName = file.fileName();
95 QTextStream ts(&file);
96 ts << fileContent;
97 file.close();
98 QFile::exists(fileName);
99
100 // 打开一个fileName为example1.desktop的文件
101 QScopedPointer<DDesktopEntry> desktopFile(new DDesktopEntry(fileName));
102
103 // 获取desktop中所有组并返回列表,对应"Desktop Entry"、"Desktop Action Gallery"、"Desktop Action Create"三组
104 QStringList allGroups = desktopFile->allGroups();
105
106 qDebug() << QString("Desktop 文件共有%1组").arg(allGroups.count());
107
108 // 调用allGroups函数,传入true,保持读取desktop文件时的顺序不变,获取第0组
109 qDebug() << QString("Desktop 文件第0组为: %1").arg(desktopFile->allGroups(true)[0]);
110
111 // 获取key=Name,localeKey=zh_CN的值,即Name[zh_CN]=福查看器
112 qDebug() << QString("Name[zh_CN]=%1") \
113 .arg(desktopFile->localizedValue("Name", "zh_CN"));
114
115 // 获取key为Nam,,localeKey为empty的值,empty表示没有localeKey,即Name=Foo Viewer
116 qDebug() << QString("Name=%1") \
117 .arg(desktopFile->localizedValue("Name", "empty"));
118
119 // 获取Desktop Entry组下的所有key,即"Actions", "Comment", "Comment[zh_CN]", "Exec", "Icon", "MimeType", "Name", "Name[zh_CN]", "TryExec", "Type", "Version"
120 qDebug() << QString("Desktop Entry组下的所有key: ") \
121 << desktopFile->keys("Desktop Entry");
122
123 // 设置 key 为 Name的值为"Bar Viewer",默认组是"Desktop Entry"
124 desktopFile->setRawValue("Bar Viewer", "Name");
125
126 // 设置 key 为 Name,localeKey为zh_CN的值为霸查看器,默认组是"Desktop Entry"
127 desktopFile->setLocalizedValue("霸查看器", "zh_CN", "Name");
128
129 // 检查 section 中是否包 key 为 Semicolon 的值,包含 key 返回true; 否则返回false,默认组是Desktop Entry
130 qDebug() << QString("Desktop Entry组是否包key是Semicolon: ") \
131 << desktopFile->contains("Semicolon", "Desktop Entry");
132
133 // 设置key为Semicolon的值为";grp\\;2;grp3;",默认组是"Desktop Entry"
134 desktopFile->setRawValue(";grp\\;2;grp3;", "Semicolon");
135
136 // 返回给定 section 中与给定 key 关联的字符串的列表。如果destkop不包含为该键的项,则函数返回一个空字符串列表。 默认组是Desktop Entry
137 qDebug() << QString("Desktop Entry组中Semicolon对应值的字符串列表: ") \
138 << desktopFile->stringListValue("Semicolon");
139
140 // 再次检查 section 中是否包 key 为 Semicolon 的值,此时为true
141 qDebug() << QString("Desktop Entry组是否包key是Semicolon: ") \
142 << desktopFile->contains("Semicolon", "Desktop Entry");
143
144 // 删除desktop中 section 中 key 对应的值,默认组是"Desktop Entry"
145 desktopFile->removeEntry("Semicolon", "Desktop Entry");
146
147 // 再次检查 section 中是否包 key 为 Semicolon 的值,此时为false
148 qDebug() << QString("Desktop Entry组是否包key是Semicolon: ") \
149 << desktopFile->contains("Semicolon", "Desktop Entry");
150
151 // 将数据回写到desktop文件。 true表示写成功; 否则返回false
152 if (desktopFile->save())
153 {
154 qDebug() << "文件保存成功";
155 } else {
156 qDebug() << "文件保存失败";
157 }
158
159 return 0;
160 }
161 ```
162
163 结果如下图
164
165 ![example](/docs/src/ddesktopentry_example1.png)
166
167 @enum Dtk::Core::DDesktopEntry::EntryType
168 @brief 桌面入口文件的类型
169 @var Dtk::Core::DDesktopEntry::Unknown
170 @brief 未知的桌面文件类型。可能是无效的
171 @var Dtk::Core::DDesktopEntry::Application
172 @brief 该文件描述应用程序
173 @var Dtk::Core::DDesktopEntry::Link
174 @brief 该文件描述URL
175 @var Dtk::Core::DDesktopEntry::Directory
176 @brief 该文件描述目录设置
177 @var Dtk::Core::DDesktopEntry::ServiceType
178 @brief KDE特定类型。规范中提到过, 所以这里也列出了
179 @var Dtk::Core::DDesktopEntry::Service
180 @brief KDE特定类型。规范中提到过, 所以这里也列出了
181 @var Dtk::Core::DDesktopEntry::FSDevice
182 @brief KDE特定类型。规范中提到过, 所以这里也列出了
183
184 @enum Dtk::Core::DDesktopEntry::ValueType
185 @brief 值的类型
186 @var Dtk::Core::DDesktopEntry::Unparsed
187 @brief 未解析的值
188 @var Dtk::Core::DDesktopEntry::String
189 @brief 字符串
190 @var Dtk::Core::DDesktopEntry::Strings
191 @brief 字符串数组
192 @var Dtk::Core::DDesktopEntry::Boolean
193 @brief 布尔值
194 @var Dtk::Core::DDesktopEntry::Numeric
195 @brief 数字
196 @var Dtk::Core::DDesktopEntry::NotExisted
197 @brief 不存在
198
199 @enum Dtk::Core::DDesktopEntry::Status
200 @brief desktop文件的解析状态
201 @var Dtk::Core::DDesktopEntry::NoError
202 @brief 没有错误发生
203 @var Dtk::Core::DDesktopEntry::AccessError
204 @brief 发生访问错误(例如, 试图写入只读文件)
205 @var Dtk::Core::DDesktopEntry::FormatError
206 @brief 发生格式错误(例如, 加载格式错误的desktop文件)
207
208 @fn Dtk::Core::DDesktopEntry::DDesktopEntry(const QString &filePath) noexcept
209 @brief DDesktopEntry构造函数
210
211 @fn bool Dtk::Core::DDesktopEntry::save() const
212 @brief 将数据回写到desktop文件。
213 @return true表示写成功; 否则返回false
214
215 @fn Status Dtk::Core::DDesktopEntry::status() const
216 @brief Get data parse status
217 @return 返回一个状态码, 表示DDesktopEntry遇到的第一个错误, 如果没有错误发生, 则返回QSettings::NoError。请注意, DDesktopEntry会延迟执行某些操作。
218
219 @fn QStringList Dtk::Core::DDesktopEntry::keys(const QString &section = "Desktop Entry") const
220 @brief 根据 `section` 返回全部键值
221 @return 返回所有的键值
222
223 @fn QStringList Dtk::Core::DDesktopEntry::allGroups(bool sorted = false) const
224 @brief 获取desktop中所有组的列表。如果 `sorted` 设置为true, 则返回结果将保持读取desktop文件时的顺序不变。
225 @return 返回所有的组.
226
227 @fn bool Dtk::Core::DDesktopEntry::contains(const QString &key, const QString &section = "Desktop Entry") const
228 @brief 检查desktop文件是否有给定的 `section` 包含给定的 `key`
229 @return 如果desktop在 `section` 包含 `key` 返回true; 否则返回false。
230
231 @fn QString Dtk::Core::DDesktopEntry::name() const
232 @brief 返回“Desktop Entry”部分下的“Name”键的本地化字符串值。这等价于调用localizedValue("Name")。
233 @return 返回“Desktop Entry”部分下的“Name”键的本地化字符串值。
234 @sa localizedValue(), genericName(), ddeDisplayName()
235
236 @fn QString Dtk::Core::DDesktopEntry::genericName() const
237 @brief 返回"Desktop Entry"部分下的"GenericName"键的本地化字符串值。它等价于调用localizedValue("GenericName")。如果是“GenericName”不存在。则不会回退到“Name”。
238 @return 返回"Desktop Entry"部分下的"GenericName"键的本地化字符串值。
239 @sa localizedValue(), name(), ddeDisplayName()
240
241 @fn QString Dtk::Core::DDesktopEntry::ddeDisplayName() const
242 @brief 为DDE应用程序专门显示名称
243 @details 这将检查“X-Deepin-Vendor”,并将返回本地化的字符串值“GenericName”
244 "X-Deepin-Vendor"是"deepin",否则它将返回"Name"的本地化字符串值。
245 @return 返回专门用于DDE应用程序的显示名称
246 @sa localizedValue(), name(), genericName()
247
248 @fn QString Dtk::Core::DDesktopEntry::comment() const
249 @brief 返回“Desktop Entry”部分下的“Comment”键的本地化字符串值。这等价于调用localizedValue("Comment")。
250 @return 返回“Desktop Entry”部分下的“Comment”键的本地化字符串值。
251 @sa localizedValue()
252
253 @fn QString Dtk::Core::DDesktopEntry::rawValue(const QString &key, const QString &section = "Desktop Entry", const QString &defaultValue = QString()) const
254 @brief 返回 `section` 中与给定 `key` 关联的原始字符串值。如果desktop不包含具有该键的项, 则函数返回一个构造好的 `defaultValue`。
255 @return 返回 `section` 中与给定 `key` 相关联的原始字符串值。
256 @sa stringValue() localizedValue() stringListValue()
257
258 @fn QString Dtk::Core::DDesktopEntry::stringValue(const QString &key, const QString &section = "Desktop Entry", const QString &defaultValue = QString()) const
259 @brief 返回 `section` 与给定 `key` 关联的未转义字符串值。如果desktop不包含键值为0的项, 则函数返回一个构造好的 `defaultValue`。
260 @return 返回 `section` 中与给定 `key` 相关联的未转义字符串值。
261 @sa rawValue() localizedValue() stringListValue()
262
263 @fn QString Dtk::Core::DDesktopEntry::localizedValue(const QString &key, const QString &localeKey = "default", const QString &section = "Desktop Entry", const QString& defaultValue = QString()) const
264 @brief 返回与 `section` 中给定的 `key` 和 `localeKey` 相关联的本地化字符串值。
265 @details
266 如果找不到给定的 `localeKey` ,它将回退到"C",如果仍然找不到,将回退 `key` 没有`localeKey`部分。。
267 如果destkop不包含 `key` 值为0的项,则函数返回一个构造好的 `defaultValue`。
268 @return 返回 `section` 中与给定的 `key` 和 `localeKey` 关联的本地化字符串值。
269 @sa rawValue() stringValue() stringListValue()
270
271 @fn QString Dtk::Core::DDesktopEntry::localizedValue(const QString &key, const QLocale &locale, const QString &section = "Desktop Entry", const QString& defaultValue = QString()) const
272 @brief 返回与给定的 `key` 和 `section` 中的区域设置相关联的本地化字符串值。
273 @details
274 如果找不到给定的 `localeKey` ,它将回退到"C",如果仍然找不到,将回退 `key` 没有`localeKey`部分。
275 如果destkop不包含 `key` 值为0的项,则函数返回一个构造好的 `defaultValue`。
276 @return 返回 `section`中 与给定的 `key` 和 `locale` 设置相关联的本地化字符串值。
277 @sa rawValue() stringValue() stringListValue()
278
279 @fn QStringList Dtk::Core::DDesktopEntry::stringListValue(const QString &key, const QString &section = "Desktop Entry") const
280 @brief 返回给定 `section` 中与给定 `key` 关联的字符串的列表。如果destkop不包含为该键的项,则函数返回一个空字符串列表。
281 @return 返回给定 `section` 中与给定 `key` 关联的字符串的列表。
282 @sa rawValue() stringValue() localizedValue()
283
284 @fn bool Dtk::Core::DDesktopEntry::setRawValue(const QString &value, const QString &key, const QString& section = "Desktop Entry")
285 @brief 设置给定 `section` 中与给定 `key` 关联的原始字符串值。
286
287 @fn bool Dtk::Core::DDesktopEntry::setStringValue(const QString &value, const QString &key, const QString& section = "Desktop Entry")
288 @brief 设置给定 `section` 中与给定 `key` 关联的字符串
289
290 @fn bool Dtk::Core::DDesktopEntry::setLocalizedValue(const QString &value, const QString& localeKey, const QString &key, const QString& section = "Desktop Entry")
291 @brief 设置给定的 `key` 和 `section` 中的区域设置相关联的本地化字符串值。
292
293 @fn bool Dtk::Core::DDesktopEntry::removeEntry(const QString &key, const QString &section = "Desktop Entry");
294 @brief 删除desktop中 `section` 与 `key` 对应的值
295
296 @fn static QString& Dtk::Core::DDesktopEntry::escape(QString &str)
297 @brief 支持转义序列`\s`、`\n`、`\t`、`\r`和`\\`表示值
298 @details string和localestring类型的值支持转义序列`\s`、`\n`、`\t`、`\r`和`\\`,分别表示ASCII空格、换行符、制表符、回车和反斜杠。
299
300 @fn static QString& Dtk::Core::DDesktopEntry::escapeExec(QString &str)
301 @brief 必须将参数括在双引号之间,并对双引号字符进行转义。
302 @details
303 | 原字符 | 转义后 |
304 |------|---------|
305 | \` | "`" |
306 | $ | "$" |
307 | \ | "\" |
308 在它前面加上一个额外的反斜杠字符。实现必须在扩展字段代码之前和之前撤销引用,将参数传递给可执行程序。
309 @note 类型为string的值的通用转义规则规定,反斜杠字符也可以转义为("\\")和这个转义规则应用在引用规则之前。<br>
310 因此,要明确地表示在desktop文件中,引号参数中的文字反斜杠字符 <br>
311 要求使用四个连续的反斜杠字符("\\\\")。同样,在桌面入口文件中引用参数中的美元符号表示为("\\$")。
312
313 @fn static QString& Dtk::Core::DDesktopEntry::unescape(QString &str, bool unescapeSemicolons = false)
314 @brief 对于类型为string和localestring的值,支持转义序列`\s`、`\n`、`\t`、`\r`和`\\`,分别表示ASCII空格、换行符、制表符、回车符和反斜杠。
315 @details 有些键可以有多个值。这种情况下,`key` 的值被指定为复数形式:
316 例如,字符串。多个值应该用分号分隔,`key` 的值可以选择以分号结尾。空字符串必须以分号结尾。
317 这些值中的分号需要使用`\;`转义。
318
319 有关该规范本身的更多详细信息,请参阅:
320 https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#value-types
321
322 @fn static QString& Dtk::Core::DDesktopEntry::unescapeExec(QString &str)
323 @brief 必须将参数括在双引号之间,并对双引号字符进行转义,
324 @details
325 | 原字符 | 转义后 |
326 |------|---------|
327 | \` | "`" |
328 | $ | "$" |
329 | \ | "\" |
330 在它前面加上一个额外的反斜杠字符。实现必须在扩展字段代码之前和之前撤销引用,将参数传递给可执行程序。
331
332 保留字符:
333 | 功能 | 字符 |
334 |---------------------|---------|
335 | space | " " |
336 | tab | |
337 | newline | |
338 | double quote | |
339 | single quote | "'" |
340 | backslash character | "\" |
341 | greater-than sign | ">" |
342 | less-than sign | "<" |
343 | tilde | "~" |
344 | vertical bar | \| |
345 | ampersand | "&" |
346 | semicolon | ";" |
347 | dollar sign | "$" |
348 | asterisk | "*" |
349 | question mark | "?" |
350 | hash mark | "#" |
351 | parenthesis | "(" 和 ")" |
352 | backtick character | "`" |
353 @note 类型为string的值的通用转义规则规定 <br>
354 反斜杠字符也可以转义为("\\"),而且转义规则在引号规则之前应用。<br>
355 因此,要在desktop文件的引号参数中明确表示字面上的反斜杠字符,需要使用四个连续的反斜杠字符(“\\\\”)。<br>
356 同样,在desktop文件中,引号参数中的美元符号可以明确地表示为("\\$")。
357
358 @fn bool Dtk::Core::DDesktopEntry::setStatus(const Status &status)
359 @brief 设置desktop文件解析状态
360
361 */