DtkCore
DTK Core module
载入中...
搜索中...
未找到
Dtk::Core::DDesktopEntry类 参考

处理desktop文件的接口 更多...

#include <ddesktopentry.h>

Public 类型

enum  EntryType {
  Unknown = 0 , Application , Link , Directory ,
  ServiceType , Service , FSDevice
}
 桌面入口文件的类型 更多...
 
enum  ValueType {
  Unparsed = 0 , String , Strings , Boolean ,
  Numeric , NotExisted = 99
}
 值的类型 更多...
 
enum  Status { NoError = 0 , AccessError , FormatError }
 desktop文件的解析状态 更多...
 

Public 成员函数

 DDesktopEntry (const QString &filePath) noexcept
 DDesktopEntry构造函数
 
bool save () const
 将数据回写到desktop文件。
 
Status status () const
 Get data parse status
 
QStringList keys (const QString &section="Desktop Entry") const
 根据 section 返回全部键值
 
QStringList allGroups (bool sorted=false) const
 获取desktop中所有组的列表。如果 sorted 设置为true, 则返回结果将保持读取desktop文件时的顺序不变。
 
bool contains (const QString &key, const QString &section="Desktop Entry") const
 检查desktop文件是否有给定的 section 包含给定的 key
 
QString name () const
 返回“Desktop Entry”部分下的“Name”键的本地化字符串值。这等价于调用localizedValue("Name")。
 
QString genericName () const
 返回"Desktop Entry"部分下的"GenericName"键的本地化字符串值。它等价于调用localizedValue("GenericName")。如果是“GenericName”不存在。则不会回退到“Name”。
 
QString ddeDisplayName () const
 为DDE应用程序专门显示名称
 
QString comment () const
 返回“Desktop Entry”部分下的“Comment”键的本地化字符串值。这等价于调用localizedValue("Comment")。
 
QString rawValue (const QString &key, const QString &section="Desktop Entry", const QString &defaultValue=QString()) const
 返回 section 中与给定 key 关联的原始字符串值。如果desktop不包含具有该键的项, 则函数返回一个构造好的 defaultValue
 
QString stringValue (const QString &key, const QString &section="Desktop Entry", const QString &defaultValue=QString()) const
 返回 section 与给定 key 关联的未转义字符串值。如果desktop不包含键值为0的项, 则函数返回一个构造好的 defaultValue
 
QString localizedValue (const QString &key, const QString &localeKey="default", const QString &section="Desktop Entry", const QString &defaultValue=QString()) const
 返回与 section 中给定的 keylocaleKey 相关联的本地化字符串值。
 
QString localizedValue (const QString &key, const QLocale &locale, const QString &section="Desktop Entry", const QString &defaultValue=QString()) const
 返回与给定的 keysection 中的区域设置相关联的本地化字符串值。
 
QStringList stringListValue (const QString &key, const QString &section="Desktop Entry") const
 返回给定 section 中与给定 key 关联的字符串的列表。如果destkop不包含为该键的项,则函数返回一个空字符串列表。
 
bool setRawValue (const QString &value, const QString &key, const QString &section="Desktop Entry")
 设置给定 section 中与给定 key 关联的原始字符串值。
 
bool setStringValue (const QString &value, const QString &key, const QString &section="Desktop Entry")
 设置给定 section 中与给定 key 关联的字符串
 
bool setLocalizedValue (const QString &value, const QString &localeKey, const QString &key, const QString &section="Desktop Entry")
 设置给定的 keysection 中的区域设置相关联的本地化字符串值。
 
bool removeEntry (const QString &key, const QString &section="Desktop Entry")
 删除desktop中 sectionkey 对应的值
 

静态 Public 成员函数

static QString & escape (QString &str)
 支持转义序列\s\n\t\r\\表示值
 
static QString & escapeExec (QString &str)
 必须将参数括在双引号之间,并对双引号字符进行转义。
 
static QString & unescape (QString &str, bool unescapeSemicolons=false)
 对于类型为string和localestring的值,支持转义序列\s\n\t\r\\,分别表示ASCII空格、换行符、制表符、回车符和反斜杠。
 
static QString & unescapeExec (QString &str)
 必须将参数括在双引号之间,并对双引号字符进行转义,
 

Protected 成员函数

bool setStatus (const Status &status)
 设置desktop文件解析状态
 

详细描述

处理desktop文件的接口

概述

DDesktopEntry提供了处理XDG desktop读写的方法的接口,这个Class类似于QSettings。

有关该规范本身的更多详细信息,请参阅: https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html

项目目录结构在同一目录下

CMakeLists.txt

cmake_minimum_required(VERSION 3.1.0) # 指定cmake最低版本
project(example1 VERSION 1.0.0 LANGUAGES CXX) # 指定项目名称, 版本, 语言 cxx就是c++
set(CMAKE_CXX_STANDARD 11) # 指定c++标准
set(CMAKE_CXX_STANDARD_REQUIRED ON) # 指定c++标准要求,至少为11以上
set(target example1) # 指定目标名称
set(CMAKE_AUTOMOC ON) # support qt moc # 支持qt moc
set(CMAKE_AUTORCC ON) # support qt resource file # 支持qt资源文件
set(CMAKE_AUTOUIC ON) # support qt ui file # 支持qt ui文件(非必须)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON) # support clangd # 支持 clangd
if (CMAKE_VERSION VERSION_LESS "3.7.0") # 如果cmake版本小于3.7.0
set(CMAKE_INCLUDE_CURRENT_DIR ON) # 设置包含当前目录
endif()
find_package(Qt5 COMPONENTS Core REQUIRED) # 寻找Qt5组件Core
find_package(Dtk COMPONENTS Core REQUIRED) # 寻找Dtk组件Core
add_executable(${target} # 生成可执行文件
main.cpp
)
target_link_libraries(${target} PRIVATE # 添加需要链接的共享库
Qt5::Core
dtkcore
)

main.cpp

