Debian Codegraph @

docs/global/dconfig.zh_CN.dox

raw
1 /*!
2 @~chinese
3 @file include/global/dconfig.h
4 @ingroup dglobal
5 @class Dtk::Core::DConfigBackend dconfig.h
6 @brief 配置后端的抽象接口。
7 @details 所有DConfig使用的配置后端都继承此类,用户可以继承此类实现自己的配置后端。
8
9 @sa FileBackend
10 @sa DBusBackend
11 @sa QSettingBackend
12
13 @fn Dtk::Core::DConfigBackend::~DConfigBackend()
14 @brief DConfigBackend析构函数
15 @sa FileBackend::~FileBackend()
16 @sa DBusBackend::~DBusBackend()
17 @sa QSettingBackend::~QSettingBackend()
18
19 @fn bool Dtk::Core::DConfigBackend::isValid() const = 0
20 @brief 判断此后端是否可用
21 @sa DConfig::isValid()
22 @sa FileBackend::isValid()
23 @sa DBusBackend::isValid()
24 @sa QSettingBackend::isValid()
25
26 @fn bool Dtk::Core::DConfigBackend::load(const QString &) = 0
27 @brief 初始化后端
28 @details appId 管理的配置信息key值,默认为应用程序名称。
29 @sa FileBackend::load()
30 @sa DBusBackend::load()
31 @sa QSettingBackend::load()
32
33 @fn QStringList Dtk::Core::DConfigBackend::keyList() = 0
34 @brief 获得所有可用的配置项名称
35 @sa DConfig::keyList()
36 @sa FileBackend::keyList()
37 @sa DBusBackend::keyList()
38 @sa QSettingBackend::keyList()
39
40 @fn QVariant Dtk::Core::DConfigBackend::value(const QString &key, const QVariant &fallback = QVariant()) const = 0
41 @brief 根据配置项名称获得对应值
42 @param[in] key 配置项名称
43 @param[in] fallback 没有获取到配置项值后提供的默认值
44 @sa DConfig::value()
45 @sa FileBackend::value()
46 @sa DBusBackend::value()
47 @sa QSettingBackend::value()
48
49 @fn void Dtk::Core::DConfigBackend::setValue(const QString &key, const QVariant &value) = 0
50 @brief 根据配置项名称设置其值
51 @param[in] key 配置项名称
52 @param[in] value 需要更新的值
53 @sa DConfig::setValue()
54 @sa FileBackend::setValue()
55 @sa DBusBackend::setValue()
56 @sa QSettingBackend::setValue()
57
58 @fn void Dtk::Core::DConfigBackend::reset(const QString &key)
59 @brief 设置其配置项对应的默认值,此值为经过override机制覆盖后的值,不一定为此配置文件中meta中定义的值。
60 @param[in] key 配置项名称
61 @sa DConfig::reset()
62 @sa FileBackend::reset()
63 @sa DBusBackend::reset()
64 @sa QSettingBackend::reset()
65
66 @fn QString Dtk::Core::DConfigBackend::name() const = 0
67 @brief 后端配置的唯一标识
68 @sa FileBackend::name()
69 @sa DBusBackend::name()
70 @sa QSettingBackend::name()
71
72 @fn bool Dtk::Core::DConfigBackend::isDefaultValue(const QString &key)
73 @brief 检测指定配置项名称对应的值是否为默认值。
74 @param[in] key 配置项名称
75 @sa DConfig::isDefaultValue()
76 @sa FileBackend::isDefaultValue()
77 @sa DBusBackend::isDefaultValue()
78 @sa QSettingBackend::isDefaultValue()
79
80 @class Dtk::Core::QSettingBackend dconfig.h
81 @brief QSetting后端,继承自DConfigBackend抽象接口,并实现了虚函数。
82 @sa DConfigBackend
83
84 @fn QSettingBackend Dtk::Core::QSettingBackend::QSettingBackend(DConfigPrivate* o)
85 @brief QSettingBackend构造函数
86
87 @class Dtk::Core::DConfigPrivate dconfig.h
88 @brief DConfig的私有实现
89
90 @fn DConfigPrivate Dtk::Core::DConfigPrivate::DConfigPrivate()
91 @brief DConfigPrivate构造函数
92
93 @fn bool Dtk::Core::DConfigPrivate::invalid()
94 @brief 判断此后端是否可用
95
96 @fn DConfigBackend* Dtk::Core::DConfigPrivate::getOrCreateBackend()
97 @brief 创建一个配置后端
98 @details 默认使用的配置后端会优先根据环境变量来选择配置中心的D-Bus接口还是文件配置后端接口。若没有配置此环境变量,则根据是否有配置中心提供D-Bus服务来选择配置中心服务还是文件配置后端接口。
99
100 @fn DConfigBackend* Dtk::Core::DConfigPrivate::createBackendByEnv()
101 @brief 创建一个配置后端
102 @details 尝试根据环境变量来选择配置中心的D-Bus接口还是文件配置后端接口。
103
104 @var QString Dtk::Core::DConfigPrivate::appId
105 @brief 配置文件所属的应用Id,为空时默认为本应用Id。
106
107 @var QString Dtk::Core::DConfigPrivate::name
108 @brief 配置文件名
109
110 @var QString Dtk::Core::DConfigPrivate::subpath
111 @brief 配置文件对应的子目录
112
113 @var QScopedPointer<DConfigBackend> Dtk::Core::DConfigPrivate::backend
114 @brief 配置策略后端
115
116 @class Dtk::Core::DConfig dconfig.h
117 @brief 配置策略提供的接口类
118 @details
119 ## 概述
120
121 此接口规范定义了开发库所提供的关于配置文件读写的相关接口,如果应用程序所使用的开发库实现了此规范,则程序应当优先使用开发库提供的接口。
122
123 项目目录结构如下:
124 ```bash
125 ├── CMakeLists.txt
126 ├── config
127 │ └── example.json
128 └── main.cpp
129 ```
130
131 ## CMakeLists.txt
132
133 ```cmake
134 cmake_minimum_required(VERSION 3.1.0) # 指定cmake最低版本
135
136 project(dconfig-example VERSION 1.0.0 LANGUAGES CXX) # 指定项目名称, 版本, 语言 cxx就是c++
137
138 set(CMAKE_CXX_STANDARD 11) # 指定c++标准
139 set(CMAKE_CXX_STANDARD_REQUIRED ON) # 指定c++标准要求,至少为11以上
140
141 set(CMAKE_AUTOMOC ON) # 支持qt moc
142 set(CMAKE_AUTORCC ON) # support qt resource file # 支持qt资源文件
143
144 set(CMAKE_EXPORT_COMPILE_COMMANDS ON) # 支持 clangd
145
146 if (CMAKE_VERSION VERSION_LESS "3.7.0") # 如果cmake版本小于3.7.0
147 set(CMAKE_INCLUDE_CURRENT_DIR ON) # 设置包含当前目录
148 endif()
149
150 find_package(Qt5 REQUIRED COMPONENTS Core) # 寻找Qt5组件Core
151 find_package(Dtk REQUIRED COMPONENTS Core) # 寻找Dtk组件Core
152
153 add_executable(${PROJECT_NAME} # 生成可执行文件
154 main.cpp
155 )
156
157 target_link_libraries(${PROJECT_NAME} PRIVATE # 添加需要链接的共享库
158 Qt5::Core
159 dtkcore
160 )
161
162 # dtk_add_config_meta_files函数,部署一些"meta"的配置。
163 # 函数定义在dtkcore的cmake目录下
164 # APPID 应用的ID
165 # FILES 需要部署的文件。
166 dtk_add_config_meta_files(
167 APPID ${PROJECT_NAME}
168 FILES ./config/example.json
169 )
170 ```
171
172 ## example.json
173 ```json
174 {
175 "magic": "dsg.config.meta",
176 "version": "1.0",
177 "contents": {
178 "canExit": {
179 "value": true,
180 "serial": 0,
181 "flags": ["global"],
182 "name": "I am name",
183 "name[zh_CN]": "我是名字",
184 "description": "I am description",
185 "permissions": "readwrite",
186 "visibility": "private"
187 },
188 "key1": {
189 "value": "125",
190 "serial": 0,
191 "flags": ["nooverride"],
192 "name": "I am name",
193 "name[zh_CN]": "我是名字",
194 "description": "I am description",
195 "permissions": "readwrite",
196 "visibility": "public"
197 },
198 "number": {
199 "value": 1,
200 "serial": 0,
201 "flags": ["global"],
202 "name": "array value type",
203 "permissions": "readwrite",
204 "visibility": "public"
205 },
206 "array": {
207 "value": ["value1", "value2"],
208 "serial": 0,
209 "flags": ["global"],
210 "name": "array",
211 "permissions": "readwrite",
212 "visibility": "public"
213 },
214 "map": {
215 "value": {"key1": "value1", "key2": "value2"},
216 "serial": 0,
217 "flags": ["global"],
218 "name": "map",
219 "permissions": "readwrite",
220 "visibility": "public"
221 }
222 }
223 }
224 ```
225
226 ## main.cpp
227 ```cpp
228 #include <DConfig>
229 #include <QDebug>
230 #include <QCoreApplication>
231
232 DCORE_USE_NAMESPACE
233
234 int main(int argc, char *argv[])
235 {
236 QCoreApplication a(argc, argv);
237
238 // 构造DConfig,元数据文件名example,与元数据安装目录的/usr/share/dsg/configs/APPID名(可执行文件名)对应目录/example.json,
239 DConfig config("example");
240
241 // 判断是否有效
242 if (!config.isValid()) {
243 qWarning() << QString("DConfig无效, name:[%1].").
244 arg(config.name());
245 return 0;
246 }
247
248 // 获取所有配置项的key
249 qDebug() << "所有的所有配置项的key:" << config.keyList();
250
251 // 获取指定配置项的值,配置项可以是字符串,数组,map容器,布尔值,整型,详见example.json
252 qDebug() << "canExit对应的值:" << config.value("canExit").toBool();
253
254 QVariantMap map;
255 for (int i = 0; i < 1; i++) {
256 QVariantMap nestItem;
257 for (int j = 0; j < 1; j++) {
258 nestItem[QString::number(j)] = QString::number(j);
259 }
260 map[QString::number(i)] = nestItem;
261 }
262
263 QScopedPointer<DConfig> heapConfig;
264 heapConfig.reset(new DConfig("example"));
265
266 if (!heapConfig->isValid()) {
267 qWarning() << QString("DConfig无效, name:[%1].").
268 arg(heapConfig->name());
269 return 0;
270 }
271
272 // 监听值改变的信号
273 const bool &oldValue = heapConfig->value("canExit").toBool();
274 QObject::connect(heapConfig.get(), &DConfig::valueChanged, [oldValue,&heapConfig](const QString &key){
275 qDebug() << "canExit原来的值:" << oldValue << ", canExit新的值:" << heapConfig->value(key).toBool();
276 });
277
278 // 重置canExit的值
279 heapConfig->setValue("canExit", !oldValue);
280
281 return a.exec();
282 }
283 ```
284
285 ## 从源码构建
286 ```bash
287 mkdir build && cd build
288 # 修改路径前缀为/usr,GNU标准的默认值为/usr/local
289 cmake .. -DCMAKE_INSTALL_PREFIX=/usr
290 make
291 sudo make install
292 ```
293 结果如下图
294
295 ![example](/docs/src/dconfig_example1.png)
296
297 @fn DConfig Dtk::Core::DConfig(const QString &name, const QString &subpath, QObject *parent)
298 @brief 构造配置策略提供的对象
299 @param[in] name 配置文件名
300 @param[in] subpath 配置文件对应的子目录
301 @param[in] parent 父对象
302
303 @fn DConfig Dtk::Core::DConfig(DConfigBackend *backend, const QString &name, const QString &subpath, QObject *parent)
304 @brief 使用自定义的配置策略后端构造对象
305 @param[in] backend 调用者继承于DConfigBackend的配置策略后端
306 @param[in] name 配置文件名
307 @param[in] subpath 配置文件对应的子目录
308 @param[in] parent 父对象
309
310 @fn static DConfig* Dtk::Core::DConfig::create(const QString &appId, const QString &name, const QString &subpath, QObject *parent)
311 @brief 构造配置策略提供的对象,指定配置所属的应用Id,管理某一特定应用的配置。
312 @param[in] appId 配置文件所属的应用Id,为空时默认为本应用Id
313 @param[in] name 配置文件名
314 @param[in] subpath 配置文件对应的子目录
315 @param[in] parent 父对象
316 @return 构造的配置策略对象,由调用者释放
317
318 @fn static DConfig* Dtk::Core::DConfig::create(DConfigBackend *backend, const QString &appId, const QString &name, const QString &subpath, QObject *parent)
319 @brief 构造配置策略提供的对象,指定配置所属的应用Id。
320 @param[in] backend 调用者继承于DConfigBackend的配置策略后端
321 @param[in] appId 配置文件所属的应用Id,为空时默认为本应用Id
322 @param[in] name 配置文件名
323 @param[in] subpath 配置文件对应的子目录
324 @param[in] parent 父对象
325 @return 构造的配置策略对象,由调用者释放
326
327 @fn static DConfig* Dtk::Core::DConfig::createGeneric(const QString &name, const QString &subpath, QObject *parent)
328 @brief 构造配置策略提供的对象,用来管理与应用无关的配置。
329 @param[in] name 配置文件名
330 @param[in] subpath 配置文件对应的子目录
331 @param[in] parent 父对象
332 @return 构造的配置策略对象,由调用者释放
333 @note 如果我们管理针对某一特定应用的配置,应该使用 Dtk::Core::DConfig::create(),或 Dtk::Core::DConfig(),来指定所属应用的appId。
334
335 @fn static DConfig* Dtk::Core::DConfig::createGeneric(DConfigBackend *backend, const QString &name, const QString &subpath, QObject *parent)
336 @sa Dtk::Core::DConfig::createGeneric()
337
338 @fn DConfig Dtk::Core::DConfig(DConfigBackend *backend, const QString &appId, const QString &name, const QString &subpath, QObject *parent)
339 @brief 使用自定义的配置策略后端构造对象
340 @param[in] backend 调用者继承于DConfigBackend的配置策略后端
341 @param[in] appId 配置文件所属的应用Id,为空时默认为本应用Id
342 @param[in] name 配置文件名
343 @param[in] subpath 配置文件对应的子目录
344 @param[in] parent 父对象
345 @note 调用者只构造backend,由DConfig释放。
346
347 @fn static void DConfig::setAppId(const QString &appId)
348 @brief 显示指定应用Id,不采用DSGApplication::id()作为应用Id
349 @param[in] appId 配置文件所属的应用Id
350 @note 需要在QCoreApplication构造前设置。
351
352 @fn static void DConfig::globalThread()
353 @brief 一个服务于 DConfig 的公用线程,一般用于 dconfig2cpp 生成的代码,此线程在构造时会自动调用 QThread::start 以满足 dconfig2cpp 的需求。
354 @return 此线程默认为 running 状态
355 @note 请不要析构它,它会在应用程序退出时释放
356
357 @fn QString Dtk::Core::DConfig::backendName()
358 @brief 配置策略后端名称
359 @return 配置策略后端名称
360 @note 调用者只能用DConfig访问DConfigBackend对象,所以不返回DConfigBackend对象。
361
362 @fn QStringList Dtk::Core::DConfig::keyList()
363 @brief 获得所有可用的配置项名称
364 @return 配置项名称集合
365
366 @fn bool Dtk::Core::DConfig::isValid()
367 @brief 判断此后端是否可用
368
369 @fn bool Dtk::Core::DConfig::isDefaultValue(const QString &key)
370 @brief 检测指定配置项名称对应的值是否为默认值。
371 @param[in] key 配置项名称
372
373 @fn QVariant Dtk::Core::DConfig::value(const QString &key, const QVariant &fallback)
374 @brief 根据配置项名称获得对应值
375 @param[in] key 配置项名称
376 @param[in] fallback 没有获取到配置项值后提供的默认值
377
378 @fn void Dtk::Core::DConfig::setValue(const QString &key, const QVariant &value);
379 @brief 根据配置项名称设置其值
380 @param[in] key 配置项名称
381 @param[in] value 需要更新的值
382
383 @fn void Dtk::Core::DConfig::reset(const QString &key)
384 @brief 设置其配置项对应的默认值,此值为经过override机制覆盖后的值,不一定为此配置文件中meta中定义的值
385 @param[in] key 配置项名称
386
387 @fn QString Dtk::Core::DConfig::name()
388 @brief 返回配置文件名称
389
390 @fn QString Dtk::Core::DConfig::subpath()
391 @brief 返回配置文件对应的子目录
392
393 */