Home

ClassesAnnotated - TreeFunctionsHomeStructure

QVariant Class Reference


Acts like a union for the most common Qt data types. More...

#include <qvariant.h>

List of all member functions.

Public Members

Static Public Members


Detailed Description

Acts like a union for the most common Qt data types.

C++ forbids unions from including classes that have constructors and destructors since the compiler and the runtime library cannot determine which constructor or destructor to call when an object goes in and out of scope.

To overcome this, a QVariant can be used to store the most common Qt and C++ data types. Like a union it can hold only one value of one type at any one time.

For each QVariant::Type that the variant can hold, there is a constructor to create a QVariant from a value of the type, and two access methods to retrieve the value. The access methods do automatic conversion. Which conversion is possible can be queried by calling canCast().

The methods named toT() are const. They return a copy of the stored data type or do conversion if needed. The conversion is only done for the returned value but the variant itself does not change. Please notice that some Qt data types such as QImage, QBrush, QPointArray, QRegion, QCString and QPalette are explicit shared. The toT() methods only return a shallow copy. That means you should make a deep copy of the returned values before modifying them.

The methods named asT() are not const. They act like the toT() methods except for two very important points. asT() returns a reference to the stored value instead of returning a copy and the casting affects the variant itself. That means if you store for example an interger in your variant and call asDouble() then the variant is converted to contain a double now and a reference to this double is returned.

Here is some example code to demonstrate the usage of QVariant:

    QDataStream out(...);
    QVariant v(123);          // The variant now contains an int
    int x = v.toInt();        // x = 123
    out << v;                 // Writes a type tag an int to out
    v = QVariant("hello");    // The variant now contains a QCString
    v = QVariant(tr("hello"));// The variant now contains a QString
    int y = v.toInt();        // x = 0, since v is not an int
    QString 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 variant
    int z = v.toInt();        // z = 123
    qDebug("Type is %s",      // prints "Type is int"
      v.typeName());
    v.asInt() += 100;         // The variant now hold the value 223.
    v = QVariant( QStringList() );
    v.asStringList().append( "Hallo" );

You can even have a QValueList stored in the variant - giving arbitrarily complex data values with lists of variants, some of which are strings while others are integers and other still are lists of lists of lists of variants. Of course, you'll need to be careful with your encapsulations or else the typelessness will make your code look like spam, spam, spam, baked beans and spam.

You can find the type of a variant with type(). There is a special type, Invalid, which can be used for special cases. The isValid() function tests for this type.


Member Type Documentation

QVariant::Type

This enum type defines the types of variable that a QVariant can contain. The supported enum values and the associated types are: Note that Qt's idea of bool depends on the compiler. qglobal.h has the system-dependent definition of bool.

Member Function Documentation

QVariant::QVariant ()

Constructs an invalid variant.

QVariant::QVariant ( QDataStream & s )

Reads the variant from the data stream.

QVariant::QVariant ( bool val, int )

Constructs a new variant with a boolean value. The integer argument is a dummy, so even the (name and description omitted) compiler can handle QVariant.

QVariant::QVariant ( const QBitmap & val )

Constructs a new variant with a bitmap.

QVariant::QVariant ( const QBrush & val )

Constructs a new variant with a brush value. The variant creates only a shallow copy of the brush since QBrush is explicit shared.

QVariant::QVariant ( const QColor & val )

Constructs a new variant with a color value.

QVariant::QVariant ( const QColorGroup & val )

Constructs a new variant with a color group value.

QVariant::QVariant ( const QCString & val )

Constructs a new variant with a c-string value. If you want to modify the QCString you passed to this constructor afterwards, then pass a deep copy by calling QCString::copy().

QVariant::QVariant ( const QCursor & val )

Constructs a new variant with a cursor.

QVariant::QVariant ( const QFont & val )

Constructs a new variant with a font value.

QVariant::QVariant ( const QIconSet & val )

Constructs a new variant with an iconset.

QVariant::QVariant ( const QImage & val )

Constructs a new variant with an image value. Since QImage is explicit shared you may consider to pass a deep copy to the variant by calling QImage::copy().

QVariant::QVariant ( const QMap<QString,QVariant> & val )

Constructs a new variant with a map of QVariants.

QVariant::QVariant ( const QPalette & val )

Constructs a new variant with a color palette value. Since QPalette is explicit shared you may consider to pass a deep copy to the variant by calling QPalette::copy().

QVariant::QVariant ( const QPixmap & val )

Constructs a new variant with a pixmap value.

QVariant::QVariant ( const QPoint & val )

Constructs a new variant with a point value.

QVariant::QVariant ( const QPointArray & val )

Constructs a new variant with an array of points. Since QPointArray is explicit shared you may consider to pass a deep copy to the variant by calling QPointArray::copy().

QVariant::QVariant ( const QRect & val )

Constructs a new variant with a rect value.

QVariant::QVariant ( const QRegion & val )

Constructs a new variant with a region. The variant creates only a shallow copy of the brush since QBrush is explicit shared.

QVariant::QVariant ( const QSize & val )

Constructs a new variant with a size value.

QVariant::QVariant ( const QString & val )

Constructs a new variant with a string value.

QVariant::QVariant ( const QStringList & val )

Constructs a new variant with a string list value.

QVariant::QVariant ( const QValueList<QVariant> & val )

Constructs a new variant with a list value.

QVariant::QVariant ( const QVariant & p )

Constructs a copy of the variant passed as argument to this constructor. Usually this is a deep copy. But if the stored data type is explicit shared then only a shallow copy is made.

The variant just resembles the copy behaviour of the data type it contains.

QVariant::QVariant ( const char * val )

Constructs a new variant with a c-string value. The variant creates a deep copy of the string. Passing a null string will result in an invalid variant.

QVariant::QVariant ( double val )

Constructs a new variant with a floating point value.

QVariant::QVariant ( int val )

Constructs a new variant with an integer value.

QVariant::QVariant ( uint val )

Constructs a new variant with an unsigned integer value.

QVariant::~QVariant ()

Destructs the QVariant and the contained object.

Note that subclasses that re-implement clear() should reimplement the destructor to call clear(). This destructor calls clear(), but since it is the destructor, QVariant::clear() is called rather than any subclass.

QBitmapQVariant::asBitmap ()

Tries to convert the variant to hold a bitmap value. If that is not possible then the variant holds a null bitmap.

Returns a reference to the stored bitmap.

See also: toBitmap().

bool& QVariant::asBool ()

Returns the variant's value as bool reference.

QBrushQVariant::asBrush ()

Tries to convert the variant to hold a brush value. If that is not possible then the variant holds a default black brush.

Returns a reference to the stored brush.

See also: toBrush().

QCStringQVariant::asCString ()

Tries to convert the variant to hold a string value. If that is not possible then the variant holds an empty string.

Returns a reference to the stored string.

See also: toCString().

QColorQVariant::asColor ()

Tries to convert the variant to hold a QColor value. If that is not possible then the variant holds an invalid color.

Returns a reference to the stored color.

See also: toColor() and QColor::isValid().

QColorGroupQVariant::asColorGroup ()

Tries to convert the variant to hold a QColorGroup value. If that is not possible then the variant holds a color group with all colors set to black.

Returns a reference to the stored color group.

See also: toColorGroup().

QCursorQVariant::asCursor ()

Tries to convert the variant to hold a QCursor value. If that is not possible then the variant holds a default arrow cursor.

Returns a reference to the stored cursor.

See also: toCursor().

double& QVariant::asDouble ()

Returns the variant's value as double reference.

QFontQVariant::asFont ()

Tries to convert the variant to hold a QFont. If that is not possible then the variant holds a default font.

Returns a reference to the stored font.

See also: toFont().

QIconSetQVariant::asIconSet ()

Tries to convert the variant to hold a QIconSet value. If that is not possible then the variant holds an empty iconset.

Returns a reference to the stored iconset.

See also: toIconSet().

QImageQVariant::asImage ()

Tries to convert the variant to hold an image value. If that is not possible then the variant holds a null image.

Returns a reference to the stored image.

See also: toImage().

int& QVariant::asInt ()

Returns the variant's value as int reference.

QValueList<QVariant>& QVariant::asList ()

Returns the variant's value as variant list reference.

QPaletteQVariant::asPalette ()

Tries to convert the variant to hold a QPalette value. If that is not possible then the variant holds a palette with black colors only.

Returns a reference to the stored palette.

See also: toString().

QPixmapQVariant::asPixmap ()

Tries to convert the variant to hold a pixmap value. If that is not possible then the variant holds a null pixmap.

Returns a reference to the stored pixmap.

See also: toPixmap().

QPointQVariant::asPoint ()

Tries to convert the variant to hold a point value. If that is not possible then the variant holds a null point.

Returns a reference to the stored point.

See also: toPoint().

QPointArrayQVariant::asPointArray ()

Tries to convert the variant to hold a QPointArray value. If that is not possible then the variant holds an empty point array.

Returns a reference to the stored point array.

See also: toPointArray().

QRectQVariant::asRect ()

Tries to convert the variant to hold a rectangle value. If that is not possible then the variant holds an empty rectangle.

Returns a reference to the stored rectangle.

See also: toRect().

QRegionQVariant::asRegion ()

Tries to convert the variant to hold a QRegion value. If that is not possible then the variant holds a null region.

Returns a reference to the stored region.

See also: toRegion().

QSizeQVariant::asSize ()

Tries to convert the variant to hold a QSize value. If that is not possible then the variant holds an invalid size.

Returns a reference to the stored size.

See also: toSize() and QSize::isValid().

QStringQVariant::asString ()

Tries to convert the variant to hold a string value. If that is not possible then the variant holds an empty string.

Returns a reference to the stored string.

See also: toString().

QStringListQVariant::asStringList ()

Tries to convert the variant to hold a QStringList value. If that is not possible then the variant holds an empty string list.

Returns a reference to the stored string list.

See also: toStringList().

uint& QVariant::asUInt ()

Returns the variant's value as unsigned int reference.

bool QVariant::canCast ( Type t ) const

Returns TRUE if the current type of the variant can be casted to the requested type. The casting is done automatically when calling the toInt(), toBool(), ... or asInt(), asBool(), ... methods.

The following casts are done automatically:

void QVariant::clear ()

De-allocate any used memory, based on the type, producing an Invalid variant.

bool QVariant::isValid () const

Returns TRUE if the storage type of this variant is not QVariant::Invalid.

QValueListConstIterator<QVariant> QVariant::listBegin () const

If the type of the variant is List, then an iterator to the first element in the list is returned. Otherwise a null iterator is returned.

QValueListConstIterator<QVariant> QVariant::listEnd () const

If the type of the variant is List, then the end iterator of the list is returned. Otherwise a null iterator is returned.

void QVariant::load ( QDataStream & s )

Internal function for loading a variant. Use the stream operators instead.

QVariant::Type QVariant::nameToType( const char * name ) [static]

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

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

Compares this QVariant with v and returns TRUE if they are not equal, FALSE othervise.

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

Assigns the value of some other variant to this variant. This is a deep copy.

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

Compares this QVariant with v and returns TRUE if they are equal, FALSE othervise.

void QVariant::save ( QDataStream & s ) const

Internal function for saving a variant. Use the stream operators instead.

QValueListConstIterator<QStringQVariant::stringListBegin () const

If the type of the variant is StringList, then an iterator to the first string in the list is returned. Otherwise a null iterator is returned.

QValueListConstIterator<QStringQVariant::stringListEnd () const

If the type of the variant is StringList, then the end iterator of the list is returned. Otherwise a null iterator is returned.

const QBitmap QVariant::toBitmap () const

Returns the variant as a QBitmap if the variant has type() Bitmap, or a null QBitmap otherwise.

See also: asBitmap().

bool QVariant::toBool () const

Returns the variant as a bool if the variant has type() Bool, or FALSE otherwise. The only exceptions to this rule are the types Int, UInt, Double. In this case TRUE is returned if the numerical value is not zero or FALSE otherwise.

See also: asBool().

const QBrush QVariant::toBrush () const

Returns the variant as a QBrush if the variant has type() Brush, or a default brush with black colors otherwise.

See also: asBrush().

const QCString QVariant::toCString () const

Returns the variant as a QCString if the variant has type() CString, or a 0 otherwise.

See also: asCString().

const QColor QVariant::toColor () const

Returns the variant as a QColor if the variant has type() Color, or an invalid color otherwise.

See also: asColor().

const QColorGroup QVariant::toColorGroup () const

Returns the variant as a QColorGroup if the variant has type() ColorGroup, or a completely black color group otherwise.

See also: asColorGroup().

const QCursor QVariant::toCursor () const

Returns the variant as a QCursor if the variant has type() Cursor, or the default arrow cursor otherwise.

See also: asCursor().

double QVariant::toDouble () const

Returns the variant as a double if the variant has type() Double, Int, UInt or Bool, or 0.0 otherwise.

See also: asDouble().

const QFont QVariant::toFont () const

Returns the variant as a QFont if the variant has type() Font, or the default font otherwise.

See also: asFont().

const QIconSet QVariant::toIconSet () const

Returns the variant as a QIconSet if the variant has type() IconSet, or an icon set of null pixmaps otherwise.

See also: asIconSet().

const QImage QVariant::toImage () const

Returns the variant as a QImage if the variant has type() Image, or a null image otherwise.

See also: asImage().

int QVariant::toInt () const

Returns the variant as an int if the variant has type() Int, UInt, Double or Bool, or 0 otherwise.

See also: asInt().

const QValueList<QVariant> QVariant::toList () const

Returns the variant as a QValueList if the variant has type() List or StringList, or an empty list otherwise.

See also: asList().

const QPalette QVariant::toPalette () const

Returns the variant as a QPalette if the variant has type() Palette, or a completely black palette otherwise.

See also: asPalette().

const QPixmap QVariant::toPixmap () const

Returns the variant as a QPixmap if the variant has type() Pixmap, or a null pixmap otherwise.

See also: asPixmap().

const QPoint QVariant::toPoint () const

Returns the variant as a QPoint if the variant has type() Point, or a the point (0,0) otherwise.

See also: asPoint().

const QPointArray QVariant::toPointArray () const

Returns the variant as a QPointArray if the variant has type() PointArray, or an empty QPointArray otherwise.

See also: asPointArray().

const QRect QVariant::toRect () const

Returns the variant as a QRect if the variant has type() Rect, or an empty rectangle otherwise.

See also: asRect().

const QRegion QVariant::toRegion () const

Returns the variant as a QRegion if the variant has type() Region, or an empty QRegion otherwise.

See also: asRegion().

const QSize QVariant::toSize () const

Returns the variant as a QSize if the variant has type() Size, or an invalid size otherwise.

See also: asSize().

const QString QVariant::toString () const

Returns the variant as a QString if the variant has type() String or CString, or QString::null otherwise.

See also: asString().

const QStringList QVariant::toStringList () const

Returns the variant as a QStringList if the variant has type() StringList or List, or an empty list otherwise.

See also: asStringList().

uint QVariant::toUInt () const

Returns the variant as an unsigned int if the variant has type() UInt, Int, Double or Bool, or 0 otherwise.

See also: asUInt().

Type QVariant::type () const

Returns the stoarge type of the value stored in the variant currently. Usually you may want to test with canCast() wether the variant can deliver the data type you are interested in.

const char* 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 "QValueList". An Invalid variant returns 0.

const char* QVariant::typeToName ( Type typ ) [static]

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


Search the documentation, FAQ, qt-interest archive and more (uses www.trolltech.com):


This file is part of the Qt toolkit, copyright © 1995-2000 Troll Tech, all rights reserved.


Copyright İ 2000 Troll TechTrademarks
Qt version 2.1.1