1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
8\brief List of QML types provided by the Qt QML module
10The \l{Qt Qml} module provides the definition and implementation of various
11convenience types that can be used with the QML language. This includes
12elementary QML types, which can provide the basis for further extensions to the
13QML language. The \l QtObject and \l Component object types are non-visual and
14provide building-blocks for extensions to QML.
16\section1 Importing QtQml
18The types provided by the \c QtQml module are only available in a QML document
19if that document imports the \c QtQml namespace (or if the document imports the
20\c QtQuick namespace, as noted below).
22To use the module, import the \c QtQml module with the following statement:
28Many clients will never need to use the \c QtQml module directly, but will rather
29import it indirectly via the \c QtQuick module as follows:
35See the \l{Qt Quick} module documentation for more information about its types.
37The QML types for creating lists and models, such as \l ListModel and
38\l ListElement, belong to a submodule, \l{Qt QML Models QML Types}{QtQml.Models}.
40The \l WorkerScript QML type belongs to the submodule
41\l{Qt QML WorkerScript QML Types}{QtQml.WorkerScript}.
43Both, \l{Qt QML Models QML Types}{QtQml.Models} and
44\l{Qt QML WorkerScript QML Types}{QtQml.WorkerScript} are automatically imported
45whenever you import \c QtQml. All their types are then available, too.
47The \l{Qt Quick} module automatically imports \c QtQml and, transitively,
48\l{Qt QML Models QML Types}{QtQml.Models} and
49\l{Qt QML WorkerScript QML Types}{QtQml.WorkerScript}, making all their types
50available whenever you import \c QtQuick.
54The following \l{qtqml-typesystem-valuetypes.html}{QML Value Types} are
57\annotatedlist qtqmlvaluetypes
59\section1 Sequence Types
61The following \l{QML Sequence Types}{QML sequence types} are provided by the Qt
62QML module in addition to the ones registered with each value type and object
66 \li \c {std::vector<QString>}
67 \li \c {std::vector<QUrl>}
68 \li \c {std::vector<bool>}
69 \li \c {std::vector<int>}
70 \li \c {std::vector<float>}
71 \li \c {std::vector<double>}
76The following \l{qtqml-typesystem-objecttypes.html}{QML object types} are
86The \c date type refers to a date value, including the time of the day.
88Properties of type \c date default to an invalid value.
90To create a \c date value, specify it as a "YYYY-MM-DDThh:mm:ss.zzzZ" string.
91(The T is literal, YYYY is a full year number, MM and DD are month and day
92numbers, hh, mm and ss are hours, minutes and seconds, with .zzz as
93milliseconds and Z as time-zone offset. The T and following time are optional.
94If they are omitted, the date is handled as the start of UTC's day, which
95falls on other dates in some time-zones. When T is included, the :ss.zzz or
96just .zzz part can be omitted. With or without those, the zone offset can be
97omitted, in which case local time is used.) For example:
100MyDatePicker { minDate: "2000-01-01 0:0"; maxDate: "2020-12-31 23:59" }
103To read a date value returned from a C++ extension class, use
104\l{QtQml::Qt::formatDate()}{Qt.formatDate()} and \l{QtQml::Qt::formatDateTime()}{Qt.formatDateTime()}.
106When integrating with C++, note that any QDate or QDateTime value
107\l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
108converted into a \c date value, and vice-versa. Note, however, that
109converting a QDate will result in UTC's start of the day, which falls on
110a different date in some other time-zones. It is usually more robust
111to convert the QDate via a QDateTime explicitly, specifying local-time
112or a relevant time-zone and selecting a time of day (such as noon)
113that reliably exists (daylight-savings transitions skip an hour, near
114one end or the other of a day).
116This value type is provided by the QML language. It can be implicitly converted
117to a \l{QtQml::Date}{Date} object.
119\sa {QtQml::Date}{QML Date object}, {QML Value Types}
124\ingroup qtqmlvaluetypes
125\brief a value with x and y attributes.
127The \c point type refers to a value with \c x and \c y attributes.
129To create a \c point value, specify it as a "x,y" string:
132CustomObject { myPointProperty: "0,20" }
135Or use the \l{QtQml::Qt::point()}{Qt.point()} function:
138CustomObject { myPointProperty: Qt.point(0, 20) }
141When integrating with C++, note that any QPoint or QPointF value
142\l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
143converted into a \c point value. When a \c point value is passed to C++, it
144is automatically converted into a QPointF value.
146Properties of type \c point are \c {Qt.point(0, 0)} by default.
153\ingroup qtqmlvaluetypes
154\brief a value with width and height attributes.
156The \c size type refers to a value with has \c width and \c height attributes.
158Properties of type \c size have \c {Qt.size(-1, -1)} as default value.
160For example, to read the \c width and \c height values of the
161\l {Image::sourceSize} size-type property:
165 Image { id: image; source: "logo.png" }
166 Text { text: image.sourceSize.width + "," + image.sourceSize.height }
170To create a \c size value, specify it as a "width x height" string:
173Image { sourceSize: "150x50" }
176Or use the \l{QtQml::Qt::size()}{Qt.size()} function:
179Image { sourceSize: Qt.size(150, 50) }
182When integrating with C++, note that any QSize or QSizeF value
183\l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
184converted into a \c size value, and vice-versa. When a \c size value is passed to C++, it
185is automatically converted into a QSizeF value.
192\ingroup qtqmlvaluetypes
193\brief a value with x, y, width and height attributes.
195The \c rect type refers to a value with \c x, \c y, \c width and \c height attributes.
197Properties of type \c rect are \c {Qt.rect(0, 0, 0, 0)} by default. This is an
198empty rectangle at the coordinate origin.
200For example, to read the \c width and \c height values of the \l Item
201\l {Item::childrenRect.x}{childrenRect} rect-type property:
205 width: childrenRect.width
206 height: childrenRect.height
208 Rectangle { width: 100; height: 100 }
212To create a \c rect value, specify it as a "x, y, width x height" string:
215CustomObject { myRectProperty: "50,50,100x100" }
218Or use the \l{QtQml::Qt::rect()}{Qt.rect()} function:
221CustomObject { myRectProperty: Qt.rect(50, 50, 100, 100) }
224The \c rect type also exposes read-only \c left, \c right, \c top and \c bottom
225attributes. These are the same as their \l {QRectF}{C++ counterparts}.
227When integrating with C++, note that any QRect or QRectF value
228\l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
229converted into a \c rect value, and vice-versa. When a \c rect value is passed to C++, it
230is automatically converted into a QRectF value.