Skip to content
This repository was archived by the owner on Mar 4, 2023. It is now read-only.

Commit c928bd1

Browse files
Skycoder42Skycoder42
committed
added settings XML file doc
1 parent 1a551f7 commit c928bd1

File tree

2 files changed

+273
-3
lines changed

2 files changed

+273
-3
lines changed

‎doc/settingssetup.dox‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ implement your own format, but unless you need to open things other then normal
77
(or hate XML), there is no advantage of doing so.
88

99
@sa #QtMvvm_ISettingsSetupLoaderIid, SettingsViewModel, SettingsLoaderException,
10-
SettingsElements::Setup, TODO link to xml doc
10+
SettingsElements::Setup, @ref settings_xml
1111
*/
1212

1313
/*!
@@ -43,7 +43,7 @@ variable.
4343

4444
@note The syntax etc of these two variables depends on your loader and they are only used by you,
4545
not by anyone using this method. The default syntax used by the XML load implementation can be
46-
found in the TODO xml doc
46+
found in the @ref settings_xml "XML documentation"
4747

48-
@sa SettingsElements::Setup, QFileSelector, TODO xml doc
48+
@sa SettingsElements::Setup, QFileSelector, @ref settings_xml
4949
*/

‎doc/settingsxml.dox‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
/*!
2+
@page settings_xml The XML settings format
3+
@brief Documentation of the XML format used to create settings uis
4+
5+
This format is used to create settings.xml files to be read by the default XML
6+
QtMvvm::ISettingsSetupLoader. The files are read via that service and mapped to
7+
QtMvvm::SettingsElements::Setup.
8+
9+
@tableofcontents
10+
11+
@section settings_xml_elements Elements
12+
The possible elements of such a file
13+
14+
@subsection settings_xml_elements_config SettingsConfig
15+
@copybrief QtMvvm::SettingsElements::Setup
16+
17+
The `<SettingsConfig>` element must be the root Element of the XML document and is mapped to the
18+
QtMvvm::SettingsElements::Setup.
19+
20+
@subsubsection settings_xml_elements_config_attribs Attributes
21+
Name | Type | Default | Description
22+
----------------|-------|-----------|-------------
23+
allowSearch | bool | `true` | @copybrief QtMvvm::SettingsElements::Setup::allowSearch
24+
allowRestore | bool | `true` | @copybrief QtMvvm::SettingsElements::Setup::allowRestore
25+
26+
@subsubsection settings_xml_elements_config_elements Content
27+
Can be an arbitrary number of Elements from the following list. However, only one type of
28+
element is allowed. If you for example use `<Entry>` as first child, all other children must
29+
be of the same type as well:
30+
31+
- (Primary:) @ref settings_xml_elements_category
32+
- @ref settings_xml_elements_section
33+
- @ref settings_xml_elements_group
34+
- @ref settings_xml_elements_entry
35+
- @ref settings_xml_elements_include
36+
37+
@subsection settings_xml_elements_category Category
38+
@copybrief QtMvvm::SettingsElements::Category
39+
40+
The `<Category>` element is mapped to the QtMvvm::SettingsElements::Category.
41+
42+
@subsubsection settings_xml_elements_category_attribs Attributes
43+
Name | Type | Default | Description
44+
------------|---------------------------------------|---------------------------------------------------|-------------
45+
title | string | `"General Settings"` | @copybrief QtMvvm::SettingsElements::Category::title
46+
icon | url | `"qrc:/de/skycoder42/qtmvvm/icons/settings.svg"` | @copybrief QtMvvm::SettingsElements::Category::icon
47+
tooltip | string | <i>Empty</i> | @copybrief QtMvvm::SettingsElements::Category::tooltip
48+
frontends | @ref settings_xml_types_descriptor | <i>Empty</i> | @copybrief QtMvvm::SettingsElements::Category::frontends
49+
selectors | @ref settings_xml_types_descriptor | <i>Empty</i> | @copybrief QtMvvm::SettingsElements::Category::selectors
50+
51+
@subsubsection settings_xml_elements_category_elements Content
52+
Can be an arbitrary number of Elements from the following list. However, only one type of
53+
element is allowed. If you for example use `<Entry>` as first child, all other children must
54+
be of the same type as well:
55+
56+
- (Primary:) @ref settings_xml_elements_section
57+
- @ref settings_xml_elements_group
58+
- @ref settings_xml_elements_entry
59+
- @ref settings_xml_elements_include
60+
61+
@subsection settings_xml_elements_section Section
62+
@copybrief QtMvvm::SettingsElements::Section
63+
64+
The `<Section>` element is mapped to the QtMvvm::SettingsElements::Section.
65+
66+
@subsubsection settings_xml_elements_section_attribs Attributes
67+
Name | Type | Default | Description
68+
------------|---------------------------------------|---------------|-------------
69+
title | string | `"General"` | @copybrief QtMvvm::SettingsElements::Section::title
70+
icon | url | <i>Empty</i> | @copybrief QtMvvm::SettingsElements::Section::icon
71+
tooltip | string | <i>Empty</i> | @copybrief QtMvvm::SettingsElements::Section::tooltip
72+
frontends | @ref settings_xml_types_descriptor | <i>Empty</i> | @copybrief QtMvvm::SettingsElements::Section::frontends
73+
selectors | @ref settings_xml_types_descriptor | <i>Empty</i> | @copybrief QtMvvm::SettingsElements::Section::selectors
74+
75+
@subsubsection settings_xml_elements_section_elements Content
76+
Can be an arbitrary number of Elements from the following list. However, only one type of
77+
element is allowed. If you for example use `<Entry>` as first child, all other children must
78+
be of the same type as well:
79+
80+
- (Primary:) @ref settings_xml_elements_group
81+
- @ref settings_xml_elements_entry
82+
- @ref settings_xml_elements_include
83+
84+
@subsection settings_xml_elements_group Group
85+
@copybrief QtMvvm::SettingsElements::Group
86+
87+
The `<Group>` element is mapped to the QtMvvm::SettingsElements::Group. A special property of
88+
the group is, that when the `title` is not set, the group becomes hidden and instead all
89+
entries that are part of the group are simply shown as normal elements in the section, instead
90+
of organizing them into subgroups. If the title is empty, the tooltip is ignored, even if set.
91+
The descriptors however still apply.
92+
93+
@subsubsection settings_xml_elements_group_attribs Attributes
94+
Name | Type | Default | Description
95+
------------|---------------------------------------|---------------|-------------
96+
title | string | <i>Empty</i> | @copybrief QtMvvm::SettingsElements::Group::title
97+
tooltip | string | <i>Empty</i> | @copybrief QtMvvm::SettingsElements::Group::tooltip
98+
frontends | @ref settings_xml_types_descriptor | <i>Empty</i> | @copybrief QtMvvm::SettingsElements::Group::frontends
99+
selectors | @ref settings_xml_types_descriptor | <i>Empty</i> | @copybrief QtMvvm::SettingsElements::Group::selectors
100+
101+
@subsubsection settings_xml_elements_group_elements Content
102+
Can be an arbitrary number of Elements from the following list. However, only one type of
103+
element is allowed. If you for example use `<Entry>` as first child, all other children must
104+
be of the same type as well:
105+
106+
- (Primary:) @ref settings_xml_elements_entry
107+
- @ref settings_xml_elements_include
108+
109+
@subsection settings_xml_elements_entry Entry
110+
@copybrief QtMvvm::SettingsElements::Entry
111+
112+
The `<Entry>` element is mapped to the QtMvvm::SettingsElements::Entry.
113+
114+
@subsubsection settings_xml_elements_entry_attribs Attributes
115+
Name | Type | Default | Description
116+
----------------|---------------------------------------|-------------------|-------------
117+
key | string | <i>Empty</i> | @copybrief QtMvvm::SettingsElements::Entry::key
118+
type | @ref settings_xml_types_type | `"QString"` | @copybrief QtMvvm::SettingsElements::Entry::type
119+
title | string | <i>Empty</i> | @copybrief QtMvvm::SettingsElements::Entry::title
120+
tooltip | string | <i>Empty</i> | @copybrief QtMvvm::SettingsElements::Entry::tooltip
121+
defaultValue | variant | <i>Invalid</i> | @copybrief QtMvvm::SettingsElements::Entry::defaultValue
122+
frontends | @ref settings_xml_types_descriptor | <i>Empty</i> | @copybrief QtMvvm::SettingsElements::Entry::frontends
123+
selectors | @ref settings_xml_types_descriptor | <i>Empty</i> | @copybrief QtMvvm::SettingsElements::Entry::selectors
124+
125+
@subsubsection settings_xml_elements_entry_elements Content
126+
Can be an arbitrary number of Elements from the following list. They can be mixed and in any
127+
order
128+
129+
- @ref settings_xml_elements_searchkey
130+
- @ref settings_xml_elements_property
131+
132+
@subsection settings_xml_elements_searchkey SearchKey
133+
The `<SearchKey>` Element is converted to a string added to the
134+
QtMvvm::SettingsElements::Entry::searchKeys property. A searchkey can only be a child of an
135+
Entry, and all the keys are merged to a list. It's a leaf element and must contain the string
136+
that becomes the search key
137+
138+
@subsection settings_xml_elements_property Property
139+
The `<Property>` Element is an XML description of a generic QVariant property. Each property
140+
gets converted to a QString key and a QVariant value that then becomes a property of the
141+
parent element. Properties can be children of entries, as well as properties and elements, as
142+
long as for the last two their type is `object`
143+
144+
@subsubsection settings_xml_elements_property_attribs Attributes
145+
Name | Type | Default | Description
146+
--------|-------------------------------|-------------------|-------------
147+
key | string | <i>Required</i> | The key of the property
148+
type | @ref settings_xml_types_type | <i>Required</i> | The type of the properties value
149+
ts | bool | `false` | Specify whether the properties value should be translated. Does not apply to `list` or `object` types
150+
151+
@subsubsection settings_xml_elements_property_elements Content
152+
The content depend on the `type` attribute. The following tables shows which type leads
153+
to which kind of child element:
154+
155+
Type | Child Element
156+
----------------|---------------
157+
list | An arbitrary number of @ref settings_xml_elements_element "Element" elements
158+
object | An arbitrary number of @ref settings_xml_elements_property "Property" elements
159+
<i>Others</i> | Has text content. The text content is interpreted as a value of the given type
160+
161+
@subsection settings_xml_elements_element Element
162+
The `<Element>` Element is an XML description of a generic QVariant list value. A property
163+
of type `list` will have a number of elements as children that are converted to a list of
164+
QVariant values. Each element can be of a different type, but typically they all are of the
165+
same.
166+
167+
@subsubsection settings_xml_elements_element_attribs Attributes
168+
Name | Type | Default | Description
169+
--------|-------------------------------|-------------------|-------------
170+
type | @ref settings_xml_types_type | <i>Required</i> | The type of the list element
171+
ts | bool | `false` | Specify whether the element value should be translated. Does not apply to `list` or `object` types
172+
173+
@subsubsection settings_xml_elements_element_elements Content
174+
The content depend on the `type` attribute. The following tables shows which type leads
175+
to which kind of child element:
176+
177+
Type | Child Element
178+
----------------|---------------
179+
list | An arbitrary number of @ref settings_xml_elements_element "Element" elements
180+
object | An arbitrary number of @ref settings_xml_elements_property "Property" elements
181+
<i>Others</i> | Has text content. The text content is interpreted as a value of the given type
182+
183+
@subsection settings_xml_elements_include Include
184+
An `<Include>` element is a reference to a different file to be included at that point. When
185+
the parser reaches an include, it continues to read the included file as if it was a part of
186+
the original XML document. Because of that the root element of an included settings file must
187+
not be `<SettingsConfig>`, but instead the expected primary child of the current parent
188+
element. For example, if the include element is a child of a `<Section>`, then the root
189+
element must be a `<Group>` element (Each element that support includes as one child type
190+
marked as primary). It is possible to specify an include element in another included document.
191+
192+
@subsubsection settings_xml_elements_include_attribs Attributes
193+
Name | Type | Default | Description
194+
------------|-------|-----------|-------------
195+
optional | bool | `false` | An optional include. If the file cannot be found it is skipped instead of aborting with an error
196+
197+
@subsubsection settings_xml_elements_include_elements Content
198+
The content of the include element must be a path to an XML file to be read as include. If the
199+
path is relative, it is resolved relative to the directory of the current file (the one that
200+
contains the include directive). It is possible to use a path with file selectors. If the file
201+
could not be found, the parser will fail, unless the include is marked as optional.
202+
203+
@section settings_xml_types Attribute and Value types
204+
In the above element descriptions a number of types are specified. Most are very basic types,
205+
but some need some more explanation to them.
206+
207+
@subsection settings_xml_types_basic Basic Types
208+
The following table lists all basic types that don't need much explanation:
209+
210+
Type | Description
211+
------------|-------------
212+
string | A simple string
213+
bool | A boolean value. Allowed values are `true` and `false`
214+
url | A standard XML encoded URL
215+
variant | A string that is read by C++ as string and then stored as QVariant. It thus must be a string convertible to the desired type via QVariant
216+
217+
@subsection settings_xml_types_type type
218+
The `type` type must be a simple string that corresponds to a C++ type name (or special ui
219+
type, for entry elements). It defines the actual type of for example the defaultValue of the
220+
`<Entry>` element or the contents of a `<Property>` element. Typical values would be:
221+
222+
- QString or string
223+
- QUrl or url
224+
- int
225+
- double or number
226+
- bool
227+
- QDateTime or datetime
228+
- ...
229+
230+
The type you need depends on what kind of data you want to represent via the XML elements. But
231+
remember that all types you use must be convertible from a simple string.
232+
233+
@subsection settings_xml_types_descriptor descriptor
234+
A descripter is a simplified string of a boolean logic statement. It us used for the
235+
`frontend` and `selectors` attributes of various elements. The general idea is that these
236+
descriptors serve as "filters". This allows you to create one xml file for all platforms and
237+
frontends, by excluding specific elements for specific configurations. See
238+
QtMvvm::ISettingsSetupLoader::loadSetup.
239+
240+
The allowed symbols and syntax depend on the attribute the descriptor is used for:
241+
242+
@subsubsection settings_xml_types_descriptor_frontend frontend descriptor
243+
The frontend is the name of the GUI implementation beeing used (For example `widgest` for
244+
the QWidgets based gui, and `quick` for the Qt Quick Controls 2 gui). Must be a string of the
245+
following format:
246+
247+
@code
248+
<frontend>[|<frontend>...]
249+
@endcode
250+
251+
With `<frontend>` beeing the name of the frontend the element should be visible for. It's
252+
basically a list of allowed frontend as simple string. If the attribute is not specified, the
253+
element is visible on all frontends.
254+
255+
@subsubsection settings_xml_types_descriptor_selectors selectors descriptor
256+
The selectors are active file selectors (of the QFileSelector class). By specifiying this
257+
attribute you can set selectors that must be active for the element to be visible. This can
258+
for example be used to show a specific element on one platform only. Must be a string of the
259+
following format:
260+
261+
@code
262+
<selector>[&<selector>...][|<frontend>[&<selector>...]...]
263+
@endcode
264+
265+
With `<selector>` beeing the names of the selectors that must be set. It's basically a bunch
266+
of or condiditions around and conditions. This is a very reduced boolean logic, but it should
267+
be enough to create the desired filters. For example, you may want to show an element only on
268+
windows or on android when the material design is used. The resulting string would be:
269+
`windows|android&material`.
270+
*/

0 commit comments

Comments
 (0)