Debian Codegraph @

docs/settings/dsettings.zh_CN.dox

raw
1 /*!
2 @~chinese
3 @file include/settings/dsettings.h
4 @ingroup dsettings
5 @class Dtk::Core::DSettingsBackend dsettings.h
6 @brief DSettingsBackend是一个配置存储类的接口
7 @details 简单的例子:
8 @code
9 {
10 "groups": [{
11 "key": "base",
12 "name": "Basic settings",
13 "groups": [{
14 "key": "open_action",
15 "name": "Open Action",
16 "options": [{
17 "key": "alway_open_on_new",
18 "type": "checkbox",
19 "text": "Always Open On New Windows",
20 "default": true
21 },
22 {
23 "key": "open_file_action",
24 "name": "Open File:",
25 "type": "combobox",
26 "default": ""
27 }
28 ]
29 },
30 {
31 "key": "new_tab_windows",
32 "name": "New Tab & Window",
33 "options": [{
34 "key": "new_window_path",
35 "name": "New Window Open:",
36 "type": "combobox",
37 "default": ""
38 },
39 {
40 "key": "new_tab_path",
41 "name": "New Tab Open:",
42 "type": "combobox",
43 "default": ""
44 }
45 ]
46 }
47 ]
48 }]
49 }
50 @endcode
51
52 读取/设置其值的示例如下:
53 @code
54 // 初始化一个存储后端
55 QTemporaryFile tmpFile;
56 tmpFile.open();
57 auto backend = new Dtk::Core::QSettingBackend(tmpFile.fileName());
58
59 // 从json中初始化配置
60 auto settings = Dtk::Core::DSettings::fromJsonFile(":/resources/data/dfm-settings.json");
61 settings->setBackend(backend);
62
63 // 读取配置
64 auto opt = settings->option("base.new_tab_windows.new_window_path");
65 qDebug() << opt->value();
66
67 // 修改配置
68 opt->setValue("Test")
69 qDebug() << opt->value();
70 @endcode
71 @sa Dtk::Core::DSettingsOption
72 @sa Dtk::Core::DSettingsGroup
73 @sa Dtk::Core::DSettingsBackend
74 @sa Dtk::Widget::DSettingsWidgetFactory
75 @sa Dtk::Widget::DSettingsDialog
76
77 @fn Dtk::Core::DSettingsBackend::DSettingsBackend(QObject *parent = Q_NULLPTR)
78 @brief DSettingsBackend构造函数
79
80 @fn virtual QStringList DSettingsBackend::keys() const = 0;
81 @brief 返回全部键值
82
83 @fn virtual QVariant DSettingsBackend::getOption(const QString &key) const = 0;
84 @brief 获取 `key` 对应的值
85
86 @fn virtual void DSettingsBackend::doSync() = 0;
87 @brief 开始进行同步
88
89 @fn virtual void DSettingsBackend::doSetOption(const QString &key, const QVariant &value) = 0;
90 @brief 设置`key`对应的值,并使用存储后端进行存储。
91
92 @fn void DSettingsBackend::optionChanged(const QString &key, const QVariant &value);
93 @brief DSettingsOption的值发生变化时发出的信号。
94 @details `key` 发生改变的 option 键,`value`对应键的值。
95
96 @fn void DSettingsBackend::sync();
97 @brief 私有信号,请勿使用。
98
99 @fn void DSettingsBackend::setOption(const QString &key, const QVariant &value);
100 @brief 私有信号,请勿使用。
101
102 @class Dtk::Core::DSettings dsettings.h
103 @brief DSettings是设计上为Dtk的应用程序提供统一的配置存储以及界面生成工具的基础库。
104 @details DSetting使用json作为应用配置程序的描述文件。简单来说,应用查询的配置分为组/键值二个基础层级,
105 对于一个标准的Dtk配置控件,一般只包含组/子组/键值三个层级,对于超过三个层级的键值,可以通过
106 DSettings的API接口进行读取和写入,但是不能在标准的DSettingsDialogs上显示出来。
107
108 一个简单的配置文件如下:
109 @code
110 {
111 "groups": [{
112 "key": "base",
113 "name": "Basic settings",
114 "groups": [{
115 "key": "open_action",
116 "name": "Open Action",
117 "options": [{
118 "key": "alway_open_on_new",
119 "type": "checkbox",
120 "text": "Always Open On New Windows",
121 "default": true
122 },
123 {
124 "key": "open_file_action",
125 "name": "Open File:",
126 "type": "combobox",
127 "default": ""
128 }
129 ]
130 },
131 {
132 "key": "new_tab_windows",
133 "name": "New Tab & Window",
134 "options": [{
135 "key": "new_window_path",
136 "name": "New Window Open:",
137 "type": "combobox",
138 "default": ""
139 },
140 {
141 "key": "new_tab_path",
142 "name": "New Tab Open:",
143 "type": "combobox",
144 "default": ""
145 }
146 ]
147 }
148 ]
149 }]
150 }
151 @endcode
152
153 该组中包含一个base的root组,两个子组: open_action/new_tab_windows,每个子组有包含若干选项。
154 对于"New Window Open:"这个配置,其完整的访问id为base.new_tab_windows.new_window_path。
155
156 读取/设置其值的示例如下:
157 @code
158 // 初始化一个存储后端
159 QTemporaryFile tmpFile;
160 tmpFile.open();
161 auto backend = new Dtk::Core::QSettingBackend(tmpFile.fileName());
162
163 // 从json中初始化配置
164 auto settings = Dtk::Core::DSettings::fromJsonFile(":/resources/data/dfm-settings.json");
165 settings->setBackend(backend);
166
167 // 读取配置
168 auto opt = settings->option("base.new_tab_windows.new_window_path");
169 qDebug() << opt->value();
170
171 // 修改配置
172 opt->setValue("Test")
173 qDebug() << opt->value();
174 @endcode
175 @sa Dtk::Core::DSettingsOption
176 @sa Dtk::Core::DSettingsGroup
177 @sa Dtk::Core::DSettingsBackend
178 @sa Dtk::Widget::DSettingsWidgetFactory
179 @sa Dtk::Widget::DSettingsDialog
180
181 @fn Dtk::Core::DSettings::DSettings(QObject *parent = Q_NULLPTR)
182 @brief DSettings构造函数
183
184 @fn void Dtk::Core::DSettings::setBackend(DSettingsBackend *backend = nullptr)
185 @brief 设置存储后端
186
187 @fn static QPointer<DSettings> Dtk::Core::DSettings::fromJson(const QByteArray &json)
188 @brief 从 json 中获取 DSettings,返回的数据使用之后需要自己手动释放。
189
190 @fn static QPointer<DSettings> Dtk::Core::DSettings::fromJsonFile(const QString &filepath)
191 @brief 从 json 文件中获取 DSetting。
192
193 @fn QJsonObject Dtk::Core::DSettings::meta() const
194 @brief 返回JSON对象
195
196 @fn QStringList Dtk::Core::DSettings::keys() const
197 @brief 返回全部键值
198
199 @fn QList<QPointer<DSettingsOption> > Dtk::Core::DSettings::options() const
200 @brief 返回全部 `key` 的值
201
202 @fn QPointer<DSettingsOption> Dtk::Core::DSettings::option(const QString &key) const
203 @brief 获取 `key` 对应的值
204
205 @fn QVariant Dtk::Core::DSettings::value(const QString &key) const
206 @brief 获取 `key` 对应的值
207
208 @fn QStringList Dtk::Core::DSettings::groupKeys() const
209 @brief 返回子组全部键值
210
211 @fn QList<QPointer<DSettingsGroup> > Dtk::Core::DSettings::groups() const
212 @brief 返回子组全部 `key` 的值
213
214 @fn QPointer<DSettingsGroup> Dtk::Core::DSettings::group(const QString &key) const
215 @brief DSettings::group将递归找到子组
216 @return
217
218 @fn QVariant Dtk::Core::DSettings::getOption(const QString &key) const
219 @brief 获取 `key` 对应的值
220
221 @fn void Dtk::Core::DSettings::sync()
222 @brief 开始进行同步
223
224 @fn void Dtk::Core::DSettings::setOption(const QString &key, const QVariant &value)
225 @brief 设置键值
226
227 @fn void Dtk::Core::DSettings::reset()
228 @brief 重置键值
229
230 */