QtMvvm/doc/settingsxml.dox

/*!
@page settings_xml The XML settings format
@brief Documentation of the XML format used to create settings uis

@tableofcontents

This format is used to create settings.xml files to be read by the default XML
QtMvvm::ISettingsSetupLoader. The files are read via that service and mapped to
QtMvvm::SettingsElements::Setup.

@section settings_xml_translator Translations
All the settings files you have can be easily translated via a standard ts/qm file. The following
explains how exactly.

The mvvm core module comes with a special make taget, called `lupdate` that will automatically
run lupdate when your sources change to update the TRANSLATIONS files. To not run this automatically,
call qmake with `qmake CONFIG+=no_auto_lupdate ...`. In both cases, you can always run `make lupdate`
to explicitly update the dependencies.

With this step enabled, the only thing left to do is to add the settings xml file to the translation
targets so it gets included as a source when running the lupdate target. To do so, simply add it
to the `SETTINGS_TRANSLATIONS` qmake variable:

@code{.pro}
SETTINGS_TRANSLATIONS += settings.xml
@endcode

This will internally generate a cpp file that is parsed and included in lupdate when running it
via the builtin lupdate target.

@section settings_xml_elements Elements
The possible elements of such a file

@subsection settings_xml_elements_config SettingsConfig
@copybrief QtMvvm::SettingsElements::Setup

The `<SettingsConfig>` element must be the root Element of the XML document and is mapped to the
QtMvvm::SettingsElements::Setup.

@subsubsection settings_xml_elements_config_attribs Attributes
 Name			| Type	| Default	| Translated	| Description
----------------|-------|-----------|---------------|-------------
 allowSearch	| bool	| `true`	| no			| @copybrief QtMvvm::SettingsElements::Setup::allowSearch
 allowRestore	| bool	| `true`	| no			| @copybrief QtMvvm::SettingsElements::Setup::allowRestore

@subsubsection settings_xml_elements_config_elements Content
Can be an arbitrary number of Elements from the following list. However, only one type of
element is allowed. If you for example use `<Entry>` as first child, all other children must
be of the same type as well:

- (Primary:) @ref settings_xml_elements_category
- @ref settings_xml_elements_section
- @ref settings_xml_elements_group
- @ref settings_xml_elements_entry
- @ref settings_xml_elements_include

@subsection settings_xml_elements_category Category
@copybrief QtMvvm::SettingsElements::Category

The `<Category>` element is mapped to the QtMvvm::SettingsElements::Category.

@subsubsection settings_xml_elements_category_attribs Attributes
 Name		| Type									| Default											| Translated	| Description
------------|---------------------------------------|---------------------------------------------------|---------------|-------------
 title		| string								| `"General Settings"`								| yes			| @copybrief QtMvvm::SettingsElements::Category::title
 icon		| url									| `"qrc:/de/skycoder42/qtmvvm/icons/settings.svg"`	| no			| @copybrief QtMvvm::SettingsElements::Category::icon
 tooltip	| string								| <i>Empty</i>										| yes			| @copybrief QtMvvm::SettingsElements::Category::tooltip
 frontends	| @ref settings_xml_types_descriptor	| <i>Empty</i>										| no			| @copybrief QtMvvm::SettingsElements::Category::frontends
 selectors	| @ref settings_xml_types_descriptor	| <i>Empty</i>										| no			| @copybrief QtMvvm::SettingsElements::Category::selectors

@subsubsection settings_xml_elements_category_elements Content
Can be an arbitrary number of Elements from the following list. However, only one type of
element is allowed. If you for example use `<Entry>` as first child, all other children must
be of the same type as well:

- (Primary:) @ref settings_xml_elements_section
- @ref settings_xml_elements_group
- @ref settings_xml_elements_entry
- @ref settings_xml_elements_include

@subsection settings_xml_elements_section Section
@copybrief QtMvvm::SettingsElements::Section

The `<Section>` element is mapped to the QtMvvm::SettingsElements::Section.

@subsubsection settings_xml_elements_section_attribs Attributes
 Name		| Type									| Default		| Translated	| Description
------------|---------------------------------------|---------------|---------------|-------------
 title		| string								| `"General"`	| yes			| @copybrief QtMvvm::SettingsElements::Section::title
 icon		| url									| <i>Empty</i>	| no			| @copybrief QtMvvm::SettingsElements::Section::icon
 tooltip	| string								| <i>Empty</i>	| yes			| @copybrief QtMvvm::SettingsElements::Section::tooltip
 frontends	| @ref settings_xml_types_descriptor	| <i>Empty</i>	| no			| @copybrief QtMvvm::SettingsElements::Section::frontends
 selectors	| @ref settings_xml_types_descriptor	| <i>Empty</i>	| no			| @copybrief QtMvvm::SettingsElements::Section::selectors

@subsubsection settings_xml_elements_section_elements Content
Can be an arbitrary number of Elements from the following list. However, only one type of
element is allowed. If you for example use `<Entry>` as first child, all other children must
be of the same type as well:

- (Primary:) @ref settings_xml_elements_group
- @ref settings_xml_elements_entry
- @ref settings_xml_elements_include

@subsection settings_xml_elements_group Group
@copybrief QtMvvm::SettingsElements::Group

The `<Group>` element is mapped to the QtMvvm::SettingsElements::Group. A special property of
the group is, that when the `title` is not set, the group becomes hidden and instead all
entries that are part of the group are simply shown as normal elements in the section, instead
of organizing them into subgroups. If the title is empty, the tooltip is ignored, even if set.
The descriptors however still apply.

@subsubsection settings_xml_elements_group_attribs Attributes
 Name		| Type									| Default		| Translated	| Description
------------|---------------------------------------|---------------|---------------|-------------
 title		| string								| <i>Empty</i>	| yes			| @copybrief QtMvvm::SettingsElements::Group::title
 tooltip	| string								| <i>Empty</i>	| yes			| @copybrief QtMvvm::SettingsElements::Group::tooltip
 frontends	| @ref settings_xml_types_descriptor	| <i>Empty</i>	| no			| @copybrief QtMvvm::SettingsElements::Group::frontends
 selectors	| @ref settings_xml_types_descriptor	| <i>Empty</i>	| no			| @copybrief QtMvvm::SettingsElements::Group::selectors

@subsubsection settings_xml_elements_group_elements Content
Can be an arbitrary number of Elements from the following list. However, only one type of
element is allowed. If you for example use `<Entry>` as first child, all other children must
be of the same type as well:

- (Primary:) @ref settings_xml_elements_entry
- @ref settings_xml_elements_include

@subsection settings_xml_elements_entry Entry
@copybrief QtMvvm::SettingsElements::Entry

The `<Entry>` element is mapped to the QtMvvm::SettingsElements::Entry.

@subsubsection settings_xml_elements_entry_attribs Attributes
 Name			| Type									| Default			| Translated	| Description
----------------|---------------------------------------|-------------------|---------------|-------------
 key			| string								| <i>Empty</i>		| no			| @copybrief QtMvvm::SettingsElements::Entry::key
 type			| @ref settings_xml_types_type			| `"QString"`		| no			| @copybrief QtMvvm::SettingsElements::Entry::type
 title			| string								| <i>Empty</i>		| yes			| @copybrief QtMvvm::SettingsElements::Entry::title
 tooltip		| string								| <i>Empty</i>		| yes			| @copybrief QtMvvm::SettingsElements::Entry::tooltip
 default		| variant								| <i>Invalid</i>	| `trdefault`	| @copybrief QtMvvm::SettingsElements::Entry::defaultValue
 trdefault		| bool									| `false`			| no			| If set to true, `default` will be translated. If not set or set to false, it will not be
 frontends		| @ref settings_xml_types_descriptor	| <i>Empty</i>		| no			| @copybrief QtMvvm::SettingsElements::Entry::frontends
 selectors		| @ref settings_xml_types_descriptor	| <i>Empty</i>		| no			| @copybrief QtMvvm::SettingsElements::Entry::selectors

@subsubsection settings_xml_elements_entry_elements Content
Can be an arbitrary number of Elements from the following list. They can be mixed and in any
order

- @ref settings_xml_elements_searchkey
- @ref settings_xml_elements_property

@subsection settings_xml_elements_searchkey SearchKey
The `<SearchKey>` Element is converted to a string added to the
QtMvvm::SettingsElements::Entry::searchKeys property. A searchkey can only be a child of an
Entry, and all the keys are merged to a list. It's a leaf element and must contain the string
that becomes the search key. The contens of the search key will be translated.

@subsection settings_xml_elements_property Property
The `<Property>` Element is an XML description of a generic QVariant property. Each property
gets converted to a QString key and a QVariant value that then becomes a property of the
parent element. Properties can be children of entries, as well as properties and elements, as
long as for the last two their type is `object`

@subsubsection settings_xml_elements_property_attribs Attributes
 Name	| Type							| Default			| Translated	| Description
--------|-------------------------------|-------------------|---------------|-------------
 key	| string						| <i>Required</i>	| no			| The key of the property
 type	| @ref settings_xml_types_type	| <i>Required</i>	| no			| The type of the properties value
 tr		| bool							| `false`			| no			| Specify whether the properties value (content) should be translated. Does not apply to `list` or `object` types
 ztr	| bool							| `false`			| no			| Like tr, but does not translate the text, only generate the translation in the ts file


@subsubsection settings_xml_elements_property_elements Content
The content depend on the `type` attribute. The following tables shows which type leads
to which kind of child element:

 Type			| Child Element
----------------|---------------
list			| An arbitrary number of @ref settings_xml_elements_element "Element" elements
object			| An arbitrary number of @ref settings_xml_elements_property "Property" elements
 <i>Others</i>	| Has text content. The text content is interpreted as a value of the given type

@subsection settings_xml_elements_element Element
The `<Element>` Element is an XML description of a generic QVariant list value. A property
of type `list` will have a number of elements as children that are converted to a list of
QVariant values. Each element can be of a different type, but typically they all are of the
same.

@subsubsection settings_xml_elements_element_attribs Attributes
 Name	| Type							| Default			| Translated	| Description
--------|-------------------------------|-------------------|---------------|-------------
 type	| @ref settings_xml_types_type	| <i>Required</i>	| no			| The type of the list element
 tr		| bool							| `false`			| no			| Specify whether the element value (content) should be translated. Does not apply to `list` or `object` types
 ztr	| bool							| `false`			| no			| Like tr, but does not translate the text, only generate the translation in the ts file

@subsubsection settings_xml_elements_element_elements Content
The content depend on the `type` attribute. The following tables shows which type leads
to which kind of child element:

 Type			| Child Element
----------------|---------------
 list			| An arbitrary number of @ref settings_xml_elements_element "Element" elements
 object			| An arbitrary number of @ref settings_xml_elements_property "Property" elements
 <i>Others</i>	| Has text content. The text content is interpreted as a value of the given type

@subsection settings_xml_elements_include Include
An `<Include>` element is a reference to a different file to be included at that point. When
the parser reaches an include, it continues to read the included file as if it was a part of
the original XML document. Because of that the root element of an included settings file must
not be `<SettingsConfig>`, but instead the expected primary child of the current parent
element. For example, if the include element is a child of a `<Section>`, then the root
element must be a `<Group>` element (Each element that support includes as one child type
marked as primary). It is possible to specify an include element in another included document.

@subsubsection settings_xml_elements_include_attribs Attributes
 Name		| Type									| Default		| Translated	| Description
------------|---------------------------------------|---------------|---------------|-------------
 optional	| bool									| `false`		| no			| An optional include. If the file cannot be found it is skipped instead of aborting with an error
 frontends	| @ref settings_xml_types_descriptor	| <i>Empty</i>	| no			| @copybrief QtMvvm::SettingsElements::Entry::frontends
 selectors	| @ref settings_xml_types_descriptor	| <i>Empty</i>	| no			| @copybrief QtMvvm::SettingsElements::Entry::selectors

@subsubsection settings_xml_elements_include_elements Content
The content of the include element must be a path to an XML file to be read as include. If the
path is relative, it is resolved relative to the directory of the current file (the one that
contains the include directive). It is possible to use a path with file selectors. If the file
could not be found, the parser will fail, unless the include is marked as optional.

@section settings_xml_types Attribute and Value types
In the above element descriptions a number of types are specified. Most are very basic types,
but some need some more explanation to them.

@subsection settings_xml_types_basic Basic Types
The following table lists all basic types that don't need much explanation:

 Type		| Description
------------|-------------
 string		| A simple string
 bool		| A boolean value. Allowed values are `true` and `false`
 url		| A standard XML encoded URL
 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

@subsection settings_xml_types_type type
The `type` type must be a simple string that corresponds to a C++ type name (or special ui
type, for entry elements). It defines the actual type of for example the default of the
`<Entry>` element or the contents of a `<Property>` element. Typical values would be:

- QString or string
- QUrl or url
- int
- double or number
- bool
- QDateTime or datetime
- @ref settings_xml_types_action
- list or selection
- radiolist
- ...

The type you need depends on what kind of data you want to represent via the XML elements. But
remember that all types you use must be convertible from a simple string.

@subsection settings_xml_types_descriptor descriptor
A descripter is a simplified string of a boolean logic statement. It us used for the
`frontend` and `selectors` attributes of various elements. The general idea is that these
descriptors serve as "filters". This allows you to create one xml file for all platforms and
frontends, by excluding specific elements for specific configurations. See
QtMvvm::ISettingsSetupLoader::loadSetup.

The allowed symbols and syntax depend on the attribute the descriptor is used for:

@subsubsection settings_xml_types_descriptor_frontend frontend descriptor
The frontend is the name of the GUI implementation beeing used (For example `widgest` for
the QWidgets based gui, and `quick` for the Qt Quick Controls 2 gui). Must be a string of the
following format:

@code
<frontend>[|<frontend>...]
@endcode

With `<frontend>` beeing the name of the frontend the element should be visible for. It's
basically a list of allowed frontend as simple string. If the attribute is not specified, the
element is visible on all frontends.

@subsubsection settings_xml_types_descriptor_selectors selectors descriptor
The selectors are active file selectors (of the QFileSelector class). By specifiying this
attribute you can set selectors that must be active for the element to be visible. This can
for example be used to show a specific element on one platform only. Must be a string of the
following format:

@code
<selector>[&<selector>...][|<frontend>[&<selector>...]...]
@endcode

With `<selector>` beeing the names of the selectors that must be set. It's basically a bunch
of or condiditions around and conditions. This is a very reduced boolean logic, but it should
be enough to create the desired filters. For example, you may want to show an element only on
windows or on android when the material design is used. The resulting string would be:
`windows|android&material`.

@subsection settings_xml_types_action action
The action type is meant as a placeholder for a pressable button. An action edit will simply
display a button or similar, and instead of representing a value in the settings, pressing it
will trigger QtMvvm::SettingsViewModel::callAction. The Entries `key` attribute is passed as
the first parameter to the method. The parameters can be specified by adding a `<Property>`
to the entry with the key `args` and the type `object`. The property of this object are the
elements of the map passed as the second parameter.

@section settings_xml_sample Sample settings XML file
The following code block is a sample settings XML file. It is the same that is beeing used in
the example application.

@include settings.xml

@section settings_xml_xsd The XSD for the settings files
The following file is the XSD the parser operates on. You can use it to verify your settings
xml files.

@include settingsconfig.xsd
*/