From ec1b2a31bc5cefc20a048c83641a1c7f0cc49b1a Mon Sep 17 00:00:00 2001 From: Skycoder42 Date: Tue, 7 Aug 2018 17:59:57 +0200 Subject: [PATCH] update quick doc --- doc/inputviewfactory.dox | 94 +++++++++++++++++++ doc/message.dox | 12 ++- src/imports/mvvmdatasynccore/plugins.qmltypes | 4 +- src/mvvmquick/inputviewfactory.cpp | 1 + src/mvvmquick/inputviewfactory.h | 8 ++ src/mvvmquick/quickpresenter.h | 1 + 6 files changed, 113 insertions(+), 7 deletions(-) diff --git a/doc/inputviewfactory.dox b/doc/inputviewfactory.dox index 8f43ffb..8fe3dc0 100644 --- a/doc/inputviewfactory.dox +++ b/doc/inputviewfactory.dox @@ -64,6 +64,35 @@ delegate to set the property. InputViewFactory::addDelegateAlias, InputViewFactory::getInputUrl */ +/*! +@fn QtMvvm::InputViewFactory::format + +@param type The type to choose a formatter for +@param formatString Some kind of format string, depending on what the formatter wants here +@param value The actual value, packet as a variant +@param viewProperties Additional properies set on the delegate +@returns The formatted value text + +Internally, this method uses the Formatter registered for the given type and then returns +the result of Formatter::format, invoked with the remaining parameters. + +If no formatter was registered for the given type, this method simply returns +`formatString.arg(value.toString());` + +Currently, the following special formatters are set by default. + + types | formatString semantics +----------------------------|------------------------ + int | A translated string with either `%1`, `%L1` or `%n` as number placeholder. If `%n` is used, "plural-translations" are used + list, selection, radiolist | A translated string with `%1` as placeholder. If the list element is named, that one is used, otherwise the value itself + QDateTime, QDate, QTime | Can either be the integer value of one of Qt::DateFormat or a standard date format string (QDateTime::toString). If neither is the case, the date is formatted using Qt::DefaultLocaleShortDate + double | Uses the SimpleFormatter with double as template argument + +All other types use the fallback formatting. + +@sa Formatter::format, InputViewFactory::addFormatter, InputViewFactory::addFormatterAlias +*/ + /*! @fn QtMvvm::InputViewFactory::addSimpleInput(const QUrl &) @@ -112,6 +141,30 @@ used as a delegate for a ListView. @sa InputViewFactory::getDelegate, InputViewFactory::addDelegateAlias */ +/*! +@fn QtMvvm::InputViewFactory::addFormatter(Formatter*) + +@tparam TType The type to add a formatter for +@param formatter The formatter instance to be added + +The formatter must be valid and is registered in the factory. The factory takes ownership of +the passed formatter. From now on it is used to convert display texts when format() is called. + +@sa InputViewFactory::format, InputViewFactory::addFormatterAlias, Formatter +*/ + +/*! +@fn QtMvvm::InputViewFactory::addFormatter(const QByteArray &, Formatter*) + +@param type The type to add a formatter for +@param formatter The formatter instance to be added + +The formatter must be valid and is registered in the factory. The factory takes ownership of +the passed formatter. From now on it is used to convert display texts when format() is called. + +@sa InputViewFactory::format, InputViewFactory::addFormatterAlias, Formatter +*/ + /*! @fn QtMvvm::InputViewFactory::addInputAlias() @@ -157,3 +210,44 @@ instead. @sa InputViewFactory::getDelegate, InputViewFactory::addSimpleDelegate */ + +/*! +@fn QtMvvm::InputViewFactory::addFormatterAlias() + +@tparam TAliasType The type to add as a new alias +@tparam TTargetType The type the alias should be translated to + +If a formatter for the alias type is requested for the format() method, the one of the target +type is used instead. + +@sa InputViewFactory::format, InputViewFactory::addFormatter +*/ + +/*! +@fn QtMvvm::InputViewFactory::addFormatterAlias(const QByteArray &, const QByteArray &) + +@param alias The type to add as a new alias +@param targetType The type the alias should be translated to + +If a formatter for the alias type is requested for the format() method, the one of the target +type is used instead. + +@sa InputViewFactory::format, InputViewFactory::addFormatter +*/ + + + +/*! +@fn QtMvvm::Formatter::format + +@param formatString Some kind of format string, depending on what your formatter wants here +@param value The actual value, packet as a variant +@param viewProperties Additional properies set on the delegate +@return A localized, human readable text, the formatted the value based on formatString + +formatString can be whatever you need it to be, but typically it is a localized text with a +placeholder to be replaced with the given value. See InputViewFactory::format for known +formats. + +@sa InputViewFactory::format +*/ diff --git a/doc/message.dox b/doc/message.dox index b1541f5..84ff263 100644 --- a/doc/message.dox +++ b/doc/message.dox @@ -247,14 +247,16 @@ create edit views yourself Type | Widgets edit | Quick edit | Quick delegate ------------------------|-------------------------------|---------------|---------------- bool | QCheckBox | CheckBox | BoolDelegate - switch | -/- | Switch | SwitchDelegate + switch | QCheckBox | Switch | SwitchDelegate QString, string | QLineEdit | TextField | MsgDelegate (*) int | QSpinBox | SpinBox | MsgDelegate double, number | QDoubleSpinBox | DoubleSpinBox | MsgDelegate - QDate | QDateEdit | -/- | -/- - QTime | QTimeEdit | -/- | -/- - QDateTime, date | QDateTimeEdit | -/- | -/- - QFont | QFontComboBox | FontEdit | MsgDelegate + range (int) | QSlider | Slider | RangeDelegate + QDate | QDateEdit | DateEdit | MsgDelegate + QTime | QTimeEdit | TimeEdit | MsgDelegate + QDateTime, date | QDateTimeEdit | DateTimeEdit | MsgDelegate + QColor, color | ColorButton | ColorEdit | ColorDelegate + QFont, font | QFontComboBox | FontEdit | MsgDelegate QKeySequence | QKeySequenceEdit | -/- | -/- QUrl, url | QLineEdit with QUrlValidator | UrlField | MsgDelegate selection, list | QComboBox | ListEdit | ListDelegate diff --git a/src/imports/mvvmdatasynccore/plugins.qmltypes b/src/imports/mvvmdatasynccore/plugins.qmltypes index 26cac33..3325dfa 100644 --- a/src/imports/mvvmdatasynccore/plugins.qmltypes +++ b/src/imports/mvvmdatasynccore/plugins.qmltypes @@ -114,8 +114,8 @@ Module { exportMetaObjectRevisions: [0] Property { name: "key"; type: "string" } Property { name: "dataVersion"; type: "int" } - Property { name: "value"; type: "QByteArray" } - Property { name: "variantValue"; type: "QVariant" } + Property { name: "value"; type: "QVariant" } + Property { name: "valueData"; type: "QByteArray" } } Component { name: "QtMvvm::DataSyncSettingsViewModel" diff --git a/src/mvvmquick/inputviewfactory.cpp b/src/mvvmquick/inputviewfactory.cpp index b7b84c3..ec4ca3c 100644 --- a/src/mvvmquick/inputviewfactory.cpp +++ b/src/mvvmquick/inputviewfactory.cpp @@ -79,6 +79,7 @@ void InputViewFactory::addSimpleDelegate(const QByteArray &type, const QUrl &qml void InputViewFactory::addFormatter(const QByteArray &type, Formatter *formatter) { + Q_ASSERT_X(formatter, Q_FUNC_INFO, "formatter must not be null"); d->formatters.insert(type, QSharedPointer{formatter}); } diff --git a/src/mvvmquick/inputviewfactory.h b/src/mvvmquick/inputviewfactory.h index ff14c09..a2ff7ee 100644 --- a/src/mvvmquick/inputviewfactory.h +++ b/src/mvvmquick/inputviewfactory.h @@ -12,6 +12,7 @@ namespace QtMvvm { +//! A class to format the preview text in the delegates class Q_MVVMQUICK_EXPORT Formatter { Q_DISABLE_COPY(Formatter) @@ -20,11 +21,13 @@ public: Formatter(); virtual ~Formatter(); + //! Is called to format a value to a localized, human readable text virtual QString format(const QString &formatString, const QVariant &value, const QVariantMap &viewProperties) const = 0; }; +//! A very basic formatter that uses QString::arg with the value on the format string template class SimpleFormatter : public Formatter { @@ -50,6 +53,7 @@ public: //! Find the input list delegate URL of the given input type Q_INVOKABLE virtual QUrl getDelegate(const QByteArray &type, const QVariantMap &viewProperties); + //! Formats the value using the internally registered Formatter for the given type QTMVVM_REVISION_1 Q_INVOKABLE QString format(const QByteArray &type, const QString &formatString, const QVariant &value, @@ -67,8 +71,10 @@ public: //! @copybrief addSimpleDelegate(const QUrl &) Q_INVOKABLE virtual void addSimpleDelegate(const QByteArray &type, const QUrl &qmlFileUrl); + //! Adds a new Formatter to format delegate preview texts for the given type template inline void addFormatter(Formatter *formatter); + //! @copybrief addFormatter(Formatter*) void addFormatter(const QByteArray &type, Formatter *formatter); //MAJOR make virtual //! Adds a type name alias for views @@ -83,8 +89,10 @@ public: //! @copybrief addDelegateAlias() Q_INVOKABLE virtual void addDelegateAlias(const QByteArray &alias, const QByteArray &targetType); + //! Adds a type name alias for formatters template inline void addFormatterAlias(); + //! @copybrief addFormatterAlias() QTMVVM_REVISION_1 Q_INVOKABLE void addFormatterAlias(const QByteArray &alias, const QByteArray &targetType); private: diff --git a/src/mvvmquick/quickpresenter.h b/src/mvvmquick/quickpresenter.h index 6c6d7a5..e6a42da 100644 --- a/src/mvvmquick/quickpresenter.h +++ b/src/mvvmquick/quickpresenter.h @@ -42,6 +42,7 @@ public: //! @copybrief registerViewExplicitly() static void registerViewExplicitly(const QMetaObject *viewModelType, const QUrl &viewUrl); + //! Returns the internally used input view factory static InputViewFactory* getInputViewFactory(); void present(ViewModel *viewModel, const QVariantHash ¶ms, QPointer parent) override;