Contents

• Public Types
• Public Functions
• Static Public Members
• Related Non-Members
• Detailed Description
• A Note on GUI Types
• Using canConvert() and convert() Consecutively

Detailed Description

TheQVariant class acts like a union for the most common Qt data types.

Because C++ forbids unions from including types that have non-default constructors or destructors, most interesting Qt classes cannot be used in unions. WithoutQVariant, this would be a problem forQObject::property() and for database work, etc.

AQVariant object holds a single value of a singletype() at a time. (Sometype()s are multi-valued, for example a string list.) You can find out what type, T, the variant holds, convert it to a different type usingconvert(), get its value using one of the toT() functions (e.g.,toSize()) and check whether the type can be converted to a particular type usingcanConvert().

The methods named toT() (e.g.,toInt(),toString()) are const. If you ask for the stored type, they return a copy of the stored object. If you ask for a type that can be generated from the stored type, toT() copies and converts and leaves the object itself unchanged. If you ask for a type that cannot be generated from the stored type, the result depends on the type; see the function documentation for details.

Here is some example code to demonstrate the use ofQVariant:

QDataStream out(...);QVariant v(123);// The variant now contains an intint x= v.toInt();// x = 123out<< v;// Writes a type tag and an int to outv=QVariant("hello");// The variant now contains a QByteArrayv=QVariant(tr("hello"));// The variant now contains a QStringint y= v.toInt();// y = 0 since v cannot be converted to an intQString s= v.toString();// s = tr("hello")  (see QObject::tr())out<< v;// Writes a type tag and a QString to out...QDataStream in(...);// (opening the previously written stream)in>> v;// Reads an Int variantint z= v.toInt();// z = 123qDebug("Type is %s",// prints "Type is int"        v.typeName());v= v.toInt()+100;// The variant now hold the value 223v=QVariant(QStringList());

You can even storeQList<QVariant> andQMap<QString,QVariant> values in a variant, so you can easily construct arbitrarily complex data structures of arbitrary types. This is very powerful and versatile, but may prove less memory and speed efficient than storing specific types in standard data structures.

QVariant also supports the notion of null values, where you can have a defined type with no value set. However, note thatQVariant types can only be cast when they have had a value set.

QVariant x, y(QString()), z(QString(""));x.convert(QVariant::Int);// x.isNull() == true// y.isNull() == true, z.isNull() == false

QVariant can be extended to support other types than those mentioned in theType enum. See theQMetaType documentation for details.

A Note on GUI Types

BecauseQVariant is part of theQtCore library, it cannot provide conversion functions to data types defined inQtGui, such asQColor,QImage, andQPixmap. In other words, there is notoColor() function. Instead, you can use theQVariant::value() or theqvariant_cast() template function. For example:

QVariant variant;...QColor color= variant.value<QColor>();

The inverse conversion (e.g., fromQColor toQVariant) is automatic for all data types supported byQVariant, including GUI-related types:

QColor color= palette().background().color();QVariant variant= color;

Using canConvert() and convert() Consecutively

When usingcanConvert() andconvert() consecutively, it is possible forcanConvert() to return true, butconvert() to return false. This is typically becausecanConvert() only reports the general ability ofQVariant to convert between types given suitable data; it is still possible to supply data which cannot actually be converted.

For example,canConvert() would return true when called on a variant containing a string because, in principle,QVariant is able to convert strings of numbers to integers. However, if the string contains non-numeric characters, it cannot be converted to an integer, and any attempt to convert it will fail. Hence, it is important to have both functions return true for a successful conversion.

Member Type Documentation

enum QVariant::Type

This enum type defines the types of variable that aQVariant can contain.

Member Function Documentation

QVariant::QVariant()

Constructs an invalid variant.

QVariant::QVariant(constQLocale & l)

Constructs a new variant with a locale value,l.

QVariant::QVariant(constQRegExp & regExp)

Constructs a new variant with the regexp valueregExp.

QVariant::QVariant(constQEasingCurve & val)

Constructs a new variant with an easing curve value,val.

This function was introduced in Qt 4.7.

QVariant::QVariant(Qt::GlobalColor color)

Constructs a new variant of typeQVariant::Color and initializes it withcolor.

This is a convenience constructor that allowsQVariant(Qt::blue); to create a validQVariant storing aQColor.

Note: This constructor will assert if the application does not link to the Qt GUI library.

This function was introduced in Qt 4.2.

QVariant::QVariant(Type type)

Constructs a null variant of typetype.

QVariant::QVariant(int typeOrUserType, constvoid * copy)

Constructs variant of typetypeOrUserType, and initializes withcopy ifcopy is not 0.