#include <QDebug>
#include <QString>
#include <DDesktopEntry>
#include <QFile>
DCORE_USE_NAMESPACE // 使用Dtk Core命名空间
const QString fileContent = { QStringLiteral(R"desktop(# A. Example Desktop Entry File
[Desktop Entry]
Version=1.0
Type=Application
Name=Foo Viewer
Name[zh_CN]=福查看器
Comment=The best viewer for Foo objects available!
# Next line have an extra " character
Comment[zh_CN]=最棒的 "福 查看器!
TryExec=fooview
Exec=fooview %F
Icon=fooview
MimeType=image/x-foo;
Actions=Gallery;Create;
[Desktop Action Gallery]
Exec=fooview --gallery
Name=Browse Gallery
[Desktop Action Create]
Exec=fooview --create-new
Name=Create a new Foo!
Icon=fooview-new
)desktop") };
int main(int argc, char *argv[])
{
QFile file("example1.desktop");
// 尝试打开文件
if(!file.open(QIODevice::WriteOnly | QIODevice::Text)){
qDebug()<<"文件打开失败";
}
const QString fileName = file.fileName();
QTextStream ts(&file);
ts << fileContent;
file.close();
QFile::exists(fileName);
// 打开一个fileName为example1.desktop的文件
QScopedPointer<DDesktopEntry> desktopFile(new DDesktopEntry(fileName));
// 获取desktop中所有组并返回列表,对应"Desktop Entry"、"Desktop Action Gallery"、"Desktop Action Create"三组
QStringList allGroups = desktopFile->allGroups();
qDebug() << QString("Desktop 文件共有%1组").arg(allGroups.count());
// 调用allGroups函数,传入true,保持读取desktop文件时的顺序不变,获取第0组
qDebug() << QString("Desktop 文件第0组为: %1").arg(desktopFile->allGroups(true)[0]);
// 获取key=Name,localeKey=zh_CN的值,即Name[zh_CN]=福查看器
qDebug() << QString("Name[zh_CN]=%1") \
.arg(desktopFile->localizedValue("Name", "zh_CN"));
// 获取key为Nam,,localeKey为empty的值,empty表示没有localeKey,即Name=Foo Viewer
qDebug() << QString("Name=%1") \
.arg(desktopFile->localizedValue("Name", "empty"));
// 获取Desktop Entry组下的所有key,即"Actions", "Comment", "Comment[zh_CN]", "Exec", "Icon", "MimeType", "Name", "Name[zh_CN]", "TryExec", "Type", "Version"
qDebug() << QString("Desktop Entry组下的所有key: ") \
<< desktopFile->keys("Desktop Entry");
// 设置 key 为 Name的值为"Bar Viewer",默认组是"Desktop Entry"
desktopFile->setRawValue("Bar Viewer", "Name");
// 设置 key 为 Name,localeKey为zh_CN的值为霸查看器,默认组是"Desktop Entry"
desktopFile->setLocalizedValue("霸查看器", "zh_CN", "Name");
// 检查 section 中是否包 key 为 Semicolon 的值,包含 key 返回true; 否则返回false,默认组是Desktop Entry
qDebug() << QString("Desktop Entry组是否包key是Semicolon: ") \
<< desktopFile->contains("Semicolon", "Desktop Entry");
// 设置key为Semicolon的值为";grp\\;2;grp3;",默认组是"Desktop Entry"
desktopFile->setRawValue(";grp\\;2;grp3;", "Semicolon");
// 返回给定 section 中与给定 key 关联的字符串的列表。如果destkop不包含为该键的项,则函数返回一个空字符串列表。 默认组是Desktop Entry
qDebug() << QString("Desktop Entry组中Semicolon对应值的字符串列表: ") \
<< desktopFile->stringListValue("Semicolon");
// 再次检查 section 中是否包 key 为 Semicolon 的值,此时为true
qDebug() << QString("Desktop Entry组是否包key是Semicolon: ") \
<< desktopFile->contains("Semicolon", "Desktop Entry");
// 删除desktop中 section 中 key 对应的值,默认组是"Desktop Entry"
desktopFile->removeEntry("Semicolon", "Desktop Entry");
// 再次检查 section 中是否包 key 为 Semicolon 的值,此时为false
qDebug() << QString("Desktop Entry组是否包key是Semicolon: ") \
<< desktopFile->contains("Semicolon", "Desktop Entry");
// 将数据回写到desktop文件。 true表示写成功; 否则返回false
if (desktopFile->save())
{
qDebug() << "文件保存成功";
} else {
qDebug() << "文件保存失败";
}
return 0;
}
QStringList allGroups(bool sorted=false) const
获取desktop中所有组的列表。如果 sorted 设置为true, 则返回结果将保持读取desktop文件时的顺序不变。

结果如下图

example

成员枚举类型说明

◆ EntryType

桌面入口文件的类型

枚举值
Unknown 

未知的桌面文件类型。可能是无效的

Application 

该文件描述应用程序

Link 

该文件描述URL

Directory 

该文件描述目录设置

ServiceType 

KDE特定类型。规范中提到过, 所以这里也列出了

Service 

KDE特定类型。规范中提到过, 所以这里也列出了

FSDevice 

KDE特定类型。规范中提到过, 所以这里也列出了

◆ Status

desktop文件的解析状态

枚举值
NoError 

没有错误发生

AccessError 

发生访问错误(例如, 试图写入只读文件)

FormatError 

发生格式错误(例如, 加载格式错误的desktop文件)

◆ ValueType

值的类型

枚举值
Unparsed 

未解析的值

String 

字符串

Strings 

字符串数组

Boolean 

布尔值

Numeric 

数字

NotExisted 

不存在

成员函数说明

◆ allGroups()

QStringList Dtk::Core::DDesktopEntry::allGroups ( bool  sorted = false) const

获取desktop中所有组的列表。如果 sorted 设置为true, 则返回结果将保持读取desktop文件时的顺序不变。

返回
返回所有的组.

◆ comment()

QString Dtk::Core::DDesktopEntry::comment ( ) const

返回“Desktop Entry”部分下的“Comment”键的本地化字符串值。这等价于调用localizedValue("Comment")。

返回
返回“Desktop Entry”部分下的“Comment”键的本地化字符串值。
参见
localizedValue()

◆ contains()

bool Dtk::Core::DDesktopEntry::contains ( const QString &  key,
const QString &  section = "Desktop Entry" 
) const

检查desktop文件是否有给定的 section 包含给定的 key

返回
如果desktop在 section 包含 key 返回true; 否则返回false。

◆ ddeDisplayName()

QString Dtk::Core::DDesktopEntry::ddeDisplayName ( ) const

为DDE应用程序专门显示名称

这将检查“X-Deepin-Vendor”,并将返回本地化的字符串值“GenericName” "X-Deepin-Vendor"是"deepin",否则它将返回"Name"的本地化字符串值。

返回
返回专门用于DDE应用程序的显示名称
参见
localizedValue(), name(), genericName()

◆ escape()

static QString & Dtk::Core::DDesktopEntry::escape ( QString &  str)
static

支持转义序列\s\n\t\r\\表示值

string和localestring类型的值支持转义序列\s\n\t\r\\,分别表示ASCII空格、换行符、制表符、回车和反斜杠。

◆ escapeExec()

static QString & Dtk::Core::DDesktopEntry::escapeExec ( QString &  str)
static

必须将参数括在双引号之间,并对双引号字符进行转义。

原字符 转义后
` "`"
$ "$"
\ "\"

在它前面加上一个额外的反斜杠字符。实现必须在扩展字段代码之前和之前撤销引用,将参数传递给可执行程序。

注解
类型为string的值的通用转义规则规定,反斜杠字符也可以转义为("\\")和这个转义规则应用在引用规则之前。<br> 因此,要明确地表示在desktop文件中,引号参数中的文字反斜杠字符 <br> 要求使用四个连续的反斜杠字符("\\")。同样,在桌面入口文件中引用参数中的美元符号表示为("\$")。

◆ genericName()

QString Dtk::Core::DDesktopEntry::genericName ( ) const

返回"Desktop Entry"部分下的"GenericName"键的本地化字符串值。它等价于调用localizedValue("GenericName")。如果是“GenericName”不存在。则不会回退到“Name”。

返回
返回"Desktop Entry"部分下的"GenericName"键的本地化字符串值。
参见
localizedValue(), name(), ddeDisplayName()

◆ keys()

QStringList Dtk::Core::DDesktopEntry::keys ( const QString &  section = "Desktop Entry") const

根据 section 返回全部键值

返回
返回所有的键值

◆ localizedValue() [1/2]

QString Dtk::Core::DDesktopEntry::localizedValue ( const QString &  key,
const QLocale &  locale,
const QString &  section = "Desktop Entry",
const QString &  defaultValue = QString() 
) const

返回与给定的 keysection 中的区域设置相关联的本地化字符串值。

如果找不到给定的 localeKey ,它将回退到"C",如果仍然找不到,将回退 key 没有localeKey部分。 如果destkop不包含 key 值为0的项,则函数返回一个构造好的 defaultValue

返回
返回 section中 与给定的 keylocale 设置相关联的本地化字符串值。
参见
rawValue() stringValue() stringListValue()

◆ localizedValue() [2/2]

QString Dtk::Core::DDesktopEntry::localizedValue ( const QString &  key,
const QString &  localeKey = "default",
const QString &  section = "Desktop Entry",
const QString &  defaultValue = QString() 
) const

返回与 section 中给定的 keylocaleKey 相关联的本地化字符串值。

如果找不到给定的 localeKey ,它将回退到"C",如果仍然找不到,将回退 key 没有localeKey部分。。 如果destkop不包含 key 值为0的项,则函数返回一个构造好的 defaultValue

返回
返回 section 中与给定的 keylocaleKey 关联的本地化字符串值。
参见
rawValue() stringValue() stringListValue()

◆ name()

QString Dtk::Core::DDesktopEntry::name ( ) const

返回“Desktop Entry”部分下的“Name”键的本地化字符串值。这等价于调用localizedValue("Name")。

返回
返回“Desktop Entry”部分下的“Name”键的本地化字符串值。
参见
localizedValue(), genericName(), ddeDisplayName()

◆ rawValue()

QString Dtk::Core::DDesktopEntry::rawValue ( const QString &  key,
const QString &  section = "Desktop Entry",
const QString &  defaultValue = QString() 
) const

返回 section 中与给定 key 关联的原始字符串值。如果desktop不包含具有该键的项, 则函数返回一个构造好的 defaultValue

返回
返回 section 中与给定 key 相关联的原始字符串值。
参见
stringValue() localizedValue() stringListValue()

◆ save()

bool Dtk::Core::DDesktopEntry::save ( ) const

将数据回写到desktop文件。

返回
true表示写成功; 否则返回false

◆ status()

Status Dtk::Core::DDesktopEntry::status ( ) const

Get data parse status

返回
返回一个状态码, 表示DDesktopEntry遇到的第一个错误, 如果没有错误发生, 则返回QSettings::NoError。请注意, DDesktopEntry会延迟执行某些操作。

◆ stringListValue()

QStringList Dtk::Core::DDesktopEntry::stringListValue ( const QString &  key,
const QString &  section = "Desktop Entry" 
) const

返回给定 section 中与给定 key 关联的字符串的列表。如果destkop不包含为该键的项,则函数返回一个空字符串列表。

返回
返回给定 section 中与给定 key 关联的字符串的列表。
参见
rawValue() stringValue() localizedValue()

◆ stringValue()

QString Dtk::Core::DDesktopEntry::stringValue ( const QString &  key,
const QString &  section = "Desktop Entry",
const QString &  defaultValue = QString() 
) const

返回 section 与给定 key 关联的未转义字符串值。如果desktop不包含键值为0的项, 则函数返回一个构造好的 defaultValue

返回
返回 section 中与给定 key 相关联的未转义字符串值。
参见
rawValue() localizedValue() stringListValue()

◆ unescape()

static QString & Dtk::Core::DDesktopEntry::unescape ( QString &  str,
bool  unescapeSemicolons = false 
)
static

对于类型为string和localestring的值,支持转义序列\s\n\t\r\\,分别表示ASCII空格、换行符、制表符、回车符和反斜杠。

有些键可以有多个值。这种情况下,key 的值被指定为复数形式: 例如,字符串。多个值应该用分号分隔,key 的值可以选择以分号结尾。空字符串必须以分号结尾。 这些值中的分号需要使用\;转义。

有关该规范本身的更多详细信息,请参阅: https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#value-types

◆ unescapeExec()

static QString & Dtk::Core::DDesktopEntry::unescapeExec ( QString &  str)
static

必须将参数括在双引号之间,并对双引号字符进行转义,

原字符 转义后
` "`"
$ "$"
\ "\"

在它前面加上一个额外的反斜杠字符。实现必须在扩展字段代码之前和之前撤销引用,将参数传递给可执行程序。

保留字符:

功能 字符
space " "
tab
newline
double quote
single quote "'"
backslash character "\"
greater-than sign ">"
less-than sign "<"
tilde "~"
vertical bar |
ampersand "&"
semicolon ";"
dollar sign "$"
asterisk "*"
question mark "?"
hash mark "#"
parenthesis "(" 和 ")"
backtick character "`"
注解
类型为string的值的通用转义规则规定
反斜杠字符也可以转义为("\\"),而且转义规则在引号规则之前应用。<br> 因此,要在desktop文件的引号参数中明确表示字面上的反斜杠字符,需要使用四个连续的反斜杠字符(“\\\\”)。<br> 同样,在desktop文件中,引号参数中的美元符号可以明确地表示为("\$")。

该类的文档由以下文件生成: