diff options
Diffstat (limited to 'src/quick/doc/src/qmltypereference.qdoc')
| -rw-r--r-- | src/quick/doc/src/qmltypereference.qdoc | 475 |
1 files changed, 344 insertions, 131 deletions
diff --git a/src/quick/doc/src/qmltypereference.qdoc b/src/quick/doc/src/qmltypereference.qdoc index 9d79ac862b..e1ebca8106 100644 --- a/src/quick/doc/src/qmltypereference.qdoc +++ b/src/quick/doc/src/qmltypereference.qdoc @@ -1,32 +1,8 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\qmlmodule QtQuick 2.\QtMinorVersion +\qmlmodule QtQuick \title Qt Quick QML Types \ingroup qmlmodules \brief Provides graphical QML types. @@ -41,11 +17,11 @@ import QtQuick \endqml Visit the \l {Qt Quick} module documentation for more -information about the concepts which are central to \c QtQuick. +information about the concepts that are central to \c QtQuick. \section1 Submodules - Qt Quick includes several submodules which contain additional types. + Qt Quick includes several submodules that contain additional types: \list \li \l{Qt Quick Local Storage QML Types}{Local Storage} - a submodule @@ -57,17 +33,23 @@ information about the concepts which are central to \c QtQuick. \li \l{Qt Quick Layouts QML Types}{Layouts} - contains types that are used to arrange items in the user interface \li \l{Qt Quick Test QML Types}{Tests} - types for testing QML applications. + \li \l{Qt Quick Effects QML Types}{Effects} - provides types for applying + one or more simple graphical effects to Qt Quick items. + \li \l{Qt Quick Shapes QML Types}{Shapes} - provides types for rendering vector shapes in + a Qt Quick scene. + \li \l{Qt Quick Vector Image QML Types}{Vector Image} - provides types for displaying vector + image files. \endlist -\target basic-types -\section1 Basic Types +\target value-types +\section1 Value Types -There are a number of basic types that are -\l{qtqml-typesystem-basictypes.html#basic-types-provided-by-the-qml-language} +There are a number of value types that are +\l{qtqml-typesystem-valuetypes.html#value-types-provided-by-the-qml-language} {supported by default in the QML language}. -In addition, the \c QtQuick import provides the following basic types: -\annotatedlist qtquickbasictypes +In addition, the \c QtQuick import provides the following value types: +\annotatedlist qtquickvaluetypes \section1 Object Types @@ -80,10 +62,10 @@ available when you import \c QtQuick. */ /*! - \qmlbasictype color - \ingroup qtquickbasictypes + \keyword colorvaluetypedocs + \qmlvaluetype color + \ingroup qtquickvaluetypes \brief an ARGB color value. - \target colorbasictypedocs The \c color type refers to an ARGB color value. It can be specified in a number of ways: @@ -127,7 +109,7 @@ available when you import \c QtQuick. \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically converted into a \c color value, and vice-versa. - This basic type is provided by the QtQuick import. + This value type is provided by the QtQuick import. \section1 SVG Color Reference @@ -136,17 +118,20 @@ available when you import \c QtQuick. \include svg-colors.qdocinc - \sa {QML Basic Types} + \sa {QML Value Types} */ /*! - \qmlbasictype font - \ingroup qtquickbasictypes + \qmlvaluetype font + \ingroup qtquickvaluetypes \brief a font value with the properties of QFont. - \target fontbasictypedocs + \target fontvaluetypedocs The \c font type refers to a font value with the properties of QFont. + Properties of type \c font default to the application's default + \l {Application::font} {font}. + The most commonly used properties are: \list @@ -172,7 +157,9 @@ available when you import \c QtQuick. \li \l bool \c font.kerning \li \l bool \c font.preferShaping \li \l enumeration \c font.hintingPreference + \li \c object \l [QML] {QtQuick::Text::}{font.features} \li \l string \c font.styleName + \li \c object \c [QML] {QtQuick::Text::}{font.variableAxes} \endlist Example: @@ -184,86 +171,55 @@ available when you import \c QtQuick. \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically converted into a \c font value, and vice-versa. - This basic type is provided by the QtQuick import. + This value type is provided by the QtQuick import. - Font weighting is classified on a scale from 0 to 99, where a weight of 0 is ultralight, - and 99 is extremely black. The following values are supported: + Numerical values for font weights follow the CSS specification, where a + weight of 100 is extremely light, and 900 is extremely bold. + The following values are supported: - \table - \row - \li \c Font.Thin - \li 0 - \row - \li \c Font.ExtraLight - \li 12 - \row - \li \c Font.Light - \li 25 - \row - \li \c Font.Normal - \li 50 - \row - \li \c Font.Medium - \li 57 - \row - \li \c Font.DemiBold - \li 63 - \row - \li \c Font.Bold - \li 75 - \row - \li \c Font.ExtraBold - \li 81 - \row - \li \c Font.Black - \li 87 - \endtable + \value Font.Thin 100 + \value Font.ExtraLight 200 + \value Font.Light 300 + \value Font.Normal 400 + \value Font.Medium 500 + \value Font.DemiBold 600 + \value Font.Bold 700 + \value Font.ExtraBold 800 + \value Font.Black 900 Capitalization supports the following values: - \table - \row - \li \c Font.MixedCase - \li No capitalization change is applied. - \row - \li \c Font.AllUppercase - \li Alters the text to be rendered in all uppercase type. - \row - \li \c Font.AllLowercase - \li Alters the text to be rendered in all lowercase type. - \row - \li \c Font.SmallCaps - \li Alters the text to be rendered in small-caps type. - \row - \li \c Font.Capitalize - \li Alters the text to be rendered with the first character of each word as an uppercase character. - \endtable + \value Font.MixedCase No capitalization change is applied. + \value Font.AllUppercase Alters the text to be rendered in all uppercase type. + \value Font.AllLowercase Alters the text to be rendered in all lowercase type. + \value Font.SmallCaps Alters the text to be rendered in small-caps type. + \value Font.Capitalize Alters the text to be rendered with the first character of each word as an uppercase character. Setting the hinting preference only has an effect when using the "NativeRendering" render type. The property supports the following values: - \list - \value Font.PreferDefaultHinting - Use the default hinting level for the target platform. - \value Font.PreferNoHinting - If possible, render text without hinting the outlines - of the glyphs. - \value Font.PreferVerticalHinting - If possible, render text with no horizontal hinting, - but align glyphs to the pixel grid in the vertical direction. - \value Font.PreferFullHinting - If possible, render text with hinting in both horizontal and - vertical directions. - \endlist + \value Font.PreferDefaultHinting Use the default hinting level for the target platform. + \value Font.PreferNoHinting If possible, render text without hinting the outlines of the glyphs. + \value Font.PreferVerticalHinting If possible, render text with no horizontal hinting, + but align glyphs to the pixel grid in the vertical direction. + \value Font.PreferFullHinting If possible, render text with hinting in both horizontal and vertical directions. - \sa {QML Basic Types} + \sa {QML Value Types} */ /*! - \qmlbasictype vector2d - \ingroup qtquickbasictypes + \qmlvaluetype vector2d + \ingroup qtquickvaluetypes \brief A vector2d type has x and y attributes. A \c vector2d type has \c x and \c y attributes, otherwise - it is similar to the \c vector3d type. Please see the - documentation about the \c vector3d type for more information. + it is similar to the \c vector3d type. + + Properties of type \c vector2d have a zero vector as their default value. + This has both \c x and \c y set to \c 0. + + See the documentation about the \c vector3d type for more information. To create a \c vector2d value, specify it as a "x,y" string, or define the components individually, or compose it with @@ -378,18 +334,21 @@ console.log(c + " " + d); // false true \endcode \endtable - This basic type is provided by the QtQuick import. + This value type is provided by the QtQuick import. - \sa {QML Basic Types} + \sa {QML Value Types} */ /*! - \qmlbasictype vector3d - \ingroup qtquickbasictypes + \qmlvaluetype vector3d + \ingroup qtquickvaluetypes \brief a value with x, y, and z attributes. The \c vector3d type refers to a value with \c x, \c y, and \c z attributes. + Properties of type \c vector3d have a zero vector by default. This has + \c x, \c y and \c z set to \c 0. + To create a \c vector3d value, specify it as a "x,y,z" string: \qml @@ -549,20 +508,24 @@ console.log(c + " " + d); // false true \endcode \endtable - This basic type is provided by the QtQuick import. + This value type is provided by the QtQuick import. - \sa {QML Basic Types} + \sa {QML Value Types} */ /*! - \qmlbasictype vector4d - \ingroup qtquickbasictypes + \qmlvaluetype vector4d + \ingroup qtquickvaluetypes \brief A vector4d type has x, y, z and w attributes. A \c vector4d type has \c x, \c y, \c z and \c w attributes, - otherwise it is similar to the \c vector3d type. Please see the - documentation about the \c vector3d type for more information. + otherwise it is similar to the \c vector3d type. + + Properties of type \c vector4d have a zero vector by default. This has + \c x, \c y ,\c z and \c w set to \c 0. + + See the documentation about the \c vector3d type for more information. To create a \c vector4d value, specify it as a "x,y,z,w" string, or define the components individually, or compose it with @@ -690,14 +653,14 @@ console.log(c + " " + d); // false true \endcode \endtable - This basic type is provided by the QtQuick import. + This value type is provided by the QtQuick import. - \sa {QML Basic Types} + \sa {QML Value Types} */ /*! - \qmlbasictype quaternion - \ingroup qtquickbasictypes + \qmlvaluetype quaternion + \ingroup qtquickvaluetypes \brief A quaternion type has scalar, x, y, and z attributes. @@ -707,22 +670,171 @@ console.log(c + " " + d); // false true or define the components individually, or compose it with the Qt.quaternion() function. - This basic type is provided by the QtQuick import. + The quaternion type has the following idempotent functions which can be + invoked in QML: + \table + \header + \li Function Signature + \li Description + \li Example + + \row + \li real dotProduct(quaternion other) + \li Returns the scalar real result of the dot product of \c this quaternion with + the \c other quaternion + \li \code +var a = Qt.quaternion(1,2,3,4); +var b = Qt.quaternion(5,6,7,8); +var c = a.dotProduct(b); +console.log(c); // 70 + \endcode + + \row + \li quaternion times(quaternion other) + \li Returns the quaternion result of multiplying \c this quaternion with + the \c other quaternion, which corresponds to applying both of the rotations + \li \code +var a = Qt.quaternion(1 / Math.sqrt(2), 1 / Math.sqrt(2), 0, 0); +var b = Qt.quaternion(1 / Math.sqrt(2), 0, 1 / Math.sqrt(2), 0); +var c = b.times(a); +console.log(c.toString()); // QQuaternion(0.5, 0.5, 0.5, -0.5) + \endcode + + \row + \li vector3d times(vector3d vector) + \li Returns the vector3d result of rotating the \c vector with \c this quaternion + \li \code +var a = Qt.quaternion(0.5,0.5,0.5,-0.5); +var b = Qt.vector3d(4,5,6); +var c = a.times(b); +console.log(c.toString()); // QVector3D(5, -6, -4) + \endcode + + \row + \li quaternion times(real factor) + \li Returns the quaternion result of multiplying \c this quaternion with the scalar + \c factor + \li \code +var a = Qt.quaternion(1,2,3,4); +var b = 4.48; +var c = a.times(b); +console.log(c.toString()); // QQuaternion(4.48, 8.96, 13.44, 17.92) + \endcode + + \row + \li quaternion plus(quaternion other) + \li Returns the quaternion result of the addition of \c this quaternion with + the \c other quaternion + \li \code +var a = Qt.quaternion(1,2,3,4); +var b = Qt.quaternion(5,6,7,8); +var c = a.plus(b); +console.log(c.toString()); // QQuaternion(6, 8, 10, 12) + \endcode + + \row + \li quaternion minus(quaternion other) + \li Returns the quaternion result of the subtraction of \c other quaternion + from \c this quaternion + \li \code +var a = Qt.quaternion(1,2,3,4); +var b = Qt.quaternion(5,6,7,8); +var c = a.minus(b); +console.log(c.toString()); // QQuaternion(-4, -4, -4, -4) + \endcode + + \row + \li quaternion normalized() + \li Returns the normalized unit form of \c this quaternion + \li \code +var a = Qt.quaternion(1,2,3,4); +var b = a.normalized(); +console.log(b.toString()); // QQuaternion(0.182574, 0.365148, 0.547723, 0.730297) + \endcode - \sa {QML Basic Types} + \row + \li quaternion inverted() + \li Returns the inverse of \c this quaternion + \li \code +var a = Qt.quaternion(0.5,0.5,0.5,-0.5); +var b = a.inverted(); +console.log(b.toString()); // QQuaternion(0.5, -0.5, -0.5, 0.5) + \endcode + + \row + \li quaternion conjugated() + \li Returns the conjugate of \c this quaternion + \li \code +var a = Qt.quaternion(1,2,3,4); +var b = a.conjugated() +console.log(b.toString()); // QQuaternion(1, -2, -3, -4) + \endcode + + \row + \li real length() + \li Returns the scalar real value of the length of \c this quaternion + \li \code +var a = Qt.quaternion(1,2,3,4); +var b = a.length(); +console.log(b.toString()); // 5.477225575051661 + \endcode + + \row + \li vector3d toEulerAngles() + \li Returns the vector3d Euler angles (in degrees) that corresponds to \c this quaternion + \li \code +var a = Qt.quaternion(0.933012,0.25,-0.25,0.066987); +var b = a.toEulerAngles(); +console.log(b.toString()); // QVector3D(30, -30, -4.28846e-05) + \endcode + + \row + \li vector4d toVector4d() + \li Returns the vector4d result of converting \c this quaternion to a vector4d + \li \code +var a = Qt.quaternion(1,2,3,4); +var b = a.toVector4d(); +console.log(b.toString()); // QVector4D(2, 3, 4, 1) + \endcode + + \row + \li bool fuzzyEquals(quaternion other, real epsilon) + \li Returns true if \c this quaternion is approximately equal to the \c other quaternion. + The approximation will be true if each attribute of \c this is within \c epsilon + of \c other. + Note that \c epsilon is an optional argument, the default \c epsilon + is 0.00001. + \li \code +var a = Qt.quaternion(1,2,3,4); +var b = Qt.quaternion(1.0001, 1.9998, 2.0001, 3.9999); +var c = a.fuzzyEquals(b); // default epsilon +var d = a.fuzzyEquals(b, 0.005); // supplied epsilon +console.log(c + " " + d); // false true + \endcode + \endtable + + Properties of type \c quaternion have \c {Qt.quaternion(1, 0, 0, 0)} as their + default value. + + This value type is provided by the QtQuick import. + + \sa {QML Value Types} */ /*! - \qmlbasictype matrix4x4 - \ingroup qtquickbasictypes + \qmlvaluetype matrix4x4 + \ingroup qtquickvaluetypes - \brief A matrix4x4 type is a 4-row and 4-column matrix + \brief A matrix4x4 type is a 4-row and 4-column matrix. A \c matrix4x4 type has sixteen values, each accessible via the properties - \c m11 through \c m44 in QML (in row/column order). Values of this type - can be composed with the Qt.matrix4x4() function. Each attribute in a - matrix4x4 is stored as a real (single-precision on ARM, double-precision - on x86). + \c m11 through \c m44 in QML (in row/column order). Values of this type can + be composed with the Qt.matrix4x4() function. Each attribute in a matrix4x4 + is stored as a real (single-precision on ARM, double-precision on x86). + + A property of type \c matrix4x4 defaults to the identity matrix, whose + diagonal entries \c m11, \c m22, \c m33 and \c m44 are all \c 1, with all + other components \c 0. The matrix4x4 type has the following idempotent functions which can be invoked in QML: @@ -733,6 +845,84 @@ console.log(c + " " + d); // false true \li Example \row + \li translate(vector3d vector) + \li Multiplies \c this matrix4x4 by another that translates coordinates by the components + of \c vector + \li \code +var m = Qt.matrix4x4(); +m.translate(Qt.vector3d(1,2,3)); +console.log(m.toString()); +// QMatrix4x4(1, 0, 0, 1, 0, 1, 0, 2, 0, 0, 1, 3, 0, 0, 0, 1) + \endcode + + \row + \li rotate(real angle, vector3d axis) + \li Multiples \c this matrix4x4 by another that rotates coordinates through + \c angle degrees about \c axis + \li \code +var m = Qt.matrix4x4(); +m.rotate(180,Qt.vector3d(1,0,0)); +console.log(m.toString()); +// QMatrix4x4(1, 0, 0, 0, 0, -1, 0, 0, 0, 0, -1, 0, 0, 0, 0, 1) + \endcode + + \row + \li rotate(quaternion quaternion) + \li Multiples \c this matrix4x4 by another that rotates coordinates according to + a specified \c quaternion. The \c quaternion is assumed to have been normalized. + \li \code +var m = Qt.matrix4x4(); +m.rotate(Qt.quaternion(0.5,0.5,0.5,-0.5)); +console.log(m.toString()); +// QMatrix4x4(0, 1, 0, 0, 0, 0, -1, 0, -1, 0, 0, 0, 0, 0, 0, 1) + \endcode + + \row + \li scale(real factor) + \li Multiplies \c this matrix4x4 by another that scales coordinates by the given \c factor + \li \code +var m = Qt.matrix4x4(); +m.scale(2); +console.log(m.toString()); +// QMatrix4x4(2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 1) + \endcode + + \row + \li scale(real x, real y, real z) + \li Multiplies \c this matrix4x4 by another that scales coordinates by the components + \c x, \c y, and \c z + \li \code +var m = Qt.matrix4x4(); +m.scale(1,2,3); +console.log(m.toString()); +// QMatrix4x4(1, 0, 0, 0, 0, 2, 0, 0, 0, 0, 3, 0, 0, 0, 0, 1) + \endcode + + \row + \li scale(vector3d vector) + \li Multiplies \c this matrix4x4 by another that scales coordinates by the components + of \c vector + \li \code +var m = Qt.matrix4x4(); +m.scale(Qt.vector3d(1,2,3)); +console.log(m.toString()); +// QMatrix4x4(1, 0, 0, 0, 0, 2, 0, 0, 0, 0, 3, 0, 0, 0, 0, 1) + \endcode + + \row + \li lookAt(vector3d eye, vector3d center, vector3d up) + \li Multiplies \c this matrix4x4 by a viewing matrix derived from an \c eye point. + The \c center vector3d indicates the center of the view that the \c eye is looking at. + The \c up vector3d indicates which direction should be considered up with respect to + the \c eye. + \li \code +var m = Qt.matrix4x4(); +m.lookAt(Qt.vector3d(1,2,3),Qt.vector3d(1,2,0),Qt.vector3d(0,1,0)); +console.log(m.toString()); +// QMatrix4x4(1, 0, 0, -1, 0, 1, 0, -2, 0, 0, 1, -3, 0, 0, 0, 1) + \endcode + + \row \li matrix4x4 times(matrix4x4 other) \li Returns the matrix4x4 result of multiplying \c this matrix4x4 with the \c other matrix4x4 @@ -860,6 +1050,29 @@ console.log(b.toString()); \endcode \row + \li rect mapRect(rect) + \li Maps the provided rectangle into the coordinate system defined by this matrix. + If rotation or shearing has been specified, this function returns the bounding rectangle. + This function was introduced in Qt 6.5. + \li \code +var a = Qt.matrix4x4(2,0,0,0,0,2,0,0,0,0,1,0,0,0,0,1); +var b = a.mapRect(Qt.rect(10, 20, 30, 40)); +console.log(b.toString()); +// Qt.rect(20, 40, 60, 80) + \endcode + + \row + \li point map(point) + \li Maps the provided point into the coordinate system defined by this matrix. + This function was introduced in Qt 6.5. + \li \code +var a = Qt.matrix4x4(2,0,0,0,0,2,0,0,0,0,1,0,0,0,0,1); +var b = a.map(10, 20); +console.log(b.toString()); +// Qt.point(20, 40) + \endcode + + \row \li bool fuzzyEquals(matrix4x4 other, real epsilon) \li Returns true if \c this matrix4x4 is approximately equal to the \c other matrix4x4. The approximation will be true if each attribute of \c this is within \c epsilon @@ -877,7 +1090,7 @@ console.log(c + " " + d); // false true \endcode \endtable - This basic type is provided by the QtQuick import. + This value type is provided by the QtQuick import. - \sa {QML Basic Types} + \sa {QML Value Types} */ |