Note that you have to pass the address of the variable you want stored.

Usually, you never have to use this constructor, useQVariant::fromValue() instead to construct variants from the pointer types represented byQMetaType::VoidStar,QMetaType::QObjectStar andQMetaType::QWidgetStar.

See alsoQVariant::fromValue() andType.

QVariant::QVariant(constQVariant & p)

Constructs a copy of the variant,p, passed as the argument to this constructor.

QVariant::QVariant(QDataStream & s)

Reads the variant from the data stream,s.

QVariant::QVariant(int val)

Constructs a new variant with an integer value,val.

QVariant::QVariant(uint val)

Constructs a new variant with an unsigned integer value,val.

QVariant::QVariant(qlonglong val)

Constructs a new variant with a long long integer value,val.

QVariant::QVariant(qulonglong val)

Constructs a new variant with an unsigned long long integer value,val.

QVariant::QVariant(bool val)

Constructs a new variant with a boolean value,val.

QVariant::QVariant(double val)

Constructs a new variant with a floating point value,val.

QVariant::QVariant(float val)

Constructs a new variant with a floating point value,val.

This function was introduced in Qt 4.6.

QVariant::QVariant(constchar * val)

Constructs a new variant with a string value ofval. The variant creates a deep copy ofval, using the encoding set byQTextCodec::setCodecForCStrings().

Note thatval is converted to aQString for storing in the variant andQVariant::type() will returnQMetaType::QString for the variant.

You can disable this operator by definingQT_NO_CAST_FROM_ASCII when you compile your applications.

See alsoQTextCodec::setCodecForCStrings().

QVariant::QVariant(constQByteArray & val)

Constructs a new variant with a bytearray value,val.

QVariant::QVariant(constQBitArray & val)

Constructs a new variant with a bitarray value,val.

QVariant::QVariant(constQString & val)

Constructs a new variant with a string value,val.

QVariant::QVariant(constQLatin1String & val)

Constructs a new variant with a string value,val.

QVariant::QVariant(constQStringList & val)

Constructs a new variant with a string list value,val.

QVariant::QVariant(constQChar & c)

Constructs a new variant with a char value,c.

QVariant::QVariant(constQDate & val)

Constructs a new variant with a date value,val.

QVariant::QVariant(constQTime & val)

Constructs a new variant with a time value,val.

QVariant::QVariant(constQDateTime & val)

Constructs a new variant with a date/time value,val.

QVariant::QVariant(constQList<QVariant> & val)

Constructs a new variant with a list value,val.

QVariant::QVariant(constQMap<QString,QVariant> & val)

Constructs a new variant with a map ofQVariants,val.

QVariant::QVariant(constQHash<QString,QVariant> & val)

Constructs a new variant with a hash ofQVariants,val.

QVariant::QVariant(constQSize & val)

Constructs a new variant with a size value ofval.

QVariant::QVariant(constQSizeF & val)

Constructs a new variant with a size value ofval.

QVariant::QVariant(constQPoint & val)

Constructs a new variant with a point value ofval.

QVariant::QVariant(constQPointF & val)

Constructs a new variant with a point value ofval.

QVariant::QVariant(constQLine & val)

Constructs a new variant with a line value ofval.

QVariant::QVariant(constQLineF & val)

Constructs a new variant with a line value ofval.

QVariant::QVariant(constQRect & val)

Constructs a new variant with a rect value ofval.

QVariant::QVariant(constQRectF & val)

Constructs a new variant with a rect value ofval.

QVariant::QVariant(constQUrl & val)

Constructs a new variant with a url value ofval.

QVariant::~QVariant()

Destroys theQVariant and the contained object.

Note that subclasses that reimplementclear() should reimplement the destructor to callclear(). This destructor callsclear(), but because it is the destructor,QVariant::clear() is called rather than a subclass'sclear().

bool QVariant::canConvert(Type t) const

Returns true if the variant's type can be cast to the requested type,t. Such casting is done automatically when calling thetoInt(),toBool(), ... methods.

The following casts are done automatically:

See alsoconvert().

bool QVariant::canConvert() const

Returns true if the variant can be converted to the template typeT, otherwise false.

Example:

QVariant v=42;v.canConvert<int>();// returns truev.canConvert<QString>();// returns trueMyCustomStruct s;v.setValue(s);v.canConvert<int>();// returns falsev.canConvert<MyCustomStruct>();// returns true

See alsoconvert().

void QVariant::clear()

Convert this variant to type Invalid and free up any resources used.

bool QVariant::convert(Type t)

Casts the variant to the requested type,t. If the cast cannot be done, the variant is cleared. Returns true if the current type of the variant was successfully cast; otherwise returns false.

Warning: For historical reasons, converting a nullQVariant results in a null value of the desired type (e.g., an empty string forQString) and a result of false.

See alsocanConvert() andclear().

[static]QVariant QVariant::fromValue(constT & value)

Returns aQVariant containing a copy ofvalue. Behaves exactly likesetValue() otherwise.

Example:

MyCustomStruct s;returnQVariant::fromValue(s);

Note:If you are working with custom types, you should use theQ_DECLARE_METATYPE() macro to register your custom type.

See alsosetValue() andvalue().

bool QVariant::isNull() const

Returns true if this is a NULL variant, false otherwise.

bool QVariant::isValid() const

Returns true if the storage type of this variant is notQVariant::Invalid; otherwise returns false.

[static]Type QVariant::nameToType(constchar * name)

Converts the string representation of the storage type given inname, to its enum representation.

If the string representation cannot be converted to any enum representation, the variant is set toInvalid.

void QVariant::setValue(constT & value)

Stores a copy ofvalue. IfT is a type thatQVariant doesn't support,QMetaType is used to store the value. A compile error will occur ifQMetaType doesn't handle the type.

Example:

QVariant v;v.setValue(5);int i= v.toInt();// i is now 5QString s= v.toString()// s is now "5"MyCustomStruct c;v.setValue(c);...MyCustomStruct c2= v.value<MyCustomStruct>();

See alsovalue(),fromValue(), andcanConvert().

void QVariant::swap(QVariant & other)

Swaps variantother with this variant. This operation is very fast and never fails.

This function was introduced in Qt 4.8.

QBitArray QVariant::toBitArray() const

Returns the variant as aQBitArray if the variant hastype()BitArray; otherwise returns an empty bit array.

See alsocanConvert() andconvert().

bool QVariant::toBool() const

Returns the variant as a bool if the variant hastype() Bool.

Returns true if the variant hastype()Bool,Char,Double,Int,LongLong,UInt, orULongLong and the value is non-zero, or if the variant has typeString orByteArray and its lower-case content is not empty, "0" or "false"; otherwise returns false.

See alsocanConvert() andconvert().

QByteArray QVariant::toByteArray() const

Returns the variant as aQByteArray if the variant hastype()ByteArray orString (converted usingQString::fromAscii()); otherwise returns an empty byte array.

See alsocanConvert() andconvert().

QChar QVariant::toChar() const

Returns the variant as aQChar if the variant hastype()Char,Int, orUInt; otherwise returns an invalidQChar.

See alsocanConvert() andconvert().

QDate QVariant::toDate() const

Returns the variant as aQDate if the variant hastype()Date,DateTime, orString; otherwise returns an invalid date.

If thetype() isString, an invalid date will be returned if the string cannot be parsed as aQt::ISODate format date.

See alsocanConvert() andconvert().

QDateTime QVariant::toDateTime() const

Returns the variant as aQDateTime if the variant hastype()DateTime,Date, orString; otherwise returns an invalid date/time.

If thetype() isString, an invalid date/time will be returned if the string cannot be parsed as aQt::ISODate format date/time.

See alsocanConvert() andconvert().

double QVariant::toDouble(bool * ok = 0) const

Returns the variant as a double if the variant hastype()Double,QMetaType::Float,Bool,ByteArray,Int,LongLong,String,UInt, orULongLong; otherwise returns 0.0.

Ifok is non-null:*ok is set to true if the value could be converted to a double; otherwise*ok is set to false.

See alsocanConvert() andconvert().

QEasingCurve QVariant::toEasingCurve() const

Returns the variant as aQEasingCurve if the variant hastype()EasingCurve; otherwise returns a default easing curve.

This function was introduced in Qt 4.7.

See alsocanConvert() andconvert().

float QVariant::toFloat(bool * ok = 0) const

Returns the variant as a float if the variant hastype()Double,QMetaType::Float,Bool,ByteArray,Int,LongLong,String,UInt, orULongLong; otherwise returns 0.0.

Ifok is non-null:*ok is set to true if the value could be converted to a double; otherwise*ok is set to false.

This function was introduced in Qt 4.6.

See alsocanConvert() andconvert().

QHash<QString,QVariant> QVariant::toHash() const

Returns the variant as aQHash<QString,QVariant> if the variant hastype()Hash; otherwise returns an empty map.

See alsocanConvert() andconvert().

int QVariant::toInt(bool * ok = 0) const

Returns the variant as an int if the variant hastype()Int,Bool,ByteArray,Char,Double,LongLong,String,UInt, orULongLong; otherwise returns 0.

Ifok is non-null:*ok is set to true if the value could be converted to an int; otherwise*ok is set to false.

Warning: If the value is convertible to aLongLong but is too large to be represented in an int, the resulting arithmetic overflow will not be reflected inok. A simple workaround is to useQString::toInt(). Fixing this bug has been postponed to Qt 5 in order to avoid breaking existing code.

See alsocanConvert() andconvert().

QLine QVariant::toLine() const

Returns the variant as aQLine if the variant hastype()Line; otherwise returns an invalidQLine.

See alsocanConvert() andconvert().

QLineF QVariant::toLineF() const

Returns the variant as aQLineF if the variant hastype()LineF; otherwise returns an invalidQLineF.

See alsocanConvert() andconvert().

QList<QVariant> QVariant::toList() const

Returns the variant as aQVariantList if the variant hastype()List orStringList; otherwise returns an empty list.

See alsocanConvert() andconvert().

QLocale QVariant::toLocale() const

Returns the variant as aQLocale if the variant hastype()Locale; otherwise returns an invalidQLocale.

See alsocanConvert() andconvert().

qlonglong QVariant::toLongLong(bool * ok = 0) const

Returns the variant as a long long int if the variant hastype()LongLong,Bool,ByteArray,Char,Double,Int,String,UInt, orULongLong; otherwise returns 0.

Ifok is non-null:*ok is set to true if the value could be converted to an int; otherwise*ok is set to false.

See alsocanConvert() andconvert().

QMap<QString,QVariant> QVariant::toMap() const

Returns the variant as aQMap<QString,QVariant> if the variant hastype()Map; otherwise returns an empty map.

See alsocanConvert() andconvert().

QPoint QVariant::toPoint() const

Returns the variant as aQPoint if the variant hastype()Point orPointF; otherwise returns a nullQPoint.

See alsocanConvert() andconvert().

QPointF QVariant::toPointF() const

Returns the variant as aQPointF if the variant hastype()Point orPointF; otherwise returns a nullQPointF.

See alsocanConvert() andconvert().

qreal QVariant::toReal(bool * ok = 0) const

Returns the variant as a qreal if the variant hastype()Double,QMetaType::Float,Bool,ByteArray,Int,LongLong,String,UInt, orULongLong; otherwise returns 0.0.

Ifok is non-null:*ok is set to true if the value could be converted to a double; otherwise*ok is set to false.

This function was introduced in Qt 4.6.

See alsocanConvert() andconvert().

QRect QVariant::toRect() const

Returns the variant as aQRect if the variant hastype()Rect; otherwise returns an invalidQRect.

See alsocanConvert() andconvert().

QRectF QVariant::toRectF() const

Returns the variant as aQRectF if the variant hastype()Rect orRectF; otherwise returns an invalidQRectF.

See alsocanConvert() andconvert().

QRegExp QVariant::toRegExp() const

Returns the variant as aQRegExp if the variant hastype()RegExp; otherwise returns an emptyQRegExp.

This function was introduced in Qt 4.1.

See alsocanConvert() andconvert().

QSize QVariant::toSize() const

Returns the variant as aQSize if the variant hastype()Size; otherwise returns an invalidQSize.

See alsocanConvert() andconvert().

QSizeF QVariant::toSizeF() const

Returns the variant as aQSizeF if the variant hastype()SizeF; otherwise returns an invalidQSizeF.

See alsocanConvert() andconvert().

QString QVariant::toString() const

Returns the variant as aQString if the variant hastype()String,Bool,ByteArray,Char,Date,DateTime,Double,Int,LongLong,StringList,Time,UInt, orULongLong; otherwise returns an empty string.

See alsocanConvert() andconvert().

QStringList QVariant::toStringList() const

Returns the variant as aQStringList if the variant hastype()StringList,String, orList of a type that can be converted toQString; otherwise returns an empty list.

See alsocanConvert() andconvert().

QTime QVariant::toTime() const

Returns the variant as aQTime if the variant hastype()Time,DateTime, orString; otherwise returns an invalid time.

If thetype() isString, an invalid time will be returned if the string cannot be parsed as aQt::ISODate format time.

See alsocanConvert() andconvert().

uint QVariant::toUInt(bool * ok = 0) const

Returns the variant as an unsigned int if the variant hastype()UInt,Bool,ByteArray,Char,Double,Int,LongLong,String, orULongLong; otherwise returns 0.

Ifok is non-null:*ok is set to true if the value could be converted to an unsigned int; otherwise*ok is set to false.

Warning: If the value is convertible to aULongLong but is too large to be represented in an unsigned int, the resulting arithmetic overflow will not be reflected inok. A simple workaround is to useQString::toUInt(). Fixing this bug has been postponed to Qt 5 in order to avoid breaking existing code.

See alsocanConvert() andconvert().

qulonglong QVariant::toULongLong(bool * ok = 0) const

Returns the variant as as an unsigned long long int if the variant hastype()ULongLong,Bool,ByteArray,Char,Double,Int,LongLong,String, orUInt; otherwise returns 0.

Ifok is non-null:*ok is set to true if the value could be converted to an int; otherwise*ok is set to false.

See alsocanConvert() andconvert().

QUrl QVariant::toUrl() const

Returns the variant as aQUrl if the variant hastype()Url; otherwise returns an invalidQUrl.

See alsocanConvert() andconvert().

Type QVariant::type() const

Returns the storage type of the value stored in the variant. Although this function is declared as returningQVariant::Type, the return value should be interpreted asQMetaType::Type. In particular,QVariant::UserType is returned here only if the value is equal or greater thanQMetaType::User.

Note that return values in the rangesQVariant::Char throughQVariant::RegExp andQVariant::Font throughQVariant::Transform correspond to the values in the rangesQMetaType::QChar throughQMetaType::QRegExp andQMetaType::QFont throughQMetaType::QQuaternion.

Pay particular attention when working with char andQChar variants. Note that there is noQVariant constructor specifically for type char, but there is one forQChar. For a variant of typeQChar, this function returnsQVariant::Char, which is the same asQMetaType::QChar, but for a variant of typechar, this function returnsQMetaType::Char, which isnot the same asQVariant::Char.

Also note that the typesvoid*,long,short,unsignedlong,unsignedshort,unsignedchar,float,QObject*, andQWidget* are represented inQMetaType::Type but not inQVariant::Type, and they can be returned by this function. However, they are considered to be user defined types when tested againstQVariant::Type.

To test whether an instance ofQVariant contains a data type that is compatible with the data type you are interested in, usecanConvert().

constchar * QVariant::typeName() const

Returns the name of the type stored in the variant. The returned strings describe the C++ datatype used to store the data: for example, "QFont", "QString", or "QVariantList". An Invalid variant returns 0.

[static]constchar * QVariant::typeToName(Type typ)

Converts the enum representation of the storage type,typ, to its string representation.

Returns a null pointer if the type isQVariant::Invalid or doesn't exist.

int QVariant::userType() const

Returns the storage type of the value stored in the variant. For non-user types, this is the same astype().

See alsotype().

T QVariant::value() const

Returns the stored value converted to the template typeT. CallcanConvert() to find out whether a type can be converted. If the value cannot be converted, default-constructed value will be returned.

If the typeT is supported byQVariant, this function behaves exactly astoString(),toInt() etc.

Example:

QVariant v;MyCustomStruct c;if (v.canConvert<MyCustomStruct>())    c= v.value<MyCustomStruct>();v=7;int i= v.value<int>();// same as v.toInt()QString s= v.value<QString>();// same as v.toString(), s is now "7"MyCustomStruct c2= v.value<MyCustomStruct>();// conversion failed, c2 is empty

See alsosetValue(),fromValue(), andcanConvert().

bool QVariant::operator!=(constQVariant & v) const

Compares thisQVariant withv and returns true if they are not equal; otherwise returns false.

Warning: This function doesn't support custom types registered withqRegisterMetaType().

QVariant & QVariant::operator=(constQVariant & variant)

Assigns the value of the variantvariant to this variant.

QVariant & QVariant::operator=(QVariant && other)

bool QVariant::operator==(constQVariant & v) const

Compares thisQVariant withv and returns true if they are equal; otherwise returns false.

In the case of custom types, their equalness operators are not called. Instead the values' addresses are compared.

Related Non-Members

typedefQVariantHash

Synonym forQHash<QString,QVariant>.

This typedef was introduced in Qt 4.5.

typedefQVariantList

Synonym forQList<QVariant>.

typedefQVariantMap

Synonym forQMap<QString,QVariant>.

Tqvariant_cast(constQVariant & value)

Returns the givenvalue converted to the template typeT.

This function is equivalent toQVariant::value().

See alsoQVariant::value().

booloperator!=(constQVariant & v1, constQVariant & v2)

Returns false ifv1 andv2 are equal; otherwise returns true.

Warning: This function doesn't support custom types registered withqRegisterMetaType().

booloperator==(constQVariant & v1, constQVariant & v2)

Returns true ifv1 andv2 are equal; otherwise returns false.

Warning: This function doesn't support custom types registered withqRegisterMetaType().