QMetaType Class

成员函数文档

[constexpr noexcept default, since 6.0] QMetaType::QMetaType()

构建一个默认的、无效的 QMetaType 对象。

该函数在 Qt 6.0 中引入。

[explicit] QMetaType::QMetaType(int typeId)

构建一个 QMetaType 对象，其中包含有关类型typeId 的所有信息。

[constexpr, since 6.0] qsizetype QMetaType::alignOf() const

返回该类型的对齐长度（以字节为单位）（即 alignof(T)，其中 T 是该QMetaType 实例所构建的实际类型）。

该函数通常与 `construct()` 配合使用，以对类型所占用的内存进行低级管理。

该函数在 Qt 6.0 中引入。

另请参阅 QMetaType::construct() 和QMetaType::sizeOf()。

[static] bool QMetaType::canConvert(QMetaType fromType, QMetaType toType)

如果 `QMetaType::convert ` 能够将 `fromType ` 转换为 `toType`，则返回 `true `。请注意，这主要涉及执行转换的能力，而实际转换在尝试时可能会失败（例如，将浮点数转换为超出其范围的整数）。

可以使用registerConverter() 函数来注册额外的转换，无论是内置类型与非内置类型之间的转换，还是两个非内置类型之间的转换。如果转换路径已注册，该函数将返回true 。

Qt 支持以下转换：

其他支持的转换包括所有基本类型（int 、float 、bool 等，包括所有枚举）之间的转换，以及任何指针类型与std::nullptr_t 之间的转换。枚举类型还可以转换为QString 和QByteArray 。

如果fromType 和toType 都是从QObject 派生的类型（或指向它们的指针），且其中一种类型是从另一种类型派生而来，则该函数也会返回true 。也就是说，如果从fromType 描述的类型到toType 描述的类型的static_cast<> 能够编译通过，则该函数返回 true。convert() 函数的工作原理与qobject_cast() 类似，用于验证QVariant 所指向的对象的动态类型。

如果toType 为QVariantList ，则从顺序容器进行的类型转换对该函数也会返回 true。

同样，如果toType 为QVariantHash 或QVariantMap ，则从关联容器进行类型转换时，该函数也会返回 true。

另请参阅 convert()、QMetaSequence::Iterable 、Q_DECLARE_SEQUENTIAL_CONTAINER_METATYPE()、QMetaAssociation::Iterable 以及Q_DECLARE_ASSOCIATIVE_CONTAINER_METATYPE()。

[static] bool QMetaType::canView(QMetaType fromType, QMetaType toType)

如果 `QMetaType::view ` 能够针对类型 `fromType` 创建类型 `toType ` 的可变视图，则返回 `true `。

如果从qobject_cast 传入的类型（由fromType 描述）到toType 描述的类型之间的转换能够成功，则该函数在QObject 派生类型的指针之间进行转换时将返回 true。

您可以在任何已通过Q_DECLARE_SEQUENTIAL_CONTAINER_METATYPE() 注册的容器上创建类型为QMetaSequence::Iterable 的可变视图。

同样，您可以在任何已通过Q_DECLARE_ASSOCIATIVE_CONTAINER_METATYPE() 注册的容器上创建类型为QMetaAssociation::Iterable 的可变视图。

另请参阅 convert()、QMetaSequence::Iterable 、Q_DECLARE_SEQUENTIAL_CONTAINER_METATYPE()、QMetaAssociation::Iterable 以及Q_DECLARE_ASSOCIATIVE_CONTAINER_METATYPE()。

[since 6.0] QPartialOrdering QMetaType::compare(const void *lhs, const void *rhs) const

比较位于lhs 和rhs 处的对象以确定排序顺序。

如果不支持比较，或者值无序，则返回QPartialOrdering::Unordered 。否则，如果lhs 分别小于、等于或大于rhs ，则分别返回QPartialOrdering::Less 、QPartialOrdering::Equivalent 或QPartialOrdering::Greater 。

两个对象必须均为该元类型所描述的类型。若lhs 或rhs 的值为nullptr ，则这些值无序。仅当该类型的“小于”运算符在元类型声明中可见时，才支持比较操作。

如果该类型的相等运算符同样可见，则只有当相等运算符判定两个值相等时，它们才被视为相等。 在没有等号运算符的情况下，当两个值均不小于对方时，它们被视为相等；如果等号运算符可用，且这两个值不相等，则它们被视为无序，正如浮点类型的 NaN（非数值）值位于其排序范围之外一样。

该函数在 Qt 6.0 中引入。

