Data Type Conversion Between QML and C++▲

When data values are exchanged between QML and C++, they are converted by the QML engine to have the correct data types as appropriate for use in QML or C++. This requires the exchanged data to be of a type that is recognizable by the engine.

The QML engine provides built-in support for a large number of Qt C++ data types. Additionally, custom C++ types may be registered with the QML type system to make them available to the engine.

This page discusses the data types supported by the QML engine and how they are converted between QML and C++.

Data Ownership▲

When data is transferred from C++ to QML, the ownership of the data always remains with C++. The exception to this rule is when a QObject is returned from an explicit C++ method call: in this case, the QML engine assumes ownership of the object, unless the ownership of the object has explicitly been set to remain with C++ by invoking QQmlEngine::setObjectOwnership() with QQmlEngine::CppOwnership specified.

Additionally, the QML engine respects the normal QObject parent ownership semantics of Qt C++ objects, and will never delete a QObject instance which has a parent.

Basic Qt Data Types▲

By default, QML recognizes the following Qt data types, which are automatically converted to a corresponding QML basic type when passed from C++ to QML and vice-versa:

Qt Type

QML Basic Type

bool

bool

unsigned int, int

int

double

double

float, qreal

real

QString

string

QUrl

url

QColor

color

QFont

font

QDateTime

date

QPoint, QPointF

point

QSize, QSizeF

size

QRect, QRectF

rect

QMatrix4x4

matrix4x4

QQuaternion

quaternion

QVector2D, QVector3D, QVector4D

vector2d, vector3d, vector4d

Enums declared with Q_ENUM() or Q_ENUMS()

enumeration

Classes provided by the Qt GUI module, such as QColor, QFont, QQuaternion and QMatrix4x4, are only available from QML when the Qt Quick module is included.

As a convenience, many of these types can be specified in QML by string values, or by a related method provided by the QtQml::Qt object. For example, the Image::sourceSize property is of type size (which automatically translates to the QSize type) and can be specified by a string value formatted as "widthxheight", or by the Qt.size() function:

 
Sélectionnez
Item {
    Image { sourceSize: "100x200" }
    Image { sourceSize: Qt.size(100, 200) }
}

See documentation for each individual type under QML Basic Types for more information.

QObject-derived Types▲

Any QObject-derived class may be used as a type for the exchange of data between QML and C++, providing the class has been registered with the QML type system.

The engine allows the registration of both instantiable and non-instantiable types. Once a class is registered as a QML type, it can be used as a data type for exchanging data between QML and C++. See Registering C++ types with the QML type system for further details on type registration.

Conversion Between Qt and JavaScript Types▲

The QML engine has built-in support for converting a number of Qt types to related JavaScript types, and vice-versa, when transferring data between QML and C++. This makes it possible to use these types and receive them in C++ or JavaScript without needing to implement custom types that provide access to the data values and their attributes.

(Note that the JavaScript environment in QML modifies native JavaScript object prototypes, including those of String, Date and Number, to provide additional features. See the JavaScript Host Environment for further details.)

QVariantList and QVariantMap to JavaScript Array and Object▲

The QML engine provides automatic type conversion between QVariantList and JavaScript arrays, and between QVariantMap and JavaScript objects.

For example, the function defined in QML below expects two arguments, an array and an object, and prints their contents using the standard JavaScript syntax for array and object item access. The C++ code below calls this function, passing a QVariantList and a QVariantMap, which are automatically converted to JavaScript array and object values, repectively:

QML
 
Sélectionnez
// MyItem.qml
Item {
    function readValues(anArray, anObject) {
        for (var i=0; i<anArray.length; i++)
            console.log("Array item:", anArray[i])

        for (var prop in anObject) {
            console.log("Object item:", prop, "=", anObject[prop])
        }
    }
}

C++
 
Sélectionnez
// C++
QQuickView view(QUrl::fromLocalFile("MyItem.qml"));

QVariantList list;
list <