1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
6\title Qt Quick QML Types
8\brief Provides graphical QML types.
10The \l{Qt Quick} module provides graphical primitive types. These types are only
11available in a QML document if that document imports the \c QtQuick namespace.
13To use the module, import the \c QtQuick module with the following statement:
19Visit the \l {Qt Quick} module documentation for more
20information about the concepts that are central to \c QtQuick.
24 Qt Quick includes several submodules that contain additional types:
27 \li \l{Qt Quick Local Storage QML Types}{Local Storage} - a submodule
28 containing a JavaScript interface for an SQLite database
29 \li \l{Qt Quick Particles QML Types}{Particles} - provides a particle
30 system for QML applications
31 \li \l{Qt Quick Controls QML Types}{Controls} - provides a set of reusable
33 \li \l{Qt Quick Layouts QML Types}{Layouts} - contains types that are used
34 to arrange items in the user interface
35 \li \l{Qt Quick Test QML Types}{Tests} - types for testing QML applications.
36 \li \l{Qt Quick Effects QML Types}{Effects} - provides types for applying
37 one or more simple graphical effects to Qt Quick items.
38 \li \l{Qt Quick Shapes QML Types}{Shapes} - provides types for rendering vector shapes in
40 \li \l{Qt Quick Vector Image QML Types}{Vector Image} - provides types for displaying vector
47There are a number of value types that are
48\l{qtqml-typesystem-valuetypes.html#value-types-provided-by-the-qml-language}
49{supported by default in the QML language}.
51In addition, the \c QtQuick import provides the following value types:
52\annotatedlist qtquickvaluetypes
56Most object types provided by the \c QtQuick import are based on the \l{Item}
57type, which itself derives from \l{QtQml::QtObject}{QtObject}. \l{Qt QML QML
58Types#Object Types} {QML object types} provided by the Qt QML module (such as
59\l{QtQml::QtObject}{QtObject} and \l{QtQml::Component}{Component}) are also
60available when you import \c QtQuick.
65 \keyword colorvaluetypedocs
67 \ingroup qtquickvaluetypes
68 \brief an ARGB color value.
70 The \c color type refers to an ARGB color value. It can be specified in a number of ways:
73 \li By a \l{SVG Color Reference}{SVG color name}, such as "red", "green" or "lightsteelblue".
74 \li By a hexadecimal triplet or quad in the form \c "#RRGGBB" and \c "#AARRGGBB"
75 respectively. For example, the color red corresponds to a triplet of \c "#FF0000"
76 and a slightly transparent blue to a quad of \c "#800000FF".
77 \li Using the \l{QtQml::Qt::rgba()}{Qt.rgba()}, \l{QtQml::Qt::hsva()}{Qt.hsva()},
78 \l{QtQml::Qt::hsla()}{Qt.hsla()}, \l{QtQml::Qt::darker()}{Qt.darker()},
79 \l{QtQml::Qt::lighter()}{Qt.lighter()} or \l{QtQml::Qt::tint()}{Qt.tint()} functions.
85 \inlineimage declarative-colors.png
87 \snippet qml/colors.qml colors
89 A color type has \c r, \c g, \c b and \c a properties that refer to the red,
90 green, blue and alpha values of the color, respectively. Additionally it has
91 \c hsvHue, \c hsvSaturation, \c hsvValue and \c hslHue, \c hslSaturation,
92 \c hslLightness properties, which allow access to color values in HSV and HSL
93 color models accordingly:
100 Component.onCompleted: console.log(color.r, color.g, color.b, color.a)
104 To test color values for equality, use the \l{QtQml::Qt::colorEqual()}{Qt.colorEqual()}
105 function. This allows colors to be accurately compared whether they are in property
106 form or in any of the acceptable string specification forms.
108 When integrating with C++, note that any QColor value
109 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
110 converted into a \c color value, and vice-versa.
112 This value type is provided by the QtQuick import.
114 \section1 SVG Color Reference
116 The following table lists the available
117 \l {http://www.w3.org/TR/SVG/types.html#ColorKeywords}{SVG colors}:
119 \include svg-colors.qdocinc
121 \sa {QML Value Types}
126 \ingroup qtquickvaluetypes
127 \brief a font value with the properties of QFont.
128 \target fontvaluetypedocs
130 The \c font type refers to a font value with the properties of QFont.
132 Properties of type \c font default to the application's default
133 \l {Application::font} {font}.
135 The most commonly used properties are:
138 \li \l string \c font.family
139 \li \l bool \c font.bold
140 \li \l bool \c font.italic
141 \li \l bool \c font.underline
142 \li \l real \c font.pointSize
143 \li \l int \c font.pixelSize
146 If both \c pointSize and a \c pixelSize are specified, \c pixelSize will be used.
148 The following properties are also available:
151 \li \l enumeration \c font.weight
152 \li \l bool \c font.overline
153 \li \l bool \c font.strikeout
154 \li \l enumeration \c font.capitalization
155 \li \l real \c font.letterSpacing
156 \li \l real \c font.wordSpacing
157 \li \l bool \c font.kerning
158 \li \l bool \c font.preferShaping
159 \li \l enumeration \c font.hintingPreference
160 \li \c object \l [QML] {QtQuick::Text::}{font.features}
161 \li \l string \c font.styleName
162 \li \c object \c [QML] {QtQuick::Text::}{font.variableAxes}
167 Text { font.family: "Helvetica"; font.pointSize: 13; font.bold: true }
170 When integrating with C++, note that any QFont value
171 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
172 converted into a \c font value, and vice-versa.
174 This value type is provided by the QtQuick import.
176 Numerical values for font weights follow the CSS specification, where a
177 weight of 100 is extremely light, and 900 is extremely bold.
178 The following values are supported:
181 \value Font.ExtraLight 200
182 \value Font.Light 300
183 \value Font.Normal 400
184 \value Font.Medium 500
185 \value Font.DemiBold 600
187 \value Font.ExtraBold 800
188 \value Font.Black 900
190 Capitalization supports the following values:
192 \value Font.MixedCase No capitalization change is applied.
193 \value Font.AllUppercase Alters the text to be rendered in all uppercase type.
194 \value Font.AllLowercase Alters the text to be rendered in all lowercase type.
195 \value Font.SmallCaps Alters the text to be rendered in small-caps type.
196 \value Font.Capitalize Alters the text to be rendered with the first character of each word as an uppercase character.
198 Setting the hinting preference only has an effect when using the "NativeRendering" render type.
199 The property supports the following values:
201 \value Font.PreferDefaultHinting Use the default hinting level for the target platform.
202 \value Font.PreferNoHinting If possible, render text without hinting the outlines of the glyphs.
203 \value Font.PreferVerticalHinting If possible, render text with no horizontal hinting,
204 but align glyphs to the pixel grid in the vertical direction.
205 \value Font.PreferFullHinting If possible, render text with hinting in both horizontal and vertical directions.
207 \sa {QML Value Types}
211 \qmlvaluetype vector2d
212 \ingroup qtquickvaluetypes
214 \brief A vector2d type has x and y attributes.
216 A \c vector2d type has \c x and \c y attributes, otherwise
217 it is similar to the \c vector3d type.
219 Properties of type \c vector2d have a zero vector as their default value.
220 This has both \c x and \c y set to \c 0.
222 See the documentation about the \c vector3d type for more information.
224 To create a \c vector2d value, specify it as a "x,y" string,
225 or define the components individually, or compose it with
226 the Qt.vector2d() function.
228 The vector2d type has the following idempotent functions which can be
232 \li Function Signature
237 \li real dotProduct(vector2d other)
238 \li Returns the scalar real result of the dot product of \c this vector2d with the \c other vector2d
240var a = Qt.vector2d(1,2);
241var b = Qt.vector2d(3,4);
242var c = a.dotProduct(b);
247 \li vector2d times(vector2d other)
248 \li Returns the vector2d result of multiplying \c this vector2d with the \c other vector2d
250var a = Qt.vector2d(1,2);
251var b = Qt.vector2d(3,4);
253console.log(c.toString()); // QVector2D(3, 8)
257 \li vector2d times(real factor)
258 \li Returns the vector2d result of multiplying \c this vector2d with the scalar \c factor
260var a = Qt.vector2d(1,2);
263console.log(c.toString()); // QVector2D(4.48, 8.96)
267 \li vector2d plus(vector2d other)
268 \li Returns the vector2d result of the addition of \c this vector2d with the \c other vector2d
270var a = Qt.vector2d(1,2);
271var b = Qt.vector2d(3,4);
273console.log(c.toString()); // QVector2D(4, 6)
277 \li vector2d minus(vector2d other)
278 \li Returns the vector2d result of the subtraction of \c other vector2d from \c this vector2d
280var a = Qt.vector2d(1,2);
281var b = Qt.vector2d(3,4);
283console.log(c.toString()); // QVector2D(-2, -2)
287 \li vector2d normalized()
288 \li Returns the normalized form of \c this vector
290var a = Qt.vector2d(1,2);
291var b = a.normalized();
292console.log(b.toString()); // QVector2D(0.447214, 0.894427)
297 \li Returns the scalar real value of the length of \c this vector2d
299var a = Qt.vector2d(1,2);
301console.log(b.toString()); // 2.23606797749979
305 \li vector3d toVector3d()
306 \li Returns the vector3d result of converting \c this vector2d to a vector3d
308var a = Qt.vector2d(1,2);
309var b = a.toVector3d();
310console.log(b.toString()); // QVector3D(1, 2, 0)
314 \li vector4d toVector4d()
315 \li Returns the vector4d result of converting \c this vector2d to a vector4d
317var a = Qt.vector2d(1,2);
318var b = a.toVector4d();
319console.log(b.toString()); // QVector4D(1, 2, 0, 0)
323 \li bool fuzzyEquals(vector2d other, real epsilon)
324 \li Returns true if \c this vector2d is approximately equal to the \c other vector2d.
325 The approximation will be true if each attribute of \c this is within \c epsilon
326 of \c other. Note that \c epsilon is an optional argument, the default \c epsilon
329var a = Qt.vector2d(1,2);
330var b = Qt.vector2d(1.0001, 1.9998);
331var c = a.fuzzyEquals(b); // default epsilon
332var d = a.fuzzyEquals(b, 0.005); // supplied epsilon
333console.log(c + " " + d); // false true
337 This value type is provided by the QtQuick import.
339 \sa {QML Value Types}
343 \qmlvaluetype vector3d
344 \ingroup qtquickvaluetypes
345 \brief a value with x, y, and z attributes.
347 The \c vector3d type refers to a value with \c x, \c y, and \c z attributes.
349 Properties of type \c vector3d have a zero vector by default. This has
350 \c x, \c y and \c z set to \c 0.
352 To create a \c vector3d value, specify it as a "x,y,z" string:
355 Rotation { angle: 60; axis: "0,1,0" }
358 or with the \l{QtQml::Qt::vector3d()}{Qt.vector3d()} function:
361 Rotation { angle: 60; axis: Qt.vector3d(0, 1, 0) }
364 or as separate \c x, \c y, and \c z components:
367 Rotation { angle: 60; axis.x: 0; axis.y: 1; axis.z: 0 }
370 Each attribute of a vector3d value is stored internally as a
371 single-precision floating point number (\c float).
373 When integrating with C++, note that any QVector3D value
374 \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
375 converted into a \c vector3d value, and vice-versa.
377 The vector3d type has the following idempotent functions which can be
381 \li Function Signature
386 \li vector3d crossProduct(vector3d other)
387 \li Returns the vector3d result of the cross product of \c this vector3d with the \c other vector3d
389var a = Qt.vector3d(1,2,3);
390var b = Qt.vector3d(4,5,6);
391var c = a.crossProduct(b);
392console.log(c.toString()); // QVector3D(-3, 6, -3)
396 \li real dotProduct(vector3d other)
397 \li Returns the scalar real result of the dot product of \c this vector3d with the \c other vector3d
399var a = Qt.vector3d(1,2,3);
400var b = Qt.vector3d(4,5,6);
401var c = a.dotProduct(b);
406 \li vector3d times(matrix4x4 matrix)
407 \li Returns the vector3d result of transforming \c this vector3d with
408 the 4x4 \c matrix with the matrix applied post-vector
410var a = Qt.vector3d(1,2,3);
411var b = Qt.matrix4x4(4,5,6,7,8,9,10,11,
412 12,13,14,15,16,17,18,19);
414console.log(c.toString());
415// QVector3D(0.774194, 0.849462, 0.924731)
419 \li vector3d times(vector3d other)
420 \li Returns the vector3d result of multiplying \c this vector3d with the \c other vector3d
422var a = Qt.vector3d(1,2,3);
423var b = Qt.vector3d(4,5,6);
425console.log(c.toString()); // QVector3D(4, 10, 18)
429 \li vector3d times(real factor)
430 \li Returns the vector3d result of multiplying \c this vector3d with the scalar \c factor
432var a = Qt.vector3d(1,2,3);
435console.log(c.toString()); // QVector3D(4.48, 8.96, 13.44)
439 \li vector3d plus(vector3d other)
440 \li Returns the vector3d result of the addition of \c this vector3d with the \c other vector3d
442var a = Qt.vector3d(1,2,3);
443var b = Qt.vector3d(4,5,6);
445console.log(c.toString()); // QVector3D(5, 7, 9)
449 \li vector3d minus(vector3d other)
450 \li Returns the vector3d result of the subtraction of \c other vector3d from \c this vector3d
452var a = Qt.vector3d(1,2,3);
453var b = Qt.vector3d(4,5,6);
455console.log(c.toString()); // QVector3D(-3, -3, -3)
459 \li vector3d normalized()
460 \li Returns the normalized form of \c this vector
462var a = Qt.vector3d(1,2,3);
463var b = a.normalized();
464console.log(b.toString());
465// QVector3D(0.267261, 0.534522, 0.801784)
470 \li Returns the scalar real value of the length of \c this vector3d
472var a = Qt.vector3d(1,2,3);
474console.log(b.toString()); // 3.7416573867739413
478 \li vector2d toVector2d()
479 \li Returns the vector2d result of converting \c this vector3d to a vector2d
481var a = Qt.vector3d(1,2,3);
482var b = a.toVector2d();
483console.log(b.toString()); // QVector2D(1, 2)
487 \li vector4d toVector4d()
488 \li Returns the vector4d result of converting \c this vector3d to a vector4d
490var a = Qt.vector3d(1,2,3);
491var b = a.toVector4d();
492console.log(b.toString()); // QVector4D(1, 2, 3, 0)
496 \li bool fuzzyEquals(vector3d other, real epsilon)
497 \li Returns true if \c this vector3d is approximately equal to the \c other vector3d.
498 The approximation will be true if each attribute of \c this is within \c epsilon
500 Note that \c epsilon is an optional argument, the default \c epsilon
503var a = Qt.vector3d(1,2,3);
504var b = Qt.vector3d(1.0001, 1.9998, 2.0001);
505var c = a.fuzzyEquals(b); // default epsilon
506var d = a.fuzzyEquals(b, 0.005); // supplied epsilon
507console.log(c + " " + d); // false true
511 This value type is provided by the QtQuick import.
513 \sa {QML Value Types}
517 \qmlvaluetype vector4d
518 \ingroup qtquickvaluetypes
520 \brief A vector4d type has x, y, z and w attributes.
522 A \c vector4d type has \c x, \c y, \c z and \c w attributes,
523 otherwise it is similar to the \c vector3d type.
525 Properties of type \c vector4d have a zero vector by default. This has
526 \c x, \c y ,\c z and \c w set to \c 0.
528 See the documentation about the \c vector3d type for more information.
530 To create a \c vector4d value, specify it as a "x,y,z,w" string,
531 or define the components individually, or compose it with
532 the Qt.vector4d() function.
534 The vector4d type has the following idempotent functions which can be
538 \li Function Signature
543 \li real dotProduct(vector4d other)
544 \li Returns the scalar real result of the dot product of \c this vector4d with the \c other vector4d
546var a = Qt.vector4d(1,2,3,4);
547var b = Qt.vector4d(5,6,7,8);
548var c = a.dotProduct(b);
553 \li vector4d times(matrix4x4 matrix)
554 \li Returns the vector4d result of transforming \c this vector4d with
555 the 4x4 \c matrix with the matrix applied post-vector
557var a = Qt.vector4d(1,2,3,4);
558var b = Qt.matrix4x4(4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19);
560console.log(c.toString()); // QVector4D(120, 130, 140, 150)
564 \li vector4d times(vector4d other)
565 \li Returns the vector4d result of multiplying \c this vector4d with the \c other vector4d
567var a = Qt.vector4d(1,2,3,4);
568var b = Qt.vector4d(5,6,7,8);
570console.log(c.toString()); // QVector4D(5, 12, 21, 32)
574 \li vector4d times(real factor)
575 \li Returns the vector4d result of multiplying \c this vector4d with the scalar \c factor
577var a = Qt.vector4d(1,2,3,4);
580console.log(c.toString()); // QVector3D(4.48, 8.96,
585 \li vector4d plus(vector4d other)
586 \li Returns the vector4d result of the addition of \c this vector4d with the \c other vector4d
588var a = Qt.vector4d(1,2,3,4);
589var b = Qt.vector4d(5,6,7,8);
591console.log(c.toString()); // QVector4D(6, 8, 10, 12)
595 \li vector4d minus(vector4d other)
596 \li Returns the vector4d result of the subtraction of \c other vector4d from \c this vector4d
598var a = Qt.vector4d(1,2,3,4);
599var b = Qt.vector4d(5,6,7,8);
601console.log(c.toString()); // QVector4D(-4, -4, -4, -4)
605 \li vector4d normalized()
606 \li Returns the normalized form of \c this vector
608var a = Qt.vector4d(1,2,3,4);
609var b = a.normalized();
610console.log(b.toString());
611// QVector4D(0.182574, 0.365148, 0.547723, 0.730297)
616 \li Returns the scalar real value of the length of \c this vector3d
618var a = Qt.vector4d(1,2,3,4);
620console.log(b.toString()); // 5.477225575051661
624 \li vector2d toVector2d()
625 \li Returns the vector2d result of converting \c this vector4d to a vector2d
627var a = Qt.vector4d(1,2,3,4);
628var b = a.toVector2d();
629console.log(b.toString()); // QVector2D(1, 2)
633 \li vector3d toVector3d()
634 \li Returns the vector3d result of converting \c this vector4d to a vector3d
636var a = Qt.vector4d(1,2,3,4);
637var b = a.toVector3d();
638console.log(b.toString()); // QVector3D(1, 2, 3)
642 \li bool fuzzyEquals(vector4d other, real epsilon)
643 \li Returns true if \c this vector4d is approximately equal to the \c other vector4d.
644 The approximation will be true if each attribute of \c this is within \c epsilon
645 of \c other. Note that \c epsilon is an optional argument, the default \c epsilon
648var a = Qt.vector4d(1,2,3,4);
649var b = Qt.vector4d(1.0001, 1.9998, 2.0001, 3.9999);
650var c = a.fuzzyEquals(b); // default epsilon
651var d = a.fuzzyEquals(b, 0.005); // supplied epsilon
652console.log(c + " " + d); // false true
656 This value type is provided by the QtQuick import.
658 \sa {QML Value Types}
662 \qmlvaluetype quaternion
663 \ingroup qtquickvaluetypes
665 \brief A quaternion type has scalar, x, y, and z attributes.
667 A \c quaternion type has \c scalar, \c x, \c y and \c z attributes.
669 To create a \c quaternion value, specify it as a "scalar,x,y,z" string,
670 or define the components individually, or compose it with
671 the Qt.quaternion() function.
673 The quaternion type has the following idempotent functions which can be
677 \li Function Signature
682 \li real dotProduct(quaternion other)
683 \li Returns the scalar real result of the dot product of \c this quaternion with
684 the \c other quaternion
686var a = Qt.quaternion(1,2,3,4);
687var b = Qt.quaternion(5,6,7,8);
688var c = a.dotProduct(b);
693 \li quaternion times(quaternion other)
694 \li Returns the quaternion result of multiplying \c this quaternion with
695 the \c other quaternion, which corresponds to applying both of the rotations
697var a = Qt.quaternion(1 / Math.sqrt(2), 1 / Math.sqrt(2), 0, 0);
698var b = Qt.quaternion(1 / Math.sqrt(2), 0, 1 / Math.sqrt(2), 0);
700console.log(c.toString()); // QQuaternion(0.5, 0.5, 0.5, -0.5)
704 \li vector3d times(vector3d vector)
705 \li Returns the vector3d result of rotating the \c vector with \c this quaternion
707var a = Qt.quaternion(0.5,0.5,0.5,-0.5);
708var b = Qt.vector3d(4,5,6);
710console.log(c.toString()); // QVector3D(5, -6, -4)
714 \li quaternion times(real factor)
715 \li Returns the quaternion result of multiplying \c this quaternion with the scalar
718var a = Qt.quaternion(1,2,3,4);
721console.log(c.toString()); // QQuaternion(4.48, 8.96, 13.44, 17.92)
725 \li quaternion plus(quaternion other)
726 \li Returns the quaternion result of the addition of \c this quaternion with
727 the \c other quaternion
729var a = Qt.quaternion(1,2,3,4);
730var b = Qt.quaternion(5,6,7,8);
732console.log(c.toString()); // QQuaternion(6, 8, 10, 12)
736 \li quaternion minus(quaternion other)
737 \li Returns the quaternion result of the subtraction of \c other quaternion
738 from \c this quaternion
740var a = Qt.quaternion(1,2,3,4);
741var b = Qt.quaternion(5,6,7,8);
743console.log(c.toString()); // QQuaternion(-4, -4, -4, -4)
747 \li quaternion normalized()
748 \li Returns the normalized unit form of \c this quaternion
750var a = Qt.quaternion(1,2,3,4);
751var b = a.normalized();
752console.log(b.toString()); // QQuaternion(0.182574, 0.365148, 0.547723, 0.730297)
756 \li quaternion inverted()
757 \li Returns the inverse of \c this quaternion
759var a = Qt.quaternion(0.5,0.5,0.5,-0.5);
761console.log(b.toString()); // QQuaternion(0.5, -0.5, -0.5, 0.5)
765 \li quaternion conjugated()
766 \li Returns the conjugate of \c this quaternion
768var a = Qt.quaternion(1,2,3,4);
769var b = a.conjugated()
770console.log(b.toString()); // QQuaternion(1, -2, -3, -4)
775 \li Returns the scalar real value of the length of \c this quaternion
777var a = Qt.quaternion(1,2,3,4);
779console.log(b.toString()); // 5.477225575051661
783 \li vector3d toEulerAngles()
784 \li Returns the vector3d Euler angles (in degrees) that corresponds to \c this quaternion
786var a = Qt.quaternion(0.933012,0.25,-0.25,0.066987);
787var b = a.toEulerAngles();
788console.log(b.toString()); // QVector3D(30, -30, -4.28846e-05)
792 \li vector4d toVector4d()
793 \li Returns the vector4d result of converting \c this quaternion to a vector4d
795var a = Qt.quaternion(1,2,3,4);
796var b = a.toVector4d();
797console.log(b.toString()); // QVector4D(2, 3, 4, 1)
801 \li bool fuzzyEquals(quaternion other, real epsilon)
802 \li Returns true if \c this quaternion is approximately equal to the \c other quaternion.
803 The approximation will be true if each attribute of \c this is within \c epsilon
805 Note that \c epsilon is an optional argument, the default \c epsilon
808var a = Qt.quaternion(1,2,3,4);
809var b = Qt.quaternion(1.0001, 1.9998, 2.0001, 3.9999);
810var c = a.fuzzyEquals(b); // default epsilon
811var d = a.fuzzyEquals(b, 0.005); // supplied epsilon
812console.log(c + " " + d); // false true
816 Properties of type \c quaternion have \c {Qt.quaternion(1, 0, 0, 0)} as their
819 This value type is provided by the QtQuick import.
821 \sa {QML Value Types}
825 \qmlvaluetype matrix4x4
826 \ingroup qtquickvaluetypes
828 \brief A matrix4x4 type is a 4-row and 4-column matrix.
830 A \c matrix4x4 type has sixteen values, each accessible via the properties
831 \c m11 through \c m44 in QML (in row/column order). Values of this type can
832 be composed with the Qt.matrix4x4() function. Each attribute in a matrix4x4
833 is stored as a real (single-precision on ARM, double-precision on x86).
835 A property of type \c matrix4x4 defaults to the identity matrix, whose
836 diagonal entries \c m11, \c m22, \c m33 and \c m44 are all \c 1, with all
837 other components \c 0.
839 The matrix4x4 type has the following idempotent functions which can be
843 \li Function Signature
848 \li translate(vector3d vector)
849 \li Multiplies \c this matrix4x4 by another that translates coordinates by the components
852var m = Qt.matrix4x4();
853m.translate(Qt.vector3d(1,2,3));
854console.log(m.toString());
855// QMatrix4x4(1, 0, 0, 1, 0, 1, 0, 2, 0, 0, 1, 3, 0, 0, 0, 1)
859 \li rotate(real angle, vector3d axis)
860 \li Multiples \c this matrix4x4 by another that rotates coordinates through
861 \c angle degrees about \c axis
863var m = Qt.matrix4x4();
864m.rotate(180,Qt.vector3d(1,0,0));
865console.log(m.toString());
866// QMatrix4x4(1, 0, 0, 0, 0, -1, 0, 0, 0, 0, -1, 0, 0, 0, 0, 1)
870 \li rotate(quaternion quaternion)
871 \li Multiples \c this matrix4x4 by another that rotates coordinates according to
872 a specified \c quaternion. The \c quaternion is assumed to have been normalized.
874var m = Qt.matrix4x4();
875m.rotate(Qt.quaternion(0.5,0.5,0.5,-0.5));
876console.log(m.toString());
877// QMatrix4x4(0, 1, 0, 0, 0, 0, -1, 0, -1, 0, 0, 0, 0, 0, 0, 1)
881 \li scale(real factor)
882 \li Multiplies \c this matrix4x4 by another that scales coordinates by the given \c factor
884var m = Qt.matrix4x4();
886console.log(m.toString());
887// QMatrix4x4(2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 1)
891 \li scale(real x, real y, real z)
892 \li Multiplies \c this matrix4x4 by another that scales coordinates by the components
895var m = Qt.matrix4x4();
897console.log(m.toString());
898// QMatrix4x4(1, 0, 0, 0, 0, 2, 0, 0, 0, 0, 3, 0, 0, 0, 0, 1)
902 \li scale(vector3d vector)
903 \li Multiplies \c this matrix4x4 by another that scales coordinates by the components
906var m = Qt.matrix4x4();
907m.scale(Qt.vector3d(1,2,3));
908console.log(m.toString());
909// QMatrix4x4(1, 0, 0, 0, 0, 2, 0, 0, 0, 0, 3, 0, 0, 0, 0, 1)
913 \li lookAt(vector3d eye, vector3d center, vector3d up)
914 \li Multiplies \c this matrix4x4 by a viewing matrix derived from an \c eye point.
915 The \c center vector3d indicates the center of the view that the \c eye is looking at.
916 The \c up vector3d indicates which direction should be considered up with respect to
919var m = Qt.matrix4x4();
920m.lookAt(Qt.vector3d(1,2,3),Qt.vector3d(1,2,0),Qt.vector3d(0,1,0));
921console.log(m.toString());
922// QMatrix4x4(1, 0, 0, -1, 0, 1, 0, -2, 0, 0, 1, -3, 0, 0, 0, 1)
926 \li matrix4x4 times(matrix4x4 other)
927 \li Returns the matrix4x4 result of multiplying \c this matrix4x4 with
928 the \c other matrix4x4
930var a = Qt.matrix4x4(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16);
931var b = Qt.matrix4x4(4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19);
933console.log(c.toString());
934// QMatrix4x4(120, 130, 140, 150, 280, 306, 332, 358, 440, 482,
935//524, 566, 600, 658, 716, 774)
939 \li vector4d times(vector4d vector)
940 \li Returns the vector4d result of transforming the \c vector
941 according to \c this matrix4x4 with the matrix applied
944var a = Qt.matrix4x4(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16);
945var b = Qt.vector4d(5,6,7,8);
947console.log(c.toString()); // QVector4D(70, 174, 278, 382)
951 \li vector3d times(vector3d vector)
952 \li Returns the vector3d result of transforming the \c vector
953 according to \c this matrix4x4 with the matrix applied
956var a = Qt.matrix4x4(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16);
957var b = Qt.vector3d(5,6,7);
959console.log(c.toString()); // QVector3D(0.155556, 0.437037, 0.718518)
963 \li matrix4x4 times(real factor)
964 \li Returns the matrix4x4 result of multiplying \c this matrix4x4 with the scalar \c factor
966var a = Qt.matrix4x4(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16);
969console.log(c.toString());
970// QMatrix4x4(4.48, 8.96, 13.44, 17.92, 22.4, 26.88, 31.36, 35.84,
971// 40.32, 44.8, 49.28, 53.76, 58.24, 62.72, 67.2, 71.68)
975 \li matrix4x4 plus(matrix4x4 other)
976 \li Returns the matrix4x4 result of the addition of \c this matrix4x4 with the \c other matrix4x4
978var a = Qt.matrix4x4(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16);
979var b = Qt.matrix4x4(5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20);
981console.log(c.toString());
982// QMatrix4x4(6, 8, 10, 12, 14, 16, 18, 20, 22,
983// 24, 26, 28, 30, 32, 34, 36)
987 \li matrix4x4 minus(matrix4x4 other)
988 \li Returns the matrix4x4 result of the subtraction of \c other matrix4x4 from \c this matrix4x4
990var a = Qt.matrix4x4(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16);
991var b = Qt.matrix4x4(5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20);
993console.log(c.toString());
994// QMatrix4x4(-4, -4, -4, -4, -4, -4, -4, -4, -4,
995// -4, -4, -4, -4, -4, -4, -4)
999 \li vector4d row(int which)
1000 \li Returns the vector4d row of \c this specified by \c which.
1001 Note: the \c which is 0-based access into the matrix.
1003var a = Qt.matrix4x4(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16);
1004var b = Qt.vector4d(a.m21, a.m22, a.m23, a.m24);
1005var c = a.row(2); // zero based access! so not equal to b
1006console.log(b.toString() + " " + c.toString());
1007// QVector4D(5, 6, 7, 8) QVector4D(9, 10, 11, 12)
1011 \li vector4d column(int which)
1012 \li Returns the vector4d column of \c this specified by \c which.
1013 Note: the \c which is 0-based access into the matrix.
1015var a = Qt.matrix4x4(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16);
1016var b = Qt.vector4d(a.m12, a.m22, a.m32, a.m42);
1017var c = a.column(2); // zero based access! so not equal to b
1018console.log(b.toString() + " " + c.toString());
1019// QVector4D(2, 6, 10, 14) QVector4D(3, 7, 11, 15)
1023 \li real determinant()
1024 \li Returns the determinant of \c this matrix4x4
1026var a = Qt.matrix4x4(1,0,0,0,0,2,0,0,0,0,3,0,100,200,300,1);
1027var b = a.determinant();
1032 \li matrix4x4 inverted()
1033 \li Returns the inverse of \c this matrix4x4 if it exists, else the identity matrix.
1035var a = Qt.matrix4x4(1,0,0,0,0,2,0,0,0,0,3,0,100,200,300,1);
1036var b = a.inverted();
1037console.log(b.toString());
1038// QMatrix4x4(1, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 0.333333, 0, -100,
1043 \li matrix4x4 transposed()
1044 \li Returns the transpose of \c this matrix4x4
1046var a = Qt.matrix4x4(1,0,0,0,0,2,0,0,0,0,3,0,100,200,300,1);
1047var b = a.transposed();
1048console.log(b.toString());
1049// QMatrix4x4(1, 0, 0, 100, 0, 2, 0, 200, 0, 0, 3, 300, 0, 0, 0, 1)
1053 \li rect mapRect(rect)
1054 \li Maps the provided rectangle into the coordinate system defined by this matrix.
1055 If rotation or shearing has been specified, this function returns the bounding rectangle.
1056 This function was introduced in Qt 6.5.
1058var a = Qt.matrix4x4(2,0,0,0,0,2,0,0,0,0,1,0,0,0,0,1);
1059var b = a.mapRect(Qt.rect(10, 20, 30, 40));
1060console.log(b.toString());
1061// Qt.rect(20, 40, 60, 80)
1065 \li point map(point)
1066 \li Maps the provided point into the coordinate system defined by this matrix.
1067 This function was introduced in Qt 6.5.
1069var a = Qt.matrix4x4(2,0,0,0,0,2,0,0,0,0,1,0,0,0,0,1);
1070var b = a.map(10, 20);
1071console.log(b.toString());
1076 \li bool fuzzyEquals(matrix4x4 other, real epsilon)
1077 \li Returns true if \c this matrix4x4 is approximately equal to the \c other matrix4x4.
1078 The approximation will be true if each attribute of \c this is within \c epsilon
1079 of the respective attribute of \c other. Note that \c epsilon is an optional
1080 argument, the default \c epsilon is 0.00001.
1082var a = Qt.matrix4x4(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16);
1083var b = Qt.matrix4x4(1.0001,2.0001,3.0002,4.0003,5.0001,6.0002,
1084 7.0002,8.0004, 9.0001,10.0003,
1085 11.0003,12.0004,13.0001,
1086 14.0002,15.0003,16.0004);
1087var c = a.fuzzyEquals(b); // default epsilon
1088var d = a.fuzzyEquals(b, 0.005); // supplied epsilon
1089console.log(c + " " + d); // false true
1093 This value type is provided by the QtQuick import.
1095 \sa {QML Value Types}