From 4eb589fc5fd80e9b967e2e1537106df39022c059 Mon Sep 17 00:00:00 2001 From: Skycoder42 Date: Tue, 7 Aug 2018 17:26:18 +0200 Subject: [PATCH] updated datasync core doc --- doc/datasyncsettingsentry.dox | 72 ++++++++++++++++++ doc/datasyncsettingsviewmodel.dox | 76 +++++++++++++++++++ doc/makedoc.sh | 3 + doc/networkexchangeviewmodel.dox | 2 +- src/mvvmcore/qsettingsaccessor.h | 2 +- src/mvvmcore/settingsviewmodel.h | 2 +- .../datasyncsettingsaccessor.cpp | 1 + .../datasyncsettingsaccessor.h | 6 ++ src/mvvmdatasynccore/datasyncsettingsentry.h | 22 +++++- .../datasyncsettingsviewmodel.h | 8 ++ 10 files changed, 189 insertions(+), 5 deletions(-) create mode 100644 doc/datasyncsettingsentry.dox create mode 100644 doc/datasyncsettingsviewmodel.dox diff --git a/doc/datasyncsettingsentry.dox b/doc/datasyncsettingsentry.dox new file mode 100644 index 0000000..40f4a85 --- /dev/null +++ b/doc/datasyncsettingsentry.dox @@ -0,0 +1,72 @@ +/*! +@class QtMvvm::DataSyncSettingsAccessor + +The data is stored by using the DataSyncSettingsEntry class to wrap the key value pairs into a +serializable datatype. + +@sa DataSyncSettingsEntry +*/ + + + +/*! +@class QtMvvm::DataSyncSettingsEntry + +In order to be consistend with other settings implementations and the requirements of +ISettingsAccessor, the actual value stored in this class is serialized not via the json +serializer, but using QDataStream. The resulting binary data is stored as the +valueData property in base64 format. When loaded, you can access the data +in the QVariant format using the DataSyncSettingsEntry::value property. + +@sa DataSyncSettingsAccessor +*/ + +/*! +@property QtMvvm::DataSyncSettingsEntry::key + +@default{empty} + +The key is simply the settings key used to identify the entry. Thus, it is set as the user +property. + +@accessors{ + @readAc{key()} + @writeAc{setKey()} + @userAc{`true`} +} + +@sa DataSyncSettingsEntry::variantValue +*/ + +/*! +@property QtMvvm::DataSyncSettingsEntry::dataVersion + +@default{`QDataStream::Qt_DefaultCompiledVersion`} + +The version is needed to identify the format used for the serialization to be able to +properly deserialize the data again. It is used internally to set up the internal QDataStream + +@accessors{ + @readAc{dataVersion()} + @writeAc{setDataVersion()} +} + +@sa DataSyncSettingsEntry::value +*/ + +/*! +@property QtMvvm::DataSyncSettingsEntry::value + +@default{invalid} + +The data of the entry. This property does not get stored directly, but instead gets serialized +to a QByteArray and then stored via the internal valueData property. + +@accessors{ + @readAc{value()} + @writeAc{setValue()} + @storedAc{`false`} +} + +@sa DataSyncSettingsEntry::valueData +*/ diff --git a/doc/datasyncsettingsviewmodel.dox b/doc/datasyncsettingsviewmodel.dox new file mode 100644 index 0000000..7c9ebfb --- /dev/null +++ b/doc/datasyncsettingsviewmodel.dox @@ -0,0 +1,76 @@ +/*! +@var QtMvvm::DataSyncSettingsViewModel::paramSetup + +Value: `"setup"` + +@sa DataSyncSettingsViewModel::showParams +*/ + +/*! +@var QtMvvm::DataSyncSettingsViewModel::paramDataStore + +Value: `"dataStore"` + +@sa DataSyncSettingsViewModel::showParams +*/ + +/*! +@var QtMvvm::DataSyncSettingsViewModel::paramDataTypeStore + +Value: `"dataTypeStore"` + +@sa DataSyncSettingsViewModel::showParams +*/ + +/*! +@fn QtMvvm::DataSyncSettingsViewModel::showParams(const QString &, const QString &) + +@param setup The name of the QtDataSync::Setup to be passed to the internally used +DataSyncSettingsAccessor +@param setupFile The path to a file to be used to create the settings. Can be empty to use the +default path +@return A paramater hash to be passed to ViewModel::show + +It's a shortcut to generate parameters for the show methods to show a settings viewmodel. + +@note Unless you need to explicitly set the settings or setup file a normal show without any +parameters will just do fine. + +@sa ViewModel::show, DataSyncSettingsViewModel::paramSetup, SettingsViewModel::paramSetupFile, +DataSyncSettingsAccessor +*/ + +/*! +@fn QtMvvm::DataSyncSettingsViewModel::showParams(QtDataSync::DataStore*, const QString &) + +@param dataStore The store to be passed to the internally used DataSyncSettingsAccessor +@param setupFile The path to a file to be used to create the settings. Can be empty to use the +default path +@return A paramater hash to be passed to ViewModel::show + +It's a shortcut to generate parameters for the show methods to show a settings viewmodel. + +@note Unless you need to explicitly set the settings or setup file a normal show without any +parameters will just do fine. + +@sa ViewModel::show, DataSyncSettingsViewModel::paramDataStore, +SettingsViewModel::paramSetupFile, DataSyncSettingsAccessor +*/ + +/*! +@fn QtMvvm::DataSyncSettingsViewModel::showParams(QtDataSync::DataTypeStore*, const QString &) + +@param dataStore The store to be passed to the internally used DataSyncSettingsAccessor +@param setupFile The path to a file to be used to create the settings. Can be empty to use the +default path +@return A paramater hash to be passed to ViewModel::show + +It's a shortcut to generate parameters for the show methods to show a settings viewmodel. + +@note Unless you need to explicitly set the settings or setup file a normal show without any +parameters will just do fine. + +@sa ViewModel::show, DataSyncSettingsViewModel::paramDataTypeStore, +SettingsViewModel::paramSetupFile, DataSyncSettingsAccessor +*/ + diff --git a/doc/makedoc.sh b/doc/makedoc.sh index 07b92fa..1ea6141 100755 --- a/doc/makedoc.sh +++ b/doc/makedoc.sh @@ -48,6 +48,9 @@ for tagFile in $(find "$qtDocs" -name *.tags); do qtdatasync.tags) echo "TAGFILES += \"$tagFile=https://skycoder42.github.io/QtDataSync\"" >> $doxyRes ;; + qtservice.tags) + echo "TAGFILES += \"$tagFile=https://skycoder42.github.io/QtService\"" >> $doxyRes + ;; qtmvvm.tags|qtquickcontrols.tags) # skipped ;; diff --git a/doc/networkexchangeviewmodel.dox b/doc/networkexchangeviewmodel.dox index 51eeba2..9b965e9 100644 --- a/doc/networkexchangeviewmodel.dox +++ b/doc/networkexchangeviewmodel.dox @@ -63,7 +63,7 @@ Changing this property will trigger start and stop actions on the underlying man the other information provided from this viewmodel. @accessors{ - @readAc{active()} + @readAc{isActive()} @writeAc{setActive()} @notifyAc{activeChanged()} } diff --git a/src/mvvmcore/qsettingsaccessor.h b/src/mvvmcore/qsettingsaccessor.h index 4161f36..2535ec8 100644 --- a/src/mvvmcore/qsettingsaccessor.h +++ b/src/mvvmcore/qsettingsaccessor.h @@ -17,7 +17,7 @@ class Q_MVVMCORE_EXPORT QSettingsAccessor : public ISettingsAccessor Q_INTERFACES(QtMvvm::ISettingsAccessor) public: - //! Constructor + //! Default Constructor Q_INVOKABLE explicit QSettingsAccessor(QObject *parent = nullptr); //! Constructor, with settings to be used (takes ownership of the settings) explicit QSettingsAccessor(QSettings *settings, QObject *parent = nullptr); diff --git a/src/mvvmcore/settingsviewmodel.h b/src/mvvmcore/settingsviewmodel.h index 88886b6..04385bc 100644 --- a/src/mvvmcore/settingsviewmodel.h +++ b/src/mvvmcore/settingsviewmodel.h @@ -41,7 +41,7 @@ public: //! Generates show parameter to show a settings viewmodel via ViewModel::show static QVariantHash showParams(ISettingsAccessor *accessor, const QString &setupFile = {}); - //! @copydetails SettingsViewModel::showParams(ISettingsAccessor*, const QString &) + //! @copybrief SettingsViewModel::showParams(ISettingsAccessor*, const QString &) static QVariantHash showParams(QSettings *settings, const QString &setupFile = {}); //! Invokable constructor diff --git a/src/mvvmdatasynccore/datasyncsettingsaccessor.cpp b/src/mvvmdatasynccore/datasyncsettingsaccessor.cpp index 089be1a..f829d0b 100644 --- a/src/mvvmdatasynccore/datasyncsettingsaccessor.cpp +++ b/src/mvvmdatasynccore/datasyncsettingsaccessor.cpp @@ -90,6 +90,7 @@ void DataSyncSettingsAccessor::remove(const QString &key) void DataSyncSettingsAccessor::sync() { // nothing needs to be done + //TODO implement via manager sync with blocking eventloop? } void DataSyncSettingsAccessor::dataChanged(const QString &key, const QVariant &value) diff --git a/src/mvvmdatasynccore/datasyncsettingsaccessor.h b/src/mvvmdatasynccore/datasyncsettingsaccessor.h index 6fa0912..a0a17d8 100644 --- a/src/mvvmdatasynccore/datasyncsettingsaccessor.h +++ b/src/mvvmdatasynccore/datasyncsettingsaccessor.h @@ -11,15 +11,20 @@ namespace QtMvvm { class DataSyncSettingsAccessorPrivate; +//! A settings accessor implementation that allows to store and sync settings via datasync class Q_MVVMDATASYNCCORE_EXPORT DataSyncSettingsAccessor : public ISettingsAccessor { Q_OBJECT Q_INTERFACES(QtMvvm::ISettingsAccessor) public: + //! Default Constructor Q_INVOKABLE explicit DataSyncSettingsAccessor(QObject *parent = nullptr); + //! Constructor, with the name of the datasync setup to use explicit DataSyncSettingsAccessor(const QString &setupName, QObject *parent = nullptr); + //! Constructor, with the store to use for access. Does not take ownership explicit DataSyncSettingsAccessor(QtDataSync::DataStore *store, QObject *parent = nullptr); + //! Constructor, with the store to use for access. Does not take ownership explicit DataSyncSettingsAccessor(QtDataSync::DataTypeStore *store, QObject *parent = nullptr); ~DataSyncSettingsAccessor() override; @@ -29,6 +34,7 @@ public: void remove(const QString &key) override; public Q_SLOTS: + //! @copydoc ISettingsAccessor::sync void sync() override; private Q_SLOTS: diff --git a/src/mvvmdatasynccore/datasyncsettingsentry.h b/src/mvvmdatasynccore/datasyncsettingsentry.h index 1ef55ef..fd553cc 100644 --- a/src/mvvmdatasynccore/datasyncsettingsentry.h +++ b/src/mvvmdatasynccore/datasyncsettingsentry.h @@ -10,37 +10,55 @@ namespace QtMvvm { class DataSyncSettingsEntryData; +//! A class used with the DataSyncSettingsAccessor to store and sync generic settings struct Q_MVVMDATASYNCCORE_EXPORT DataSyncSettingsEntry { Q_GADGET + //! They key of the entry stored Q_PROPERTY(QString key READ key WRITE setKey USER true) + //! The QDataStream::Version that was used to serialize the entry Q_PROPERTY(int dataVersion READ dataVersion WRITE setDataVersion) - Q_PROPERTY(QByteArray value READ valueData WRITE setValueData) + //! The raw (deserialized) value stored + Q_PROPERTY(QVariant value READ value WRITE setValue STORED false) - Q_PROPERTY(QVariant variantValue READ value WRITE setValue STORED false) + //! @private Internal property + Q_PROPERTY(QByteArray valueData READ valueData WRITE setValueData) public: DataSyncSettingsEntry(); ~DataSyncSettingsEntry(); + //! Copy constructor DataSyncSettingsEntry(const DataSyncSettingsEntry &other); + //! Move constructor DataSyncSettingsEntry(DataSyncSettingsEntry &&other) noexcept; + //! Copy assignment operator DataSyncSettingsEntry &operator=(const DataSyncSettingsEntry &other); + //! Move assignment operator DataSyncSettingsEntry &operator=(DataSyncSettingsEntry &&other) noexcept; + //! Constructor, takes a key and value DataSyncSettingsEntry(QString key, QVariant value); + //! @copybrief DataSyncSettingsEntry::DataSyncSettingsEntry(QString, QVariant) template DataSyncSettingsEntry(QString key, const T &value); + //! @readAcFn{key} QString key() const; + //! @readAcFn{dataVersion} int dataVersion() const; + //! @readAcFn{variantValue} QVariant value() const; + //! @readAcFn{variantValue} template T value() const; + //! @writeAcFn{key} void setKey(QString key); + //! @writeAcFn{dataVersion} void setDataVersion(int dataVersion); + //! @writeAcFn{variantValue} void setValue(QVariant value); private: diff --git a/src/mvvmdatasynccore/datasyncsettingsviewmodel.h b/src/mvvmdatasynccore/datasyncsettingsviewmodel.h index ff042a3..b7344eb 100644 --- a/src/mvvmdatasynccore/datasyncsettingsviewmodel.h +++ b/src/mvvmdatasynccore/datasyncsettingsviewmodel.h @@ -13,19 +13,27 @@ namespace QtMvvm { +//! An extension of the normal settings viewmodel with the DataSyncSettingsAccessor as accessor class Q_MVVMDATASYNCCORE_EXPORT DataSyncSettingsViewModel : public QtMvvm::SettingsViewModel { Q_OBJECT public: + //! The parameter for a setup name for the onInit() method static const QString paramSetup; + //! The parameter for a QtDataSync::DataStore object for the onInit() method static const QString paramDataStore; + //! The parameter for a QtDataSync::DataTypeStore object for the onInit() method static const QString paramDataTypeStore; + //! @copybrief SettingsViewModel::showParams(ISettingsAccessor*, const QString &) static QVariantHash showParams(const QString &setup, const QString &setupFile = {}); + //! @copybrief SettingsViewModel::showParams(ISettingsAccessor*, const QString &) static QVariantHash showParams(QtDataSync::DataStore *dataStore, const QString &setupFile = {}); + //! @copybrief SettingsViewModel::showParams(ISettingsAccessor*, const QString &) static QVariantHash showParams(QtDataSync::DataTypeStore *dataStore, const QString &setupFile = {}); + //! Invokable constructor Q_INVOKABLE explicit DataSyncSettingsViewModel(QObject *parent = nullptr); protected: