Skycoder42
6 years ago
8 changed files with 459 additions and 18 deletions
@ -0,0 +1,336 @@ |
|||
/*! |
|||
@page settings_generator The qsettingsgenerator Tool |
|||
@brief A tool to generate static, typesafe settings access without having to type key strings |
|||
|
|||
@tableofcontents |
|||
|
|||
The general idea is that instead of this: |
|||
@code{.cpp} |
|||
QSettins settings; |
|||
int value = settings.value("my/key", 42).toInt(); |
|||
@endcode |
|||
|
|||
You create a settings file like this: |
|||
@code{.xml} |
|||
<Settings name="Settings"> |
|||
<Node key="my"> |
|||
<Entry key="key" type="int" default="42"/> |
|||
</Node> |
|||
</Settings> |
|||
@endcode |
|||
|
|||
And can now access the data like this: |
|||
@code{.cpp} |
|||
int value = Settings::instance()->my.key; |
|||
@endcode |
|||
|
|||
So in summary: First, using QSettings requires you to type in |
|||
strings as keys - which cannot be checked by the compiler. With this tool you get a c++ member |
|||
hirachie instead - which is checked by the compiler and thus typo free. Also, the values in |
|||
the settings are made statically typed by using this generator. The second point was to support |
|||
multiple backends, not only QSettings, without having to change the frontend code. |
|||
|
|||
@section settings_generator_features Features |
|||
- Access settings via code - no more typos and redundant strings! |
|||
- Static typing gives additionl saftey and is easier to use (no `.toType()` calls needed) |
|||
- Default values in one single, central place - less error prone and easier to maintain |
|||
- Can be specified as strings in the xml |
|||
- Can be specified as C++ code in the xml |
|||
- Use as a global single instance or create local instances |
|||
- Support for custom settings backends instead of QSettings alone |
|||
- QtMvvm::QSettingsAccessor for usage with QSettings (the default) |
|||
- QtMvvm::DataSyncSettingsAccessor to sync settings via [QtDataSync](https://github.com/Skycoder42/QtDataSync) |
|||
- QtMvvm::AndroidSettingsAccessor (android only) to access the SharedPreferences |
|||
- Can be used as an injectable service |
|||
|
|||
@section settings_generator_usage Usage |
|||
Using QtMvvmCore adds a custom qmake compiler to you project. All you need to do is to create the settings xml |
|||
definition and then add it to the pro file as `SETTINGS_DEFINITIONS += mysettings.xml`. This will create a header |
|||
named "mysettings.h" you can include. That header contains the C++ generated settings class to access the settings. |
|||
|
|||
@subsection settings_generator_usage_example Example |
|||
Create a pro file with and add the lines: |
|||
@code{.pro} |
|||
QT += mvvmcore |
|||
|
|||
SETTINGS_DEFINITIONS += mysettings.xml |
|||
@endcode |
|||
|
|||
Create a file named `mysettings.xml` and fill it: |
|||
@code{.xml} |
|||
<?xml version="1.0" encoding="UTF-8" ?> |
|||
<Settings name="MySettings"> |
|||
<Node key="my"> |
|||
<Entry key="key" type="int" default="42"/> |
|||
</Node> |
|||
</Settings> |
|||
@endcode |
|||
|
|||
Finally, adjust you main to look like this: |
|||
@code{.cpp} |
|||
#include <QCoreApplication> |
|||
#include <QDebug> |
|||
#include "mysettings.h" |
|||
|
|||
int main(int argc, char *argv[]) |
|||
{ |
|||
QCoreApplication a(argc, argv); |
|||
|
|||
int myKey = MySettings::instance()->my.key; |
|||
qDebug() << myKey; |
|||
|
|||
return 0; |
|||
} |
|||
@endcode |
|||
|
|||
@section settings_generator_qml QML-Bindings |
|||
The tool can also generate QML-Bindings, so you can access the settings in the same way from |
|||
QML. To do so, add to your pro file (in addition to `SETTINGS_DEFINITIONS`): |
|||
@code{.pro} |
|||
QML_SETTINGS_DEFINITIONS += mysettings.xml |
|||
@endcode |
|||
|
|||
And also add some QML metadata using the Qml element in the settings |
|||
@code{.xml} |
|||
<?xml version="1.0" encoding="UTF-8" ?> |
|||
<Settings name="MySettings"> |
|||
<Qml uri="com.example.settings" |
|||
major="1" |
|||
minor="0"/> |
|||
<!-- ... --> |
|||
</Settings> |
|||
@endcode |
|||
|
|||
And with that, you can use the specified uri to access the settings from QML: |
|||
@code{.qml} |
|||
import com.example.settings 1.0 |
|||
|
|||
SomeItem { |
|||
someProperty: MySettings.my.key |
|||
} |
|||
@endcode |
|||
|
|||
@section settings_generator_format XML-Format Documentation |
|||
The following sections document the different elements and attributes in the XML format used |
|||
by the generator. |
|||
|
|||
@subsection settings_generator_elements Elements |
|||
The possible elements of such a file. |
|||
|
|||
@subsubsection settings_generator_elements_Settings Settings |
|||
The root Element of the XML document. It defines meta-stuff and the actual nodes and entries. |
|||
|
|||
@paragraph settings_generator_elements_Settings_attributes Attributes |
|||
Name | Type | Default/Required | Description |
|||
------------|-----------------------------------------------|-----------------------|------------- |
|||
name | string | _filename_ | The C++ class name of the generated class |
|||
prefix | string | _empty_ | Specify an export macro. The value is put before the class definition, if you want to export the generated class from a dynamic library |
|||
baseKey | string | _empty_ | A base settings key that is prepended to all keys |
|||
scope | @ref settings_generator_values_InstanceScope | DestroyOnAppDestroy | The destruction scope of the create service instance |
|||
|
|||
@paragraph settings_generator_elements_Settings_children Child elements |
|||
Name | XML-Type | Limits | Description |
|||
----------------|-----------------------------------------------|-----------|------------- |
|||
Include | @ref settings_generator_elements_Include | 0 - ∞ | A header file to be included |
|||
Backend | @ref settings_generator_elements_Backend | 0 - 1 | The definition of the settings backend to use |
|||
Qml | @ref settings_generator_elements_Qml | 0 - 1 | Special configuration parameters for the QML bindings |
|||
TypeMapping | @ref settings_generator_elements_TypeMapping | 0 - ∞ | Type mappings to map abstract type names to C++ types |
|||
<node> | @ref settings_generator_elements_NodeContent | 0 - ∞ | General "node-like" elements, that can be inside any node-like element |
|||
|
|||
@subsubsection settings_generator_elements_Include Include |
|||
Describes a file to be included via a c++ include directive. You can use them if you want to |
|||
make use of special classes in your generated classes. Both global includes (#include <header>) |
|||
and local includes (#include "header") are supported.<br/> |
|||
|
|||
@paragraph settings_generator_elements_Include_attributes Attributes |
|||
Name | Type | Default/Required | Description |
|||
--------|-------|-------------------|------------- |
|||
local | bool | false | Specifies whether the include is a global or a local include |
|||
|
|||
@paragraph settings_generator_elements_Include_children Content |
|||
The content of this element must be a string. More specific the header to be included. It |
|||
becomes the content of the include directive. Specifiy it without the braces or quores, as thoes |
|||
are added automatically. |
|||
|
|||
@subsubsection settings_generator_elements_Backend Backend |
|||
The backend element can be used to select a different QtMvvm::ISettingsAccessor instead of the |
|||
standard QtMvvm::QSettingsAccessor. |
|||
|
|||
@paragraph settings_generator_elements_Backend_attributes Attributes |
|||
Name | Type | Default/Required | Description |
|||
--------|-----------|-------------------|------------- |
|||
class | string | _required_ | The C++ class name of the backend to be used. Must be a class that implements QtMvvm::ISettingsAccessor |
|||
|
|||
@paragraph settings_generator_elements_Backend_children Child elements |
|||
Name | XML-Type | Limits | Description |
|||
--------|-------------------------------------------|-----------|------------- |
|||
Param | @ref settings_generator_elements_Param | 0 - ∞ | A parameter to be passed to the backends constructor, before the QObject* parent |
|||
|
|||
@subsubsection settings_generator_elements_Param Param |
|||
A generic parameter to be passed to C++ method. |
|||
|
|||
@paragraph settings_generator_elements_Param_attributes Attributes |
|||
Name | Type | Default/Required | Description |
|||
--------|-----------|-------------------|------------- |
|||
type | string | _required_ | The C++ class name of type of the parameter. |
|||
asStr | bool | false | Specify how the element content should be interpreted |
|||
|
|||
@paragraph settings_generator_elements_Param_children Content |
|||
The content of a param represents the value of the parameter. How the content is interpreted |
|||
depends on the asStr attribute. |
|||
|
|||
If it is set to false (the default), the content must be c++ code and is copied to the generated |
|||
class as is. The code must be an expression that evalutes to a single value that is implicitly |
|||
convertible to the given type. If type was for example int, valid expressions could be: |
|||
|
|||
@code{.xml} |
|||
<Param type="int">-1</Param> |
|||
<Param type="int">10 + 20</Param> |
|||
<Param type="int">qRand()</Param> |
|||
@endcode |
|||
|
|||
If set to true, the content is assumed to be a string. You don't need to specify quotation |
|||
marks around the string. That string is used to initialize a QVariant that is then converted to |
|||
type - in other words, the type you use must be variant convertible from a string. This can be |
|||
used to, for example, create a QDate from a string with the value of |
|||
`<Param type="QDate" asStr="true">2018-05-09</Param>`.<br/> |
|||
|
|||
@subsubsection settings_generator_elements_Qml Qml |
|||
The Qml element contains special properties that are only used for QML binding generation. |
|||
|
|||
@paragraph settings_generator_elements_Qml_attributes Attributes |
|||
Name | Type | Default/Required | Description |
|||
------------|-------------------------------------------------------|-------------------|------------- |
|||
uri | string | _required_ | The QML-Import URI for the QML module |
|||
major | int | 1 | The major version of the generated module |
|||
minor | int | 0 | The minor version of the generated module |
|||
type | @ref settings_generator_values_QmlRegistrationMode | Singleton | The mode on how to register the instance in QML |
|||
register | bool | true | Specify, if the type should be registered automatically |
|||
header | string | _empty_ | A custom path to the generate C++-Code of the settings generator, if it can't be the default path |
|||
|
|||
@subsubsection settings_generator_elements_TypeMapping TypeMapping |
|||
Type mappings allow you to specify the C++-type of an arbitrary type to be replaced by in the |
|||
generated code. This can be useful when importing a @ref settings_xml "Settings-XML" file. |
|||
|
|||
@paragraph settings_generator_elements_TypeMapping_attributes Attributes |
|||
Name | Type | Default/Required | Description |
|||
--------|-----------|-------------------|------------- |
|||
key | string | _required_ | The fake type name |
|||
type | string | _required_ | The C++-type to replace it with |
|||
|
|||
@subsubsection settings_generator_elements_NodeContent NodeContent Elements |
|||
Elements that have the NodeContent as child type can have a combination of the following |
|||
actual child elements. Can can be unordered and mixed in any way: |
|||
|
|||
- @ref settings_generator_elements_Node |
|||
- @ref settings_generator_elements_Entry |
|||
- @ref settings_generator_elements_ListNode |
|||
- @ref settings_generator_elements_Import |
|||
|
|||
@subsubsection settings_generator_elements_Node Node |
|||
The node represents a sub-group within the settings. All elements within the node will have |
|||
the node's key prepended to their key (seperated by a `/`) |
|||
|
|||
@paragraph settings_generator_elements_Node_attributes Attributes |
|||
Name | Type | Default/Required | Description |
|||
--------|-----------|-------------------|------------- |
|||
key | string | _required_ | The name (and group key) of the node |
|||
|
|||
@paragraph settings_generator_elements_Node_children Child elements |
|||
Name | XML-Type | Limits | Description |
|||
----------------|-----------------------------------------------|-----------|------------- |
|||
<node> | @ref settings_generator_elements_NodeContent | 0 - ∞ | General "node-like" elements, that can be inside any node-like element |
|||
|
|||
@subsubsection settings_generator_elements_Entry Entry |
|||
The Entry element is an extension of the @ref settings_generator_elements_Node type. This |
|||
means it's the same as a Node, but with additional properties. |
|||
|
|||
The entry represents a leaf entry in the settings, with a value that can be loaded and stored |
|||
from the settings via the entry's key (within the node subgroups). Entries themselves can also |
|||
be used as a node as well, and thus contain child elements, too. |
|||
|
|||
The default value can be specified in 2 ways. Either as a string (via the attribute) that is |
|||
converted to the target type using QVariant, or via the `<Code>` child element, that contains |
|||
actual C++-Code that evaluates to a default value. |
|||
|
|||
@sa QtMvvm::SettingsEntry |
|||
|
|||
@paragraph settings_generator_elements_Entry_attributes Attributes |
|||
Name | Type | Default/Required | Description |
|||
------------|-----------|-------------------|------------- |
|||
type | string | _required_ | The C++-type that this entry saves and loads. Can be a virtual type, that is resolved by a @ref settings_generator_elements_TypeMapping |
|||
qmlGroupKey | string | `<key>Group` | The name the property that holds the entries sub-nodes for the QML binding |
|||
default | string | _empty_ | A default value (as string) to be returned if the entry is not stored in the settings |
|||
tr | bool | false | Specify whether the default value should be translated |
|||
trContext | string | _filename_ | A custom translation context to use instead of the filename |
|||
|
|||
@paragraph settings_generator_elements_Entry_children Additional Child elements |
|||
Name | XML-Type | Limits | Description |
|||
--------|---------------------------------------|-----------|------------- |
|||
Code | @ref settings_generator_elements_Code | 0 - 1 | C++-Code to create a default value |
|||
|
|||
@subsubsection settings_generator_elements_ListNode ListNode |
|||
The ListNode element is an extension of the @ref settings_generator_elements_Node type. This |
|||
means it's the same as a Node, but with additional properties. |
|||
|
|||
The ListNode is a special node that allows you to easily store lists of elements. All children |
|||
that are defined within a listnode are part of the "array elements", so you will access |
|||
elements in a list node via `listNode[2].group.entry` and can append and remove elements from |
|||
that list. |
|||
|
|||
@sa QtMvvm::SettingsListNode |
|||
|
|||
@subsubsection settings_generator_elements_ImportType ImportType |
|||
The Imports allow you to include other files within this one as sub elements. You can include |
|||
either a Settings-Generator-XML (this file) or a @ref settings_xml "Settings-XML". The |
|||
imported file is then treated like it's contents where simply defined instead of the import |
|||
element, allowing seemless combination of different files. |
|||
|
|||
You can use the rootNode to instead of importing the root element in the importet file, go |
|||
down to the node that matches the key defined by rootNode and only import that part. |
|||
|
|||
@paragraph settings_generator_elements_ImportType_attributes Attributes |
|||
Name | Type | Default/Required | Description |
|||
------------|-----------|-------------------|------------- |
|||
required | bool | true | Specify, if the import is required or optional |
|||
rootNode | string | _empty_ | A root node withing the imported file to use as a starting point |
|||
|
|||
@paragraph settings_generator_elements_ImportType_children Content |
|||
The content of the element is a string - the path to the file to be imported. If the path is |
|||
a relative path, it is resolved relative to the file that is importing it, aka "this" file. |
|||
|
|||
@subsection settings_generator_values XML-Types |
|||
The XML-Types are not elements, but values of attributes etc. that have been defined for the |
|||
file. |
|||
|
|||
@subsubsection settings_generator_values_InstanceScope InstanceScope |
|||
InstanceScope is a simple enum with the following allowed values: |
|||
|
|||
Name | Description |
|||
----------------------------|------------- |
|||
DestroyOnAppQuit | Sets the scope of the created mvvm service to QtMvvm::ServiceRegistry::DestroyOnAppQuit |
|||
DestroyOnAppDestroy | Sets the scope of the created mvvm service to QtMvvm::ServiceRegistry::DestroyOnAppDestroy |
|||
DestroyOnRegistryDestroy | Sets the scope of the created mvvm service to QtMvvm::ServiceRegistry::DestroyOnRegistryDestroy |
|||
DestroyNever | Sets the scope of the created mvvm service to QtMvvm::ServiceRegistry::DestroyNever |
|||
|
|||
@subsubsection settings_generator_values_QmlRegistrationMode QmlRegistrationMode |
|||
InstanceScope is a simple enum with the following allowed values: |
|||
|
|||
Name | Description |
|||
----------------|------------- |
|||
Singleton | Register the QML type as a singleton instance |
|||
Uncreatable | Register the QML type as a uncreatable type |
|||
Creatable | Register the QML type as a normal, constructable type |
|||
|
|||
@section settings_generator_sample Sample settings generator XML file |
|||
The following code block is a sample of a settings generator XML file. It's a little bigger to |
|||
show of the capabilities |
|||
|
|||
@include generatortest.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 qsettingsgenerator.xsd |
|||
*/ |
|||
@ -0,0 +1,86 @@ |
|||
<?xml version="1.0" encoding="UTF-8" ?> |
|||
<Settings name="TestSettings" |
|||
prefix="SOME_EXPORT" |
|||
baseKey="tests" |
|||
scope="DestroyOnAppQuit"> |
|||
<Include>QtCore/QDateTime</Include> |
|||
<Include local="false">QtCore/QUrl</Include> |
|||
<Include local="true">testbackend.h</Include> |
|||
|
|||
<Backend class="TestBackend"> |
|||
<Param type="QString" asStr="true">Test Backend</Param> |
|||
<Param type="int">42</Param> |
|||
</Backend> |
|||
|
|||
<TypeMapping key="range" type="int"/> |
|||
|
|||
<Node key="emptyNode"/> |
|||
<Entry key="emptyEntry" |
|||
type="bool"/> |
|||
<Entry key="advancedEntry" |
|||
type="QString" |
|||
qmlGroupKey="qmlAdvancedEntry" |
|||
default="Hello World" |
|||
tr="true" |
|||
trContext="some_context"/> |
|||
<Entry key="codeEntry" |
|||
type="QUrl"> |
|||
<Code>QUrl::fromLocalFile(QStringLiteral("/path/to/something"))</Code> |
|||
</Entry> |
|||
|
|||
<Node key="parentNode"> |
|||
<Node key="emptyChildNode"/> |
|||
<Node key="fullChildNode"> |
|||
<Entry key="replaceEntry" |
|||
type="range" |
|||
default="42"/> |
|||
</Node> |
|||
<Entry key="parentEntry" |
|||
type="bool" |
|||
default="true"> |
|||
<Node key="subNode"/> |
|||
<Entry key="nodeWithCodeEntry" |
|||
type="int"> |
|||
<Node key="someNode"/> |
|||
<Code> |
|||
qRound(42.8) |
|||
</Code> |
|||
</Entry> |
|||
<Entry key="leafEntry" |
|||
type="QString" |
|||
default="translate me" |
|||
tr="true"/> |
|||
</Entry> |
|||
</Node> |
|||
|
|||
<Entry key="voidEntry" |
|||
type="void"/> |
|||
<Entry key="variantEntry" |
|||
type="QVariant"/> |
|||
<Entry key="simpleListEntry" |
|||
type="QList<int>"> |
|||
<Code>{42}</Code> |
|||
</Entry> |
|||
|
|||
<ListNode key="listNode"> |
|||
<Entry key="simpleChild" |
|||
type="bool"/> |
|||
<Node key="someNode"> |
|||
<Entry key="deepChild" |
|||
type="int" |
|||
default="22"/> |
|||
<Entry key="deepParent" |
|||
type="QString" |
|||
default="___"> |
|||
<Entry key="simpleChild" |
|||
type="bool" |
|||
default="true"/> |
|||
</Entry> |
|||
</Node> |
|||
<ListNode key="childList"> |
|||
<Entry key="valueEntry" |
|||
type="double" |
|||
default="4.2"/> |
|||
</ListNode> |
|||
</ListNode> |
|||
</Settings> |
|||
Loading…
Reference in new issue