whytofly
/
qt6-bb10
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

QMetaType: Expand and clean up converter/view function documentation 

This adds a few snippets to show how the functions can be used, and also
removes workarounds for oldver versions of qdoc that weren't clang based
- those workarounds also seem to have caused some bitrot.

Remove documentation for an overload of registerMutableView that
currently does not exist (for a member function with an ok parameter).

Fixes: QTBUG-96963
Pick-to: 6.2
Change-Id: Ibc867d08bcacbc7add8c965df9864d6f339a5d54
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
bb10
Fabian Kosmale 2021-09-29 13:00:44 +02:00
parent 684c9b82b9
commit 4f897584ec
3 changed files with 118 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
src/corelib/doc/snippets/qmetatype/registerConverters.cpp Normal file
View File

@ -0,0 +1,101 @@
/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:BSD$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** BSD License Usage
** Alternatively, you may use this file under the terms of the BSD license
** as follows:
**
** "Redistribution and use in source and binary forms, with or without
** modification, are permitted provided that the following conditions are
** met:
** * Redistributions of source code must retain the above copyright
** notice, this list of conditions and the following disclaimer.
** * Redistributions in binary form must reproduce the above copyright
** notice, this list of conditions and the following disclaimer in
** the documentation and/or other materials provided with the
** distribution.
** * Neither the name of The Qt Company Ltd nor the names of its
** contributors may be used to endorse or promote products derived
** from this software without specific prior written permission.
**
**
** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
**
** $QT_END_LICENSE$
**
****************************************************************************/
#include <QMetaType>
#include <QString>
int main() {
//! [member]
struct Coordinates {
int x;
int y;
int z;
QString toString() const { return u"[x: %1; y: %2, z: %3]"_qs.arg(QString::number(x),
QString::number(y),
QString::number(z)); }
};
QMetaType::registerConverter<Coordinates, QString>(&Coordinates::toString);
//! [member]
//! [memberOk]
struct BigNumber {
long long l;
int toInt(bool *ok = nullptr) const {
const bool canConvertSafely = l < std::numeric_limits<int>::max();
if (ok)
*ok = canConvertSafely;
return l;
}
};
QMetaType::registerConverter<BigNumber, int>(&BigNumber::toInt);
//! [memberOk]
//! [implicit]
class Counter {
int number = 0;
public:
int value() const { return number; }
operator int() const { return value(); }
void increment() {++number;}
};
QMetaType::registerConverter<Counter, int>();
//! [implicit]
struct CustomStringType {
const char *data() const {return nullptr;}
};
//! [unaryfunc]
QMetaType::registerConverter<CustomStringType, QString>([](const CustomStringType &str) {
return QString::fromUtf8(str.data());
});
//! [unaryfunc]
}

31
src/corelib/kernel/qmetatype.cpp
View File

@ -1600,30 +1600,42 @@ Q_GLOBAL_STATIC(QMetaTypeMutableViewRegistry, customTypesMutableViewRegistry)
\since 5.2
Registers the possibility of an implicit conversion from type From to type To in the meta
type system. Returns \c true if the registration succeeded, otherwise false.
\snippet qmetatype/registerConverters.cpp [implicit]
*/
/*!
\fn template<typename MemberFunction, int> bool QMetaType::registerConverter(MemberFunction function)
\fn template<typename From, typename To> static bool registerConverter(To(From::*function)() const)
\since 5.2
\overload
Registers a method \a function like To From::function() const as converter from type From
to type To in the meta type system. Returns \c true if the registration succeeded, otherwise false.
\snippet qmetatype/registerConverters.cpp [member]
*/
/*!
\fn template<typename MemberFunctionOk, char> bool QMetaType::registerConverter(MemberFunctionOk function)
\fn template<typename From, typename To> static bool registerConverter(To(From::*function)(bool*) const)
\since 5.2
\overload
Registers a method \a function like To From::function(bool *ok) const as converter from type From
to type To in the meta type system. Returns \c true if the registration succeeded, otherwise false.
The \a ok pointer can be used by the function to indicate whether the conversion succceeded.
\snippet qmetatype/registerConverters.cpp [memberOk]
*/
/*!
\fn template<typename UnaryFunction> bool QMetaType::registerConverter(UnaryFunction function)
\fn template<typename From, typename To, typename UnaryFunction> static bool registerConverter(UnaryFunction function)
\since 5.2
\overload
Registers a unary function object \a function as converter from type From
to type To in the meta type system. Returns \c true if the registration succeeded, otherwise false.
\a function must take an instance of type \a From and return an instance of \a To. It can be a function
pointer, a lambda or a functor object.
\snippet qmetatype/registerConverters.cpp [unaryfunc]
*/
/*!
@ -1644,7 +1656,7 @@ bool QMetaType::registerConverterFunction(const ConverterFunction &f, QMetaType
}
/*!
\fn template<typename MemberFunction, int> bool QMetaType::registerMutableView(MemberFunction function)
\fn template<typename From, typename To> static bool registerMutableView(To(From::*function)())
\since 6.0
\overload
Registers a method \a function like \c {To From::function()} as mutable view of type \c {To} on
@ -1653,16 +1665,7 @@ bool QMetaType::registerConverterFunction(const ConverterFunction &f, QMetaType
*/
/*!
\fn template<typename MemberFunctionOk, char> bool QMetaType::registerMutableView(MemberFunctionOk function)
\since 6.0
\overload
Registers a method \a function like To From::function(bool *ok) as mutable view of type To on
type From in the meta type system. Returns \c true if the registration succeeded, otherwise
\c false.
*/
/*!
\fn template<typename UnaryFunction> bool QMetaType::registerMutableView(UnaryFunction function)
\fn template<typename From, typename To, typename UnaryFunction> static bool registerMutableView(UnaryFunction function)
\since 6.0
\overload
Registers a unary function object \a function as mutable view of type To on type From

16
src/corelib/kernel/qmetatype.h
View File

@ -541,21 +541,6 @@ public:
return registerConverter<From, To>(QtPrivate::convertImplicit<From, To>);
}
#ifdef Q_CLANG_QDOC
template<typename MemberFunction, int>
static bool registerConverter(MemberFunction function);
template<typename MemberFunctionOk, char>
static bool registerConverter(MemberFunctionOk function);
template<typename UnaryFunction>
static bool registerConverter(UnaryFunction function);
template<typename MemberFunction, int>
static bool registerMutableView(MemberFunction function);
template<typename MemberFunctionOk, char>
static bool registerMutableView(MemberFunctionOk function);
template<typename UnaryFunction>
static bool registerMutableView(UnaryFunction function);
#else
// member function as in "QString QFont::toString() const"
template<typename From, typename To>
static bool registerConverter(To(From::*function)() const)
@ -675,7 +660,6 @@ private:
return false;
}
}
#endif // Q_CLANG_DOC
public:
static bool convert(QMetaType fromType, const void *from, QMetaType toType, void *to);