另请参阅 equals() 和isOrdered()。

void *QMetaType::construct(void *where, const void *copy = nullptr) const

在由where 指定的现有内存中，构建一个与该QMetaType 实例所针对的类型相符的值（即copy 的副本），并返回where 。如果copy 为零，则对该值进行默认构造。

这是一个用于显式管理该类型存储内存的底层函数。如果您不需要此级别的控制，请考虑调用create()（即使用“new”而非“placement new”）。

您必须确保where 指向可存储新值的位置，并且where 已正确对齐。可通过调用sizeOf() 查询该类型的大小。

对齐的经验法则是：类型应对其自然边界进行对齐，即大于该类型的最小 2 的幂，除非该对齐值大于该平台上的最大有效对齐值。 从实际应用角度来看，只有在涉及特殊硬件指令时（例如 x86 架构上对齐的 SSE 加载和存储指令），才需要大于 2 * sizeof(void*) 的对齐度。

[static] bool QMetaType::convert(QMetaType fromType, const void *from, QMetaType toType, void *to)

将位于from 的对象从fromType 转换为位于to 的预分配空间，类型为toType 。如果转换成功，则返回true ；否则返回 false。

from 和to 都必须是有效的指针。

void *QMetaType::create(const void *copy = nullptr) const

返回copy 的副本，前提是该 的类型与该QMetaType 实例的创建类型一致。如果copy 为nullptr ，则创建一个通过默认构造函数生成的实例。

另请参阅 QMetaType::destroy()。

bool QMetaType::debugStream(QDebug &dbg, const void *rhs)

将位于rhs 的对象流式传输到调试流dbg 。成功时返回true ，否则返回 false。

void QMetaType::destroy(void *data) const

销毁data ，前提是该对象属于此QMetaType 实例所针对的类型。

另请参阅 QMetaType::create()。

void QMetaType::destruct(void *data) const

销毁位于 `data` 处的值，并假设该值的类型与该 `QMetaType ` 实例的构造类型一致。

与destroy() 不同，此函数仅调用该类型的析构函数，而不调用 delete 运算符。

另请参阅 QMetaType::construct()。

[since 6.0] bool QMetaType::equals(const void *lhs, const void *rhs) const

比较位于lhs 和rhs 处的对象是否相等。

这两个对象必须属于此元类型所描述的类型。只有当该类型的“小于”或“等于”运算符在元类型声明中可见时，才能对这两个对象进行比较。否则，元类型绝不会将这两个值视为相等。 当等值运算符对元类型声明可见时，该运算符具有权威性；否则，如果小于运算符可见，且两个值均未小于对方，则视为相等。如果值是无序的（详情参见compare()），则它们不被视为相等。

如果两个对象比较结果相等，则返回 true；否则返回 false。

该函数在 Qt 6.0 中引入。

另请参阅 isEqualityComparable() 和compare()。

[constexpr] QMetaType::TypeFlags QMetaType::flags() const

返回该QMetaType 实例所基于的类型的标志。若要检查特定的类型特征，建议使用“is-”函数之一，而非直接使用这些标志。

另请参阅 QMetaType::TypeFlags 、isDefaultConstructible()、isCopyConstructible()、isMoveConstructible()、isDestructible()、isEqualityComparable() 以及isOrdered()。

[static] QMetaType QMetaType::fromName(QByteArrayView typeName)

返回一个与typeName 匹配的QMetaType 。如果typeName未被QMetaType

[static constexpr] template <typename T> QMetaType QMetaType::fromType()

返回与模板参数中指定的类型对应的QMetaType 。

[static] bool QMetaType::hasRegisteredConverterFunction(QMetaType fromType, QMetaType toType)

true如果元类型系统中已注册了从元类型 IDfromType 到toType

[static] template <typename From, typename To> bool QMetaType::hasRegisteredConverterFunction()

如果元类型系统中已注册了从类型 From 到类型 To 的转换，则返回true 。

[since 6.1] bool QMetaType::hasRegisteredDataStreamOperators() const

如果元类型系统已为此元类型注册了数据流运算符，则返回true 。

该函数于 Qt 6.1 版本中引入。

[since 6.0] bool QMetaType::hasRegisteredDebugStreamOperator() const

如果元类型系统为此元类型注册了调试流运算符，则返回true 。

该函数在 Qt 6.0 中引入。

[static] bool QMetaType::hasRegisteredMutableViewFunction(QMetaType fromType, QMetaType toType)

如果元类型系统在元类型 IDfromType 上注册了元类型 IDtoType 的可变视图，则返回true 。

[static, since 6.0] template <typename From, typename To> bool QMetaType::hasRegisteredMutableViewFunction()

如果元类型系统在类型 To 上注册了类型 From 的可变视图，则返回true 。

该函数在 Qt 6.0 中引入。

int QMetaType::id() const

返回此QMetaType 实例持有的id类型。

[noexcept, since 6.5] bool QMetaType::isCopyConstructible() const

如果该类型支持复制构造，则返回 true。如果支持，则construct() 和create() 函数可与非空的copy 参数一起使用。

该函数在 Qt 6.5 中引入。

另请参阅 flags()、isDefaultConstructible()、isMoveConstructible() 和isDestructible()。

[noexcept, since 6.5] bool QMetaType::isDefaultConstructible() const

如果该类型可以进行默认构造，则返回 true。如果可以，那么在调用 `construct()` 和 `create()` 时，可以将 `copy ` 参数设为 null。

该函数在 Qt 6.5 中引入。

另请参阅 flags()、isCopyConstructible()、isMoveConstructible() 和isDestructible()。

[noexcept, since 6.5] bool QMetaType::isDestructible() const

如果该类型可以被销毁，则返回 true。如果可以，则可以调用destroy() 和destruct()。

该函数在 Qt 6.5 中引入。

另请参阅 flags()、isDefaultConstructible()、isCopyConstructible() 和isMoveConstructible()。

bool QMetaType::isEqualityComparable() const

如果该元类型所描述的类型具有小于或等于运算符，且该运算符在元类型声明中是可见的，则返回true ；否则返回false 。

另请参阅 equals() 和isOrdered()。

[noexcept, since 6.5] bool QMetaType::isMoveConstructible() const

如果该类型支持移动构造，则返回 true。QMetaType 目前尚无利用此特性的 API。

该函数于 Qt 6.5 中引入。

另请参阅 flags()、isDefaultConstructible()、isCopyConstructible() 以及isDestructible()。

bool QMetaType::isOrdered() const

如果该元类型所描述的类型具有小于运算符，且该运算符在元类型声明中是可见的，则返回true ；否则返回false 。

另请参阅 compare() 和isEqualityComparable()。

[noexcept] bool QMetaType::isRegistered() const

如果该QMetaType 对象已在 Qt 全局元类型注册表中注册，则返回true 。注册后，可通过名称（使用QMetaType::fromName()) 或 ID（使用构造函数）查找该类型。

另请参阅 qRegisterMetaType() 和isValid()。

[static] bool QMetaType::isRegistered(int type)

如果 ID 为type 的数据类型已注册，则返回true ；否则返回false 。

另请参见 type() 和Type 。

[constexpr noexcept] bool QMetaType::isValid() const

如果该QMetaType 对象包含有关某类型的有效信息，则返回true ；否则返回 false。

另请参阅 isRegistered()。

bool QMetaType::load(QDataStream &stream, void *data) const

从给定的stream 中读取此类型的对象，并将其读入data 。如果对象加载成功，则返回true ；否则返回false 。

通常情况下，您无需直接调用此函数。建议使用QVariant 的operator>>() 方法，该方法依赖于load()来加载自定义类型。

另请参阅 save()。

[constexpr] const QMetaObject *QMetaType::metaObject() const

返回一个相对于此类型的QMetaObject 。

如果该类型是QObject 子类的指针类型，则flags()包含QMetaType::PointerToQObject ，且本函数返回相应的QMetaObject 。这可与QMetaObject::newInstance()结合使用，以创建该类型的QObject。

如果类型是Q_GADGET ，则flags()包含QMetaType::IsGadget 。如果类型是Q_GADGET 的指针，则flags()包含QMetaType::PointerToGadget 。在这两种情况下，该函数均返回其QMetaObject 。这可用于检索QMetaMethod 和QMetaProperty ，并将其应用于该类型的指针上，例如由QVariant::data()返回的指针。

如果类型是一个枚举，则flags() 包含QMetaType::IsEnumeration 。在这种情况下，如果该枚举已注册为Q_ENUM ，则该函数返回外围对象的QMetaObject ；否则返回nullptr 。

另请参阅 QMetaType::flags()。

[constexpr] const char *QMetaType::name() const

返回与该QMetaType 关联的类型名称；如果未找到匹配的类型，则返回空指针。返回的指针不得被删除。

另请参阅 typeName()。

[static] template <typename From, typename To> bool QMetaType::registerConverter()

在元类型系统中注册从类型 From 到类型 To 的隐式转换可能性。如果注册成功，则返回true ；否则返回 false。

class Counter {
  int number = 0;
public:
  int value() const { return number; }
  operator int() const { return value(); }
  void increment() {++number;}
};
QMetaType::registerConverter<Counter, int>();

[static] template <typename From, typename To> bool QMetaType::registerConverter(To (From::*function)() const)

在元类型系统中，将方法function （形式为To From::function() const）注册为从类型From到类型To的转换器。如果注册成功，则返回true ；否则返回false。

struct Coordinates {
  int x;
  int y;
  int z;

  QString toString() const { return u"[x: %1; y: %2, z: %3]"_s.arg(QString::number(x),
    QString::number(y),
    QString::number(z)); }
};
QMetaType::registerConverter<Coordinates, QString>(&Coordinates::toString);

[static] template <typename From, typename To> bool QMetaType::registerConverter(To (From::*function)(bool *) const)

在元类型系统中将方法function （如 To From::function(bool *ok) const）注册为从类型 From 到类型 To 的转换器。如果注册成功，则返回true ；否则返回 false。

该函数可使用 `ok ` 指针来指示转换是否成功。

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);

[static] template < typename From, typename To, typename UnaryFunction > bool QMetaType::registerConverter(UnaryFunction function)

在元类型系统中将一元函数对象 `function ` 注册为从类型 `From` 到类型 `To` 的转换器。如果注册成功，则返回 `true `；否则返回 `false`。

function 该函数必须接受类型From 的实例，并返回类型To 的实例。它可以是函数指针、lambda 表达式或函子对象。自 Qt 6.5 起，function 还可以返回类型std::optional<To> 的实例，以便指示转换失败的情况。

QMetaType::registerConverter<CustomStringType, QString>([](const CustomStringType &str) {
    return QString::fromUtf8(str.data());
});
QMetaType::registerConverter<QJsonValue, CustomPointType>(
          [](const QJsonValue &value) -> std::optional<CustomPointType> {
    const auto object = value.toObject();
    if (!object.contains("x") || !object.contains("y"))
        return std::nullopt;  // The conversion fails if the required properties are missing
    return CustomPointType{object["x"].toDouble(), object["y"].toDouble()};
});

[static, since 6.0] template <typename From, typename To> bool QMetaType::registerMutableView(To (From::*function)())

在元类型系统中，将方法function （如To From::function() 所示）注册为类型From 上类型To 的可变视图。如果注册成功，则返回true ；否则返回false 。

该函数在 Qt 6.0 中引入。

[static, since 6.0] template < typename From, typename To, typename UnaryFunction > bool QMetaType::registerMutableView(UnaryFunction function)

在元类型系统中，将一元函数对象function 注册为类型From上类型To的可变视图。如果注册成功，则返回true ；否则返回false 。

该函数于 Qt 6.0 中引入。

[since 6.5] void QMetaType::registerType() const

将此QMetaType 注册到类型注册表中，以便可以通过名称查找它，使用QMetaType::fromName()。

该函数在 Qt 6.5 中引入。

另请参阅 qRegisterMetaType()。

bool QMetaType::save(QDataStream &stream, const void *data) const

将data 所指向的对象写入指定的stream 。如果对象保存成功，则返回true ；否则返回false 。

通常情况下，您无需直接调用此函数。建议使用QVariant 的operator<<() 方法，该方法依赖于 save() 来流式传输自定义类型。

另请参阅 load()。

[constexpr] qsizetype QMetaType::sizeOf() const

返回该类型的字节大小（即 sizeof(T)，其中 T 是该QMetaType 实例所构造的实际类型）。

该函数通常与 `construct()` 配合使用，以对类型所占用的内存进行低级管理。

另请参阅 QMetaType::construct() 和QMetaType::alignOf()。

[since 6.6] QMetaType QMetaType::underlyingType() const

如果该元类型表示一个枚举，则该方法返回一个数值类的元类型，其符号性和大小与该枚举的底层类型相同。如果它表示一个QFlags 类型，则返回QMetaType::Int 。在所有其他情况下，将返回一个无效的QMetaType 。

该函数在 Qt 6.6 中引入。

[static, since 6.0] bool QMetaType::view(QMetaType fromType, void *from, QMetaType toType, void *to)

在预分配空间to （类型为toType ）中，针对位于from 的对象fromType 创建一个可变视图。如果转换成功，则返回true ，否则返回 false。

该函数自 Qt 6.0 起引入。