1	// Copyright (C) 2021 The Qt Company Ltd.
2	// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4	#include "qqmlbuiltinfunctions_p.h"
5
6	#include <private/qqmlcomponent_p.h>
7	#include <private/qqmldebugconnector_p.h>
8	#include <private/qqmldebugserviceinterfaces_p.h>
9	#include <private/qqmldelayedcallqueue_p.h>
10	#include <private/qqmlengine_p.h>
11	#include <private/qqmlloggingcategorybase_p.h>
12	#include <private/qqmlplatform_p.h>
13	#include <private/qqmlstringconverters_p.h>
14
15	#include <private/qv4dateobject_p.h>
16	#include <private/qv4engine_p.h>
17	#include <private/qv4functionobject_p.h>
18	#include <private/qv4include_p.h>
19	#include <private/qv4mm_p.h>
20	#include <private/qv4qobjectwrapper_p.h>
21	#include <private/qv4sequenceobject_p.h>
22	#include <private/qv4stackframe_p.h>
23
24	#include <QtQml/qqmlfile.h>
25
26	#include <QtCore/qcoreapplication.h>
27	#include <QtCore/qcryptographichash.h>
28	#include <QtCore/qdatetime.h>
29	#include <QtCore/qfileinfo.h>
30	#include <QtCore/qloggingcategory.h>
31	#include <QtCore/qpoint.h>
32	#include <QtCore/qrect.h>
33	#include <QtCore/qsize.h>
34	#include <QtCore/qstring.h>
35	#include <QtCore/qurl.h>
36
37	QT_BEGIN_NAMESPACE
38
39	Q_LOGGING_CATEGORY(lcRootProperties, "qt.qml.rootObjectProperties");
40	Q_LOGGING_CATEGORY(lcQml, "qml");
41	Q_LOGGING_CATEGORY(lcJs, "js");
42
43	using namespace QV4;
44
45	#define THROW_TYPE_ERROR_WITH_MESSAGE(msg) \
46	do { \
47	return scope.engine->throwTypeError(QString::fromUtf8(msg)); \
48	} while (false)
49
50	/*!
51	\qmltype Qt
52	\inqmlmodule QtQml
53	//! \nativetype QQmlEnginePrivate
54	\ingroup qml-utility-elements
55	\keyword QmlGlobalQtObject
56	\brief Provides a global object with useful enums and functions from Qt.
57
58	\c Qt is a singleton type that provides utility functions, properties, and
59	enums. Here is an example showing how to use this type:
60
61	\qml
62	import QtQuick 2.0
63
64	Text {
65	color: Qt.rgba(1, 0, 0, 1)
66	text: Qt.md5("hello, world")
67	}
68	\endqml
69
70
71	\section1 Enums
72
73	The Qt object contains the enums available in the \l [QtCore]{Qt}{Qt Namespace}. For example, you can access
74	the \l Qt::LeftButton and \l Qt::RightButton enumeration values as \c Qt.LeftButton and \c Qt.RightButton.
75
76
77	\section1 Types
78	\target globalqtobjecttypes
79
80	The Qt object also contains helper functions for creating objects of specific
81	data types. This is primarily useful when setting the properties of an item
82	when the property has one of the following types:
83	\list
84	\li \c rect - use \l{Qt::rect()}{Qt.rect()}
85	\li \c point - use \l{Qt::point()}{Qt.point()}
86	\li \c size - use \l{Qt::size()}{Qt.size()}
87	\endlist
88
89	If the \c QtQuick module has been imported, the following helper functions for
90	creating objects of specific data types are also available for clients to use:
91	\list
92	\li \c color - use \l{Qt::rgba()}{Qt.rgba()}, \l{Qt::hsla()}{Qt.hsla()}, \l{Qt::darker()}{Qt.darker()}, \l{Qt::lighter()}{Qt.lighter()} or \l{Qt::tint()}{Qt.tint()}
93	\li \c font - use \l{Qt::font()}{Qt.font()}
94	\li \c vector2d - use \l{Qt::vector2d()}{Qt.vector2d()}
95	\li \c vector3d - use \l{Qt::vector3d()}{Qt.vector3d()}
96	\li \c vector4d - use \l{Qt::vector4d()}{Qt.vector4d()}
97	\li \c quaternion - use \l{Qt::quaternion()}{Qt.quaternion()}
98	\li \c matrix4x4 - use \l{Qt::matrix4x4()}{Qt.matrix4x4()}
99	\endlist
100
101	\section1 Date/Time Formatters
102
103	The Qt object contains several functions for formatting QDateTime, QDate and QTime values.
104
105	\list
106	\li \l{Qt::formatDateTime}{string Qt.formatDateTime(datetime date, variant format)}
107	\li \l{Qt::formatDate}{string Qt.formatDate(datetime date, variant format)}
108	\li \l{Qt::formatTime}{string Qt.formatTime(datetime date, variant format)}
109	\endlist
110
111	The format specification is described at \l{Qt::formatDateTime}{Qt.formatDateTime}.
112
113
114	\section1 Dynamic Object Creation
115	The following functions on the global object allow you to dynamically create QML
116	items from files or strings. See \l{Dynamic QML Object Creation from JavaScript} for an overview
117	of their use.
118
119	\list
120	\li \l{Qt::createComponent()}{object Qt.createComponent(url)}
121	\li \l{Qt::createQmlObject()}{object Qt.createQmlObject(string qml, object parent, string filepath)}
122	\endlist
123
124
125	\section1 Other Functions
126
127	The following functions are also on the Qt object.
128
129	\list
130	\li \l{Qt::quit()}{Qt.quit()}
131	\li \l{Qt::md5()}{Qt.md5(string)}
132	\li \l{Qt::btoa()}{string Qt.btoa(string)}
133	\li \l{Qt::atob()}{string Qt.atob(string)}
134	\li \l{Qt::binding()}{object Qt.binding(function)}
135	\li \l{Qt::locale()}{object Qt.locale()}
136	\li \l{Qt::resolvedUrl()}{string Qt.resolvedUrl(string)}
137	\li \l{Qt::openUrlExternally()}{Qt.openUrlExternally(string)}
138	\li \l{Qt::fontFamilies()}{list<string> Qt.fontFamilies()}
139	\endlist
140	*/
141
142	/*!
143	\qmlproperty object Qt::platform
144	\since 5.1
145
146	The \c platform object provides info about the underlying platform.
147
148	Its properties are:
149
150	\table
151	\row
152	\li \c platform.os
153	\li
154
155	This read-only property contains the name of the operating system.
156
157	Possible values are:
158
159	\list
160	\li \c "android" - Android
161	\li \c "ios" - iOS
162	\li \c "tvos" - tvOS
163	\li \c "visionos" - visionOS
164	\li \c "linux" - Linux
165	\li \c "osx" - \macos
166	\li \c "qnx" - QNX (since Qt 5.9.3)
167	\li \c "unix" - Other Unix-based OS
168	\li \c "windows" - Windows
169	\li \c "wasm" - WebAssembly
170	\endlist
171
172	\note The property's value on \macos is "osx", regardless of Apple naming convention.
173	The returned value will be updated to "macos" for Qt 7.
174
175	\row
176	\li \c platform.pluginName
177	\li This is the name of the platform set on the QGuiApplication instance
178	as returned by \l QGuiApplication::platformName()
179
180	\endtable
181	*/
182
183	/*!
184	\qmlproperty Application Qt::application
185	\since 5.1
186
187	The \c application object provides access to global application state
188	properties shared by many QML components.
189
190	It is the same as the \l Application singleton.
191
192	The following example uses the \c application object to indicate
193	whether the application is currently active:
194
195	\snippet qml/application.qml document
196
197	\note When using QML without a QGuiApplication, the following properties will be undefined:
198	\list
199	\li application.active
200	\li application.state
201	\li application.layoutDirection
202	\li application.font
203	\endlist
204	*/
205
206	/*!
207	\qmlproperty InputMethod Qt::inputMethod
208	\since 5.0
209
210	It is the same as the \l InputMethod singleton.
211
212	The \c inputMethod object allows access to application's QInputMethod object
213	and all its properties and slots. See the QInputMethod documentation for
214	further details.
215	*/
216
217	/*!
218	\qmlproperty object Qt::styleHints
219	\since 5.5
220
221	The \c styleHints object provides platform-specific style hints and settings.
222	See the \l QStyleHints documentation for further details.
223
224	You should access StyleHints via \l Application::styleHints instead, as
225	this provides better type information for tooling such as the
226	\l {Qt Quick Compiler}.
227
228	\note The \c styleHints object is only available when using the Qt Quick module.
229	*/
230
231	/*!
232	\qmlmethod object Qt::include(string url, jsobject callback)
233	\deprecated
234
235	This method should not be used. Use ECMAScript modules, and the native
236	JavaScript \c import and \c export statements instead.
237
238	Includes another JavaScript file. This method can only be used from within JavaScript files,
239	and not regular QML files.
240
241	This imports all functions from \a url into the current script's namespace.
242
243	Qt.include() returns an object that describes the status of the operation. The object has
244	a single property, \c {status}, that is set to one of the following values:
245
246	\table
247	\header \li Symbol \li Value \li Description
248	\row \li result.OK \li 0 \li The include completed successfully.
249	\row \li result.LOADING \li 1 \li Data is being loaded from the network.
250	\row \li result.NETWORK_ERROR \li 2 \li A network error occurred while fetching the url.
251	\row \li result.EXCEPTION \li 3 \li A JavaScript exception occurred while executing the included code.
252	An additional \c exception property will be set in this case.
253	\endtable
254
255	The \c status property will be updated as the operation progresses.
256
257	If provided, \a callback is invoked when the operation completes. The callback is passed
258	the same object as is returned from the Qt.include() call.
259
260	\warning Using this function is strict mode does not actually put identifier into the
261	current context.
262	*/
263	// Qt.include() is implemented in qv4include.cpp
264
265	QtObject::QtObject(ExecutionEngine *engine)
266	: m_engine(engine)
267	{
268	}
269
270	QtObject::Contexts QtObject::getContexts() const
271	{
272	QQmlEngine *engine = qmlEngine();
273	if (!engine)
274	return {};
275
276	QQmlRefPointer<QQmlContextData> context = v4Engine()->callingQmlContext();
277	if (!context)
278	context = QQmlContextData::get(context: QQmlEnginePrivate::get(e: engine)->rootContext);
279
280	Q_ASSERT(context);
281	QQmlRefPointer<QQmlContextData> effectiveContext
282	= context->isPragmaLibraryContext() ? nullptr : context;
283	return {.context: context, .effectiveContext: effectiveContext};
284	}
285
286	QtObject *QtObject::create(QQmlEngine *, QJSEngine *jsEngine)
287	{
288	QV4::ExecutionEngine *v4 = jsEngine->handle();
289	QV4::Scope scope(v4);
290	ScopedObject globalObject(scope, v4->globalObject);
291	ScopedString qtName(scope, v4->newString(QStringLiteral("Qt")));
292	QV4::ScopedValue result(scope, globalObject->get(id: qtName->toPropertyKey()));
293	return qobject_cast<QtObject *>(object: result->as<QV4::QObjectWrapper>()->object());
294	}
295
296	QJSValue QtObject::include(const QString &url, const QJSValue &callback) const
297	{
298	return QV4Include::method_include(engine: v4Engine(), url: v4Engine()->resolvedUrl(file: url), callbackFunction: callback);
299	}
300
301
302	/*!
303	\qmlmethod bool Qt::isQtObject(object)
304
305	Returns \c true if \a object is a valid reference to a Qt or QML object,
306	\c false otherwise.
307	*/
308	bool QtObject::isQtObject(const QJSValue &value) const
309	{
310	return qjsvalue_cast<QObject *>(value) != nullptr;
311	}
312
313	/*!
314	\qmlmethod color Qt::color(string name)
315
316	Returns the color corresponding to the given \a name (i.e. red or #ff0000).
317	If there is no such color, \c null is returned.
318	*/
319	QVariant QtObject::color(const QString &name) const
320	{
321	bool ok = false;
322	const QVariant v = QQmlStringConverters::colorFromString(name, ok: &ok);
323	if (ok)
324	return v;
325
326	v4Engine()->throwError(QStringLiteral("\"%1\" is not a valid color name").arg(a: name));
327	return QVariant::fromValue(value: nullptr);
328	}
329
330	/*!
331	\qmlmethod color Qt::rgba(real red, real green, real blue, real alpha)
332
333	Returns a color with the specified \a red, \a green, \a blue, and \a alpha
334	components. All components should be in the range 0-1 (inclusive).
335	*/
336	QVariant QtObject::rgba(double r, double g, double b, double a) const
337	{
338	if (r < 0.0) r=0.0;
339	if (r > 1.0) r=1.0;
340	if (g < 0.0) g=0.0;
341	if (g > 1.0) g=1.0;
342	if (b < 0.0) b=0.0;
343	if (b > 1.0) b=1.0;
344	if (a < 0.0) a=0.0;
345	if (a > 1.0) a=1.0;
346
347	return QQml_colorProvider()->fromRgbF(r, g, b, a);
348	}
349
350	/*!
351	\qmlmethod color Qt::hsla(real hue, real saturation, real lightness, real alpha)
352
353	Returns a color with the specified \a hue, \a saturation, \a lightness, and \a alpha
354	components. All components should be in the range 0-1 (inclusive).
355	*/
356	QVariant QtObject::hsla(double h, double s, double l, double a) const
357	{
358	if (h != -1)
359	h = qBound(min: 0.0, val: h, max: 1.0);
360	s = qBound(min: 0.0, val: s, max: 1.0);
361	l = qBound(min: 0.0, val: l, max: 1.0);
362	a = qBound(min: 0.0, val: a, max: 1.0);
363
364	return QQml_colorProvider()->fromHslF(h, s, l, a);
365	}
366
367	/*!
368	\since 5.5
369	\qmlmethod color Qt::hsva(real hue, real saturation, real value, real alpha)
370
371	Returns a color with the specified \a hue, \a saturation, \a value and \a alpha
372	components. All components should be in the range 0-1 (inclusive).
373
374	*/
375	QVariant QtObject::hsva(double h, double s, double v, double a) const
376	{
377	if (h != -1)
378	h = qBound(min: 0.0, val: h, max: 1.0);
379	s = qBound(min: 0.0, val: s, max: 1.0);
380	v = qBound(min: 0.0, val: v, max: 1.0);
381	a = qBound(min: 0.0, val: a, max: 1.0);
382
383	return QQml_colorProvider()->fromHsvF(h, s, v, a);
384	}
385
386	/*!
387	\qmlmethod color Qt::colorEqual(color lhs, string rhs)
388
389	Returns \c true if both \a lhs and \a rhs yield equal color values. Both
390	arguments may be either color values or string values. If a string value
391	is supplied it must be convertible to a color, as described for the
392	\l{colorvaluetypedocs}{color} value type.
393	*/
394	bool QtObject::colorEqual(const QVariant &lhs, const QVariant &rhs) const
395	{
396	bool ok = false;
397
398	QVariant color1 = lhs;
399	if (color1.userType() == QMetaType::QString) {
400	color1 = QQmlStringConverters::colorFromString(color1.toString(), ok: &ok);
401	if (!ok) {
402	v4Engine()->throwError(QStringLiteral("Qt.colorEqual(): Invalid color name"));
403	return false;
404	}
405	} else if (color1.userType() != QMetaType::QColor) {
406	v4Engine()->throwError(QStringLiteral("Qt.colorEqual(): Invalid arguments"));
407	return false;
408	}
409
410	QVariant color2 = rhs;
411	if (color2.userType() == QMetaType::QString) {
412	color2 = QQmlStringConverters::colorFromString(color2.toString(), ok: &ok);
413	if (!ok) {
414	v4Engine()->throwError(QStringLiteral("Qt.colorEqual(): Invalid color name"));
415	return false;
416	}
417	} else if (color2.userType() != QMetaType::QColor) {
418	v4Engine()->throwError(QStringLiteral("Qt.colorEqual(): Invalid arguments"));
419	return false;
420	}
421
422	return color1 == color2;
423	}
424
425	/*!
426	\qmlmethod rect Qt::rect(real x, real y, real width, real height)
427
428	Returns a rect with the top-left corner at \a x, \a y and the specified \a width and \a height.
429	*/
430	QRectF QtObject::rect(double x, double y, double width, double height) const
431	{
432	return QRectF(x, y, width, height);
433	}
434
435	/*!
436	\qmlmethod point Qt::point(real x, real y)
437
438	Returns a point with the specified \a x and \a y coordinates.
439	*/
440	QPointF QtObject::point(double x, double y) const
441	{
442	return QPointF(x, y);
443	}
444
445	/*!
446	\qmlmethod size Qt::size(real width, real height)
447
448	Returns a size with the specified \a width and \a height.
449	*/
450	QSizeF QtObject::size(double w, double h) const
451	{
452	return QSizeF(w, h);
453	}
454
455	/*!
456	\qmlmethod font Qt::font(object fontSpecifier)
457
458	Returns a font with the properties specified in the \a fontSpecifier object
459	or the nearest matching font. The \a fontSpecifier object should contain
460	key-value pairs where valid keys are the \l{fontvaluetypedocs}{font} type's
461	subproperty names, and the values are valid values for each subproperty.
462	Invalid keys will be ignored.
463	*/
464	QVariant QtObject::font(const QJSValue &fontSpecifier) const
465	{
466	if (!fontSpecifier.isObject()) {
467	v4Engine()->throwError(QStringLiteral("Qt.font(): Invalid arguments"));
468	return QVariant();
469	}
470
471	{
472	const QVariant v = QQmlValueTypeProvider::createValueType(
473	fontSpecifier, QMetaType(QMetaType::QFont));
474	if (v.isValid())
475	return v;
476	}
477
478	v4Engine()->throwError(QStringLiteral("Qt.font(): Invalid argument: "
479	"no valid font subproperties specified"));
480	return QVariant();
481	}
482
483	template<typename T>
484	void addParameters(QJSEngine *e, QJSValue &result, int i, T parameter)
485	{
486	result.setProperty(i, e->toScriptValue(parameter));
487	}
488
489	template<>
490	void addParameters<double>(QJSEngine *, QJSValue &result, int i, double parameter)
491	{
492	result.setProperty(arrayIndex: i, value: QJSValue(parameter));
493	}
494
495	template<typename T, typename ...Others>
496	void addParameters(QJSEngine *e, QJSValue &result, int i, T parameter, Others... others)
497	{
498	addParameters<T>(e, result, i, parameter);
499	addParameters<Others...>(e, result, ++i, others...);
500	}
501
502	template<typename ...T>
503	static QVariant constructFromJSValue(QJSEngine *e, QMetaType type, T... parameters)
504	{
505	if (!e)
506	return QVariant();
507	QJSValue params = e->newArray(length: sizeof...(parameters));
508	addParameters(e, params, 0, parameters...);
509	const QVariant variant = QQmlValueTypeProvider::createValueType(params, type);
510	return variant.isValid() ? variant : QVariant(type);
511	}
512
513	/*!
514	\qmlmethod vector2d Qt::vector2d(real x, real y)
515
516	Returns a vector2d with the specified \a x and \a y values.
517	*/
518	QVariant QtObject::vector2d(double x, double y) const
519	{
520	return constructFromJSValue(e: jsEngine(), type: QMetaType(QMetaType::QVector2D), parameters: x, parameters: y);
521	}
522
523	/*!
524	\qmlmethod vector3d Qt::vector3d(real x, real y, real z)
525
526	Returns a vector3d with the specified \a x, \a y, and \a z values.
527	*/
528	QVariant QtObject::vector3d(double x, double y, double z) const
529	{
530	return constructFromJSValue(e: jsEngine(), type: QMetaType(QMetaType::QVector3D), parameters: x, parameters: y, parameters: z);
531	}
532
533	/*!
534	\qmlmethod vector4d Qt::vector4d(real x, real y, real z, real w)
535
536	Returns a vector4d with the specified \a x, \a y, \a z, and \a w values.
537	*/
538	QVariant QtObject::vector4d(double x, double y, double z, double w) const
539	{
540	return constructFromJSValue(e: jsEngine(), type: QMetaType(QMetaType::QVector4D), parameters: x, parameters: y, parameters: z, parameters: w);
541	}
542
543	/*!
544	\qmlmethod quaternion Qt::quaternion(real scalar, real x, real y, real z)
545
546	Returns a quaternion with the specified \a scalar, \a x, \a y, and \a z values.
547	*/
548	QVariant QtObject::quaternion(double scalar, double x, double y, double z) const
549	{
550	return constructFromJSValue(e: jsEngine(), type: QMetaType(QMetaType::QQuaternion), parameters: scalar, parameters: x, parameters: y, parameters: z);
551	}
552
553	/*!
554	\qmlmethod matrix4x4 Qt::matrix4x4()
555
556	Returns an identity matrix4x4.
557	*/
558	QVariant QtObject::matrix4x4() const
559	{
560	const QMetaType metaType(QMetaType::QMatrix4x4);
561	const QVariant variant = QQmlValueTypeProvider::createValueType(QJSValue(), metaType);
562	return variant.isValid() ? variant : QVariant(metaType);
563	}
564
565	/*!
566	\qmlmethod matrix4x4 Qt::matrix4x4(var values)
567
568	Returns a matrix4x4 with the specified \a values. \a values is expected to
569	be a JavaScript array with 16 entries.
570
571	The array indices correspond to positions in the matrix as follows:
572
573	\table
574	\row \li 0 \li 1 \li 2 \li 3
575	\row \li 4 \li 5 \li 6 \li 7
576	\row \li 8 \li 9 \li 10 \li 11
577	\row \li 12 \li 13 \li 14 \li 15
578	\endtable
579	*/
580	QVariant QtObject::matrix4x4(const QJSValue &value) const
581	{
582	if (value.isObject()) {
583	QVariant v = QQmlValueTypeProvider::createValueType(
584	value, QMetaType(QMetaType::QMatrix4x4));
585	if (v.isValid())
586	return v;
587	}
588
589	v4Engine()->throwError(QStringLiteral("Qt.matrix4x4(): Invalid argument: "
590	"not a valid matrix4x4 values array"));
591	return QVariant();
592	}
593
594	/*!
595	\qmlmethod matrix4x4 Qt::matrix4x4(real m11, real m12, real m13, real m14, real m21, real m22, real m23, real m24, real m31, real m32, real m33, real m34, real m41, real m42, real m43, real m44)
596
597	Returns a matrix4x4 with the specified values.
598
599	The arguments correspond to their positions in the matrix:
600
601	\table
602	\row \li \a m11 \li \a m12 \li \a m13 \li \a m14
603	\row \li \a m21 \li \a m22 \li \a m23 \li \a m24
604	\row \li \a m31 \li \a m32 \li \a m33 \li \a m34
605	\row \li \a m41 \li \a m42 \li \a m43 \li \a m44
606	\endtable
607	*/
608	QVariant QtObject::matrix4x4(double m11, double m12, double m13, double m14,
609	double m21, double m22, double m23, double m24,
610	double m31, double m32, double m33, double m34,
611	double m41, double m42, double m43, double m44) const
612	{
613	return constructFromJSValue(e: jsEngine(), type: QMetaType(QMetaType::QMatrix4x4),
614	parameters: m11, parameters: m12, parameters: m13, parameters: m14, parameters: m21, parameters: m22, parameters: m23, parameters: m24,
615	parameters: m31, parameters: m32, parameters: m33, parameters: m34, parameters: m41, parameters: m42, parameters: m43, parameters: m44);
616	}
617
618	static QVariant colorVariantFromJSValue(const QJSValue &color, bool *ok)
619	{
620	QVariant v;
621	if (color.isString()) {
622	v = QQmlStringConverters::colorFromString(color.toString(), ok);
623	if (!(*ok))
624	return QVariant::fromValue(value: nullptr);
625	} else {
626	v = color.toVariant();
627	if (v.userType() != QMetaType::QColor) {
628	*ok = false;
629	return QVariant::fromValue(value: nullptr);
630	}
631	}
632
633	*ok = true;
634	return v;
635	}
636
637	/*!
638	\qmlmethod color Qt::lighter(color baseColor, real factor)
639
640	Returns a color lighter than \a baseColor by the \a factor provided.
641
642	If the factor is greater than 1.0, this functions returns a lighter color.
643	Setting factor to 1.5 returns a color that is 50% brighter. If the factor is less than 1.0,
644	the return color is darker, but we recommend using the Qt.darker() function for this purpose.
645	If the factor is 0 or negative, the return value is unspecified.
646
647	The function converts the current RGB color to HSV, multiplies the value (V) component
648	by factor and converts the color back to RGB.
649
650	If \a factor is not supplied, returns a color that is 50% lighter than \a baseColor (factor 1.5).
651	*/
652	QVariant QtObject::lighter(const QJSValue &color, double factor) const
653	{
654	bool ok;
655	const QVariant v = colorVariantFromJSValue(color, ok: &ok);
656	return ok ? QQml_colorProvider()->lighter(v, factor) : v;
657	}
658
659	/*!
660	\qmlmethod color Qt::darker(color baseColor, real factor)
661
662	Returns a color darker than \a baseColor by the \a factor provided.
663
664	If the factor is greater than 1.0, this function returns a darker color.
665	Setting factor to 3.0 returns a color that has one-third the brightness.
666	If the factor is less than 1.0, the return color is lighter, but we recommend using
667	the Qt.lighter() function for this purpose. If the factor is 0 or negative, the return
668	value is unspecified.
669
670	The function converts the current RGB color to HSV, divides the value (V) component
671	by factor and converts the color back to RGB.
672
673	If \a factor is not supplied, returns a color that is 50% darker than \a baseColor (factor 2.0).
674	*/
675	QVariant QtObject::darker(const QJSValue &color, double factor) const
676	{
677	bool ok;
678	const QVariant v = colorVariantFromJSValue(color, ok: &ok);
679	return ok ? QQml_colorProvider()->darker(v, factor) : v;
680	}
681
682	/*!
683	\qmlmethod color Qt::alpha(color baseColor, real value)
684
685	Returns \a baseColor with an alpha value of \a value.
686
687	\a value is a real ranging from 0 (completely transparent) to 1 (completely opaque).
688	*/
689	QVariant QtObject::alpha(const QJSValue &baseColor, double value) const
690	{
691	bool ok;
692	const QVariant v = colorVariantFromJSValue(color: baseColor, ok: &ok);
693	return ok ? QQml_colorProvider()->alpha(v, value) : v;
694	}
695
696	/*!
697	\qmlmethod color Qt::tint(color baseColor, color tintColor)
698
699	This function allows tinting one color (\a baseColor) with another (\a tintColor).
700
701	The tint color should usually be mostly transparent, or you will not be
702	able to see the underlying color. The below example provides a slight red
703	tint by having the tint color be pure red which is only 1/16th opaque.
704
705	\qml
706	Item {
707	Rectangle {
708	x: 0; width: 80; height: 80
709	color: "lightsteelblue"
710	}
711	Rectangle {
712	x: 100; width: 80; height: 80
713	color: Qt.tint("lightsteelblue", "#10FF0000")
714	}
715	}
716	\endqml
717	\image declarative-rect_tint.png
718
719	Tint is most useful when a subtle change is intended to be conveyed due to some event;
720	you can then use tinting to more effectively tune the visible color.
721	*/
722	QVariant QtObject::tint(const QJSValue &baseColor, const QJSValue &tintColor) const
723	{
724	bool ok;
725
726	// base color
727	const QVariant v1 = colorVariantFromJSValue(color: baseColor, ok: &ok);
728	if (!ok)
729	return v1;
730
731	// tint color
732	const QVariant v2 = colorVariantFromJSValue(color: tintColor, ok: &ok);
733
734	return ok ? QQml_colorProvider()->tint(v1, v2) : v2;
735	}
736
737	namespace {
738	template <typename T>
739	QString formatDateTimeObjectUsingDateFormat(T formatThis, Qt::DateFormat format) {
740	switch (format) {
741	case Qt::TextDate:
742	case Qt::ISODate:
743	case Qt::RFC2822Date:
744	case Qt::ISODateWithMs:
745	return formatThis.toString(format);
746	default: // ### Qt 6: remove once qtbase has removed the rest of the enum !
747	break;
748	}
749	// Q_UNREACHABLE(); // ### Qt 6: restore once the default is gone
750	return QString();
751	}
752	}
753
754	static QTime dateTimeToTime(const QDateTime &dateTime)
755	{
756	return dateTime.toLocalTime().time();
757	}
758
759	/*!
760	\qmlmethod string Qt::formatDate(datetime date, variant format, variant localeFormatOption)
761
762	Returns a string representation of \a date, optionally formatted using \a format.
763
764	The \a date parameter may be a JavaScript \c Date object, a \l{date}{date}
765	property, a QDate, or QDateTime value. The \a format and \a localeFormatOption
766	parameter may be any of the possible format values as described for
767	\l{QtQml::Qt::formatDateTime()}{Qt.formatDateTime()}.
768
769	If \a format is not specified, \a date is formatted using
770	\l {QLocale::FormatType}{Locale.ShortFormat} using the
771	default locale.
772
773	\sa Locale
774	*/
775	static std::optional<QDate> dateFromString(const QString &string, QV4::ExecutionEngine *engine)
776	{
777	{
778	const QDate date = QDate::fromString(string, format: Qt::ISODate);
779	if (date.isValid())
780	return date;
781	}
782
783	{
784	// For historical reasons, the string argument is parsed as datetime, not as only date
785	const QDateTime dateTime = QDateTime::fromString(string, format: Qt::ISODate);
786	if (dateTime.isValid()) {
787	qCWarning(lcRootProperties())
788	<< string << "is a date/time string being passed to formatDate()."
789	<< "You should only pass date strings to formatDate().";
790	return dateTime.date();
791	}
792	}
793
794	{
795	// Since we can coerce QDate to QString, allow the resulting string format here.
796	const QDateTime dateTime = DateObject::stringToDateTime(string, engine);
797	if (dateTime.isValid())
798	return DateObject::dateTimeToDate(dateTime);
799	}
800
801	engine->throwError(QStringLiteral("Invalid argument passed to formatDate(): %1").arg(a: string));
802	return std::nullopt;
803	}
804
805	QString QtObject::formatDate(QDate date, const QString &format) const
806	{
807	return date.toString(format);
808	}
809
810	QString QtObject::formatDate(QDate date, Qt::DateFormat format) const
811	{
812	return formatDateTimeObjectUsingDateFormat(formatThis: date, format);
813	}
814
815	QString QtObject::formatDate(const QDateTime &dateTime, const QString &format) const
816	{
817	return DateObject::dateTimeToDate(dateTime).toString(format);
818	}
819
820	QString QtObject::formatDate(const QString &string, const QString &format) const
821	{
822	if (const auto qDate = dateFromString(string, engine: v4Engine()))
823	return formatDate(date: qDate.value(), format);
824
825	return QString();
826	}
827
828	QString QtObject::formatDate(const QDateTime &dateTime, Qt::DateFormat format) const
829	{
830	return formatDateTimeObjectUsingDateFormat(formatThis: DateObject::dateTimeToDate(dateTime), format);
831	}
832
833	QString QtObject::formatDate(const QString &string, Qt::DateFormat format) const
834	{
835	if (const auto qDate = dateFromString(string, engine: v4Engine()))
836	return formatDate(date: qDate.value(), format);
837
838	return QString();
839	}
840
841	#if QT_CONFIG(qml_locale)
842	QString QtObject::formatDate(QDate date, const QLocale &locale,
843	QLocale::FormatType formatType) const
844	{
845	return locale.toString(date, format: formatType);
846	}
847
848	QString QtObject::formatDate(const QDateTime &dateTime, const QLocale &locale,
849	QLocale::FormatType formatType) const
850	{
851	return locale.toString(date: DateObject::dateTimeToDate(dateTime), format: formatType);
852	}
853
854	QString QtObject::formatDate(const QString &string, const QLocale &locale,
855	QLocale::FormatType formatType) const
856	{
857	if (const auto qDate = dateFromString(string, engine: v4Engine()))
858	return locale.toString(date: qDate.value(), format: formatType);
859
860	return QString();
861	}
862	#endif
863
864	/*!
865	\qmlmethod string Qt::formatTime(datetime time, variant format, variant localeFormatOption)
866
867	Returns a string representation of \a time, optionally formatted using
868	\a format, and, if provided, \a localeFormatOption.
869
870	The \a time parameter may be a JavaScript \c Date object, a QTime, or QDateTime
871	value. The \a format and \a localeFormatOption parameter may be any of the
872	possible format values as described for
873	\l{QtQml::Qt::formatDateTime()}{Qt.formatDateTime()}.
874
875	If \a format is not specified, \a time is formatted using
876	\l {QLocale::FormatType}{Locale.ShortFormat} using the default locale.
877
878	\sa Locale
879	*/
880	static std::optional<QTime> timeFromString(const QString &string, QV4::ExecutionEngine *engine)
881	{
882	{
883	const QTime time = QTime::fromString(string, format: Qt::ISODate);
884	if (time.isValid())
885	return time;
886	}
887
888	{
889	// For historical reasons, the string argument is parsed as datetime, not as only time
890	const QDateTime dateTime = QDateTime::fromString(string, format: Qt::ISODate);
891	if (dateTime.isValid()) {
892	qCWarning(lcRootProperties())
893	<< string << "is a date/time string being passed to formatTime()."
894	<< "You should only pass time strings to formatTime().";
895	return dateTime.time();
896	}
897	}
898
899	{
900	// Since we can coerce QTime to QString, allow the resulting string format here.
901	const QDateTime dateTime = DateObject::stringToDateTime(string, engine);
902	if (dateTime.isValid())
903	return dateTimeToTime(dateTime);
904	}
905
906	engine->throwError(QStringLiteral("Invalid argument passed to formatTime(): %1").arg(a: string));
907	return std::nullopt;
908	}
909
910	QString QtObject::formatTime(QTime time, const QString &format) const
911	{
912	return time.toString(format);
913	}
914
915	QString QtObject::formatTime(const QDateTime &dateTime, const QString &format) const
916	{
917	return dateTimeToTime(dateTime).toString(format);
918	}
919
920	QString QtObject::formatTime(const QString &time, const QString &format) const
921	{
922
923	if (auto qTime = timeFromString(string: time, engine: v4Engine()))
924	return formatTime(time: qTime.value(), format);
925
926	return QString();
927	}
928
929	QString QtObject::formatTime(QTime time, Qt::DateFormat format) const
930	{
931	return formatDateTimeObjectUsingDateFormat(formatThis: time, format);
932	}
933
934	QString QtObject::formatTime(const QDateTime &dateTime, Qt::DateFormat format) const
935	{
936	return formatDateTimeObjectUsingDateFormat(formatThis: dateTimeToTime(dateTime), format);
937	}
938
939	QString QtObject::formatTime(const QString &time, Qt::DateFormat format) const
940	{
941	if (auto qTime = timeFromString(string: time, engine: v4Engine()))
942	return formatTime(time: qTime.value(), format);
943
944	return QString();
945	}
946
947	#if QT_CONFIG(qml_locale)
948	QString QtObject::formatTime(QTime time, const QLocale &locale,
949	QLocale::FormatType formatType) const
950	{
951	return locale.toString(time, format: formatType);
952	}
953
954	QString QtObject::formatTime(const QDateTime &dateTime, const QLocale &locale,
955	QLocale::FormatType formatType) const
956	{
957	return locale.toString(time: dateTimeToTime(dateTime), format: formatType);
958	}
959
960	QString QtObject::formatTime(const QString &time, const QLocale &locale,
961	QLocale::FormatType formatType) const
962	{
963	if (auto qTime = timeFromString(string: time, engine: v4Engine()))
964	return locale.toString(time: qTime.value(), format: formatType);
965
966	return QString();
967	}
968	#endif
969
970	/*!
971	\qmlmethod string Qt::formatDateTime(datetime dateTime, variant format, variant localeFormatOption)
972
973	Returns a string representation of \a dateTime, optionally formatted using
974	\a format and \a localeFormatOption.
975
976	The \a dateTime parameter may be a JavaScript \c Date object, a \l{date}{date}
977	property, a QDate, QTime, or QDateTime value.
978
979	If \a format is not provided, \a dateTime is formatted using
980	\l {QLocale::FormatType}{Locale.ShortFormat} using the
981	default locale. Otherwise, \a format should be either:
982
983	\list
984	\li One of the Qt::DateFormat enumeration values, such as
985	\c Qt.RFC2822Date or \c Qt.ISODate.
986	\li A string that specifies the format of the returned string, as detailed below.
987	\li A \c locale object.
988	\endlist
989
990	If \a format specifies a locale object, \dateTime is formatted
991	with \l{QLocale::toString}. In this case, \a localeFormatOption can hold a value
992	of type \l {QLocale::FormatType} to further tune the formatting. If none is
993	provided, \l {QLocale::FormatType}{Locale.ShortFormat} is used.
994
995	If \a format specifies a format string, it should use the following expressions
996	to specify the date:
997
998	\table
999	\header \li Expression \li Output
1000	\row \li d \li the day as number without a leading zero (1 to 31)
1001	\row \li dd \li the day as number with a leading zero (01 to 31)
1002	\row \li ddd
1003	\li the abbreviated localized day name (e.g. 'Mon' to 'Sun').
1004	Uses QDate::shortDayName().
1005	\row \li dddd
1006	\li the long localized day name (e.g. 'Monday' to 'Qt::Sunday').
1007	Uses QDate::longDayName().
1008	\row \li M \li the month as number without a leading zero (1-12)
1009	\row \li MM \li the month as number with a leading zero (01-12)
1010	\row \li MMM
1011	\li the abbreviated localized month name (e.g. 'Jan' to 'Dec').
1012	Uses QDate::shortMonthName().
1013	\row \li MMMM
1014	\li the long localized month name (e.g. 'January' to 'December').
1015	Uses QDate::longMonthName().
1016	\row \li yy \li the year as two digit number (00-99)
1017	\row \li yyyy \li the year as four digit number
1018	\endtable
1019
1020	In addition the following expressions can be used to specify the time:
1021
1022	\table
1023	\header \li Expression \li Output
1024	\row \li h
1025	\li the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display)
1026	\row \li hh
1027	\li the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display)
1028	\row \li m \li the minute without a leading zero (0 to 59)
1029	\row \li mm \li the minute with a leading zero (00 to 59)
1030	\row \li s \li the second without a leading zero (0 to 59)
1031	\row \li ss \li the second with a leading zero (00 to 59)
1032	\row \li z \li the milliseconds without leading zeroes (0 to 999)
1033	\row \li zzz \li the milliseconds with leading zeroes (000 to 999)
1034	\row \li AP
1035	\li use AM/PM display. \e AP will be replaced by either "AM" or "PM".
1036	\row \li ap
1037	\li use am/pm display. \e ap will be replaced by either "am" or "pm".
1038	\row \li t
1039	\li include a time-zone indicator.
1040	\endtable
1041
1042	All other input characters will be ignored. Any sequence of characters that
1043	are enclosed in single quotes will be treated as text and not be used as an
1044	expression. Two consecutive single quotes ("''") are replaced by a single quote
1045	in the output.
1046
1047	For example, if the following date/time value was specified:
1048
1049	\code
1050	// 21 May 2001 14:13:09
1051	var dateTime = new Date(2001, 5, 21, 14, 13, 09)
1052	\endcode
1053
1054	This \a dateTime value could be passed to \c Qt.formatDateTime(),
1055	\l {QtQml::Qt::formatDate()}{Qt.formatDate()} or \l {QtQml::Qt::formatTime()}{Qt.formatTime()}
1056	with the \a format values below to produce the following results:
1057
1058	\table
1059	\header \li Format \li Result
1060	\row \li "dd.MM.yyyy" \li 21.05.2001
1061	\row \li "ddd MMMM d yy" \li Tue May 21 01
1062	\row \li "hh:mm:ss.zzz" \li 14:13:09.042
1063	\row \li "h:m:s ap" \li 2:13:9 pm
1064	\endtable
1065
1066	\sa Locale
1067	*/
1068	static std::optional<QDateTime> dateTimeFromString(const QString &string, QV4::ExecutionEngine *engine)
1069	{
1070	{
1071	const QDateTime dateTime = QDateTime::fromString(string, format: Qt::ISODate);
1072	if (dateTime.isValid())
1073	return dateTime;
1074	}
1075
1076	{
1077	// Since we can coerce QDateTime to QString, allow the resulting string format here.
1078	const QDateTime dateTime = DateObject::stringToDateTime(string, engine);
1079	if (dateTime.isValid())
1080	return dateTime;
1081	}
1082
1083	engine->throwError(QStringLiteral("Invalid argument passed to formatDateTime(): %1").arg(a: string));
1084	return std::nullopt;
1085	}
1086
1087	QString QtObject::formatDateTime(const QDateTime &dateTime, const QString &format) const
1088	{
1089	return dateTime.toString(format);
1090	}
1091
1092	QString QtObject::formatDateTime(const QString &string, const QString &format) const
1093	{
1094
1095	if (const auto qDateTime = dateTimeFromString(string, engine: v4Engine()))
1096	return formatDateTime(dateTime: qDateTime.value(), format);
1097
1098	return QString();
1099	}
1100
1101	QString QtObject::formatDateTime(const QDateTime &dateTime, Qt::DateFormat format) const
1102	{
1103	return formatDateTimeObjectUsingDateFormat(formatThis: dateTime, format);
1104	}
1105
1106	QString QtObject::formatDateTime(const QString &string, Qt::DateFormat format) const
1107	{
1108
1109	if (const auto qDateTime = dateTimeFromString(string, engine: v4Engine()))
1110	return formatDateTime(dateTime: qDateTime.value(), format);
1111
1112	return QString();
1113	}
1114
1115	#if QT_CONFIG(qml_locale)
1116	QString QtObject::formatDateTime(const QDateTime &dateTime, const QLocale &locale,
1117	QLocale::FormatType formatType) const
1118	{
1119	return locale.toString(dateTime, format: formatType);
1120	}
1121
1122	QString QtObject::formatDateTime(const QString &string, const QLocale &locale,
1123	QLocale::FormatType formatType) const
1124	{
1125
1126	if (const auto qDateTime = dateTimeFromString(string, engine: v4Engine()))
1127	return formatDateTime(dateTime: qDateTime.value(), locale, formatType);
1128
1129	return QString();
1130	}
1131	#endif
1132
1133	/*!
1134	\qmlmethod bool Qt::openUrlExternally(url target)
1135
1136	Attempts to open the specified \a target url in an external application, based on the user's
1137	desktop preferences. Returns \c true if it succeeds, \c false otherwise.
1138
1139	\warning A return value of \c true indicates that the application has successfully requested
1140	the operating system to open the URL in an external application. The external application may
1141	still fail to launch or fail to open the requested URL. This result will not be reported back
1142	to the application.
1143	*/
1144	bool QtObject::openUrlExternally(const QUrl &url) const
1145	{
1146	return QQml_guiProvider()->openUrlExternally(resolvedUrl(url));
1147	}
1148
1149	/*!
1150	\qmlmethod url Qt::url(url url)
1151
1152	Returns \a url verbatim. This can be used to force a type coercion to \c url.
1153	In contrast to Qt.resolvedUrl() this retains any relative URLs. As strings
1154	are implicitly converted to urls, the function can be called with a string
1155	as argument, and will then return a url.
1156
1157	\sa resolvedUrl()
1158	*/
1159	QUrl QtObject::url(const QUrl &url) const
1160	{
1161	return url;
1162	}
1163
1164	/*!
1165	\qmlmethod url Qt::resolvedUrl(url url)
1166
1167	Returns \a url resolved relative to the URL of the caller.
1168
1169	If there is no caller or the caller is not associated with a QML context,
1170	returns \a url resolved relative to the QML engine's base URL. If the QML
1171	engine has no base URL, just returns \a url.
1172
1173	\sa url()
1174	*/
1175	QUrl QtObject::resolvedUrl(const QUrl &url) const
1176	{
1177	if (QQmlRefPointer<QQmlContextData> ctxt = v4Engine()->callingQmlContext())
1178	return ctxt->resolvedUrl(url);
1179	if (QQmlEngine *engine = qmlEngine())
1180	return engine->baseUrl().resolved(relative: url);
1181	return url;
1182	}
1183
1184	/*!
1185	\qmlmethod url Qt::resolvedUrl(url url, object context)
1186
1187	Returns \a url resolved relative to the URL of the QML context of
1188	\a context. If \a context is not associated with a QML context,
1189	returns \a url resolved relative to the QML engine's base URL. If
1190	the QML engine has no base URL, just returns \a url.
1191
1192	\sa url()
1193	*/
1194	QUrl QtObject::resolvedUrl(const QUrl &url, QObject *context) const
1195	{
1196	if (context) {
1197	QQmlData *data = QQmlData::get(object: context);
1198	if (data && data->outerContext)
1199	return data->outerContext->resolvedUrl(url);
1200	}
1201
1202	if (QQmlEngine *engine = qmlEngine())
1203	return engine->baseUrl().resolved(relative: url);
1204	return url;
1205	}
1206
1207	/*!
1208	\qmlmethod list<string> Qt::fontFamilies()
1209
1210	Returns a list of the font families available to the application.
1211	*/
1212	QStringList QtObject::fontFamilies() const
1213	{
1214	return QQml_guiProvider()->fontFamilies();
1215	}
1216
1217	/*!
1218	\qmlmethod string Qt::md5(data)
1219	Returns a hex string of the md5 hash of \a data.
1220	*/
1221	QString QtObject::md5(const QString &data) const
1222	{
1223	return QLatin1String(QCryptographicHash::hash(data: data.toUtf8(), method: QCryptographicHash::Md5).toHex());
1224	}
1225
1226	/*!
1227	\qmlmethod string Qt::btoa(data)
1228	Binary to ASCII - this function returns a base64 encoding of \a data.
1229	*/
1230	QString QtObject::btoa(const QString &data) const
1231	{
1232	return QLatin1String(data.toUtf8().toBase64());
1233	}
1234
1235	/*!
1236	\qmlmethod string Qt::atob(data)
1237	ASCII to binary - this function decodes the base64 encoded \a data string and returns it.
1238	*/
1239	QString QtObject::atob(const QString &data) const
1240	{
1241	return QString::fromUtf8(ba: QByteArray::fromBase64(base64: data.toLatin1()));
1242	}
1243
1244	/*!
1245	\qmlmethod Qt::quit()
1246
1247	This function causes the QQmlEngine::quit() signal to be emitted.
1248	Within the \l {Prototyping with the QML Runtime Tool}{qml tool},
1249	this causes the launcher application to exit; to quit a C++ application
1250	when this method is called, connect the QQmlEngine::quit() signal to the
1251	QCoreApplication::quit() slot.
1252
1253	\sa exit()
1254	*/
1255	void QtObject::quit() const
1256	{
1257	if (QQmlEngine *engine = qmlEngine())
1258	QQmlEnginePrivate::get(e: engine)->sendQuit();
1259	}
1260
1261	/*!
1262	\qmlmethod Qt::exit(int retCode)
1263
1264	This function causes the QQmlEngine::exit(int) signal to be emitted.
1265	Within the \l {Prototyping with the QML Runtime Tool}{qml tool},
1266	this causes the launcher application to exit with
1267	the specified return code (\a retCode). To exit from the event loop with a specified
1268	return code when this method is called, a C++ application can connect the
1269	QQmlEngine::exit(int) signal to the QCoreApplication::exit(int) slot.
1270
1271	\sa quit()
1272	*/
1273	void QtObject::exit(int retCode) const
1274	{
1275	if (QQmlEngine *engine = qmlEngine())
1276	QQmlEnginePrivate::get(e: engine)->sendExit(retCode);
1277	}
1278
1279	/*!
1280	\qmlmethod object Qt::createQmlObject(string qml, object parent, string filepath)
1281
1282	Returns a new object created from the given \a qml string which will have the specified \a parent,
1283	or \c null if there was an error in creating the object.
1284
1285	If \a filepath is specified, it will be used for error reporting for the created object.
1286
1287	Example (where \c parentItem is the id of an existing QML item):
1288
1289	\snippet qml/createQmlObject.qml 0
1290
1291	In the case of an error, a QQmlError object is thrown. This object has an additional property,
1292	\c qmlErrors, which is an array of the errors encountered.
1293	Each object in this array has the members \c lineNumber, \c columnNumber, \c fileName and \c message.
1294	For example, if the above snippet had misspelled color as 'colro' then the array would contain an object like the following:
1295	{ "lineNumber" : 1, "columnNumber" : 32, "fileName" : "dynamicSnippet1", "message" : "Cannot assign to non-existent property \"colro\""}.
1296
1297	\note This function returns immediately, and therefore may not work if
1298	the \a qml string loads new components (that is, external QML files that have not yet been loaded).
1299	If this is the case, consider using \l{QtQml::Qt::createComponent()}{Qt.createComponent()} instead.
1300
1301	\warning This function is extremely slow since it has to compile the passed QML string every time
1302	it is invoked. Furthermore, it's very easy to produce invalid QML when programmatically constructing
1303	QML code. It's much better to keep your QML components as separate files and add properties and
1304	methods to customize their behavior than to produce new components by string manipulation.
1305
1306	See \l {Dynamic QML Object Creation from JavaScript} for more information on using this function.
1307	*/
1308	QObject *QtObject::createQmlObject(const QString &qml, QObject *parent, const QUrl &url) const
1309	{
1310	QQmlEngine *engine = qmlEngine();
1311	if (!engine) {
1312	v4Engine()->throwError(QStringLiteral("Qt.createQmlObject(): "
1313	"Can only be called on a QML engine."));
1314	return nullptr;
1315	}
1316
1317	struct Error {
1318	static ReturnedValue create(QV4::ExecutionEngine *v4, const QList<QQmlError> &errors) {
1319	Scope scope(v4);
1320	QString errorstr;
1321	// '+=' reserves extra capacity. Follow-up appending will be probably free.
1322	errorstr += QLatin1String("Qt.createQmlObject(): failed to create object: ");
1323
1324	QV4::ScopedArrayObject qmlerrors(scope, v4->newArrayObject());
1325	QV4::ScopedObject qmlerror(scope);
1326	QV4::ScopedString s(scope);
1327	QV4::ScopedValue v(scope);
1328	for (int ii = 0; ii < errors.size(); ++ii) {
1329	const QQmlError &error = errors.at(i: ii);
1330	errorstr += QLatin1String("\n ") + error.toString();
1331	qmlerror = v4->newObject();
1332	qmlerror->put(name: (s = v4->newString(QStringLiteral("lineNumber"))), v: (v = QV4::Value::fromInt32(i: error.line())));
1333	qmlerror->put(name: (s = v4->newString(QStringLiteral("columnNumber"))), v: (v = QV4::Value::fromInt32(i: error.column())));
1334	qmlerror->put(name: (s = v4->newString(QStringLiteral("fileName"))), v: (v = v4->newString(s: error.url().toString())));
1335	qmlerror->put(name: (s = v4->newString(QStringLiteral("message"))), v: (v = v4->newString(s: error.description())));
1336	qmlerrors->put(idx: ii, v: qmlerror);
1337	}
1338
1339	v = v4->newString(s: errorstr);
1340	ScopedObject errorObject(scope, v4->newErrorObject(value: v));
1341	errorObject->put(name: (s = v4->newString(QStringLiteral("qmlErrors"))), v: qmlerrors);
1342	return errorObject.asReturnedValue();
1343	}
1344	};
1345
1346	QQmlRefPointer<QQmlContextData> context = v4Engine()->callingQmlContext();
1347	if (!context)
1348	context = QQmlContextData::get(context: QQmlEnginePrivate::get(e: engine)->rootContext);
1349
1350	Q_ASSERT(context);
1351	QQmlContext *effectiveContext = nullptr;
1352	if (context->isPragmaLibraryContext())
1353	effectiveContext = engine->rootContext();
1354	else
1355	effectiveContext = context->asQQmlContext();
1356	Q_ASSERT(effectiveContext);
1357
1358	if (qml.isEmpty())
1359	return nullptr;
1360
1361	QUrl resolvedUrl = url;
1362	if (url.isValid() && url.isRelative())
1363	resolvedUrl = context->resolvedUrl(url);
1364
1365	if (!parent) {
1366	v4Engine()->throwError(QStringLiteral("Qt.createQmlObject(): Missing parent object"));
1367	return nullptr;
1368	}
1369
1370	QQmlRefPointer<QQmlTypeData> typeData = QQmlEnginePrivate::get(e: engine)->typeLoader.getType(
1371	qml.toUtf8(), url: resolvedUrl, mode: QQmlTypeLoader::Synchronous);
1372	Q_ASSERT(typeData->isCompleteOrError());
1373	QQmlComponent component(engine);
1374	QQmlComponentPrivate *componentPrivate = QQmlComponentPrivate::get(c: &component);
1375	componentPrivate->fromTypeData(data: typeData);
1376	componentPrivate->progress = 1.0;
1377
1378	Scope scope(v4Engine());
1379	if (component.isError()) {
1380	ScopedValue v(scope, Error::create(v4: scope.engine, errors: component.errors()));
1381	scope.engine->throwError(value: v);
1382	return nullptr;
1383	}
1384
1385	if (!component.isReady()) {
1386	v4Engine()->throwError(QStringLiteral("Qt.createQmlObject(): Component is not ready"));
1387	return nullptr;
1388	}
1389
1390	if (!effectiveContext->isValid()) {
1391	v4Engine()->throwError(QStringLiteral("Qt.createQmlObject(): Cannot create a component "
1392	"in an invalid context"));
1393	return nullptr;
1394	}
1395
1396	QObject *obj = component.beginCreate(effectiveContext);
1397	if (obj) {
1398	QQmlData::get(object: obj, create: true)->explicitIndestructibleSet = false;
1399	QQmlData::get(object: obj)->indestructible = false;
1400
1401	obj->setParent(parent);
1402
1403	QList<QQmlPrivate::AutoParentFunction> functions = QQmlMetaType::parentFunctions();
1404	for (int ii = 0; ii < functions.size(); ++ii) {
1405	if (QQmlPrivate::Parented == functions.at(i: ii)(obj, parent))
1406	break;
1407	}
1408	}
1409	component.completeCreate();
1410
1411	if (component.isError()) {
1412	ScopedValue v(scope, Error::create(v4: scope.engine, errors: component.errors()));
1413	scope.engine->throwError(value: v);
1414	return nullptr;
1415	}
1416
1417	Q_ASSERT(obj);
1418	return obj;
1419	}
1420
1421	/*!
1422	\qmlmethod Component Qt::createComponent(url url, enumeration mode, QtObject parent)
1423
1424	Returns a \l Component object created using the QML file at the specified \a url,
1425	or \c null if an empty string was given.
1426
1427	The returned component's \l Component::status property indicates whether the
1428	component was successfully created. If the status is \c Component.Error,
1429	see \l Component::errorString() for an error description.
1430
1431	If the optional \a mode parameter is set to \c Component.Asynchronous, the
1432	component will be loaded in a background thread. The Component::status property
1433	will be \c Component.Loading while it is loading. The status will change to
1434	\c Component.Ready if the component loads successfully, or \c Component.Error
1435	if loading fails. This parameter defaults to \c Component.PreferSynchronous
1436	if omitted.
1437
1438	If \a mode is set to \c Component.PreferSynchronous, Qt will attempt to load
1439	the component synchronously, but may end up loading it asynchronously if
1440	necessary. Scenarios that may cause asynchronous loading include, but are not
1441	limited to, the following:
1442
1443	\list
1444	\li The URL refers to a network resource
1445	\li The component is being created as a result of another component that is
1446	being loaded asynchronously
1447	\endlist
1448
1449	If the optional \a parent parameter is given, it should refer to the object
1450	that will become the parent for the created \l Component object. If no mode
1451	was passed, this can be the second argument.
1452
1453	Call \l {Component::createObject()}{Component.createObject()} on the returned
1454	component to create an object instance of the component.
1455
1456	For example:
1457
1458	\snippet qml/createComponent-simple.qml 0
1459
1460	See \l {Dynamic QML Object Creation from JavaScript} for more information on using this function.
1461
1462	To create a QML object from an arbitrary string of QML (instead of a file),
1463	use \l{QtQml::Qt::createQmlObject()}{Qt.createQmlObject()}.
1464	*/
1465
1466	/*!
1467	\since 6.5
1468	\qmlmethod Component Qt::createComponent(string moduleUri, string typeName, enumeration mode, QtObject parent)
1469	\overload
1470	Returns a \l Component object created for the type specified by \a moduleUri and \a typeName.
1471	\qml
1472	import QtQml
1473	QtObject {
1474	id: root
1475	property Component myComponent: Qt.createComponent("QtQuick", "Rectangle", Component.Asynchronous, root)
1476	}
1477	\endqml
1478	This overload mostly behaves as the \c url based version, but can be used
1479	to instantiate types which do not have an URL (e.g. C++ types registered
1480	via \l {QML_ELEMENT}).
1481	\note In some cases, passing \c Component.Asynchronous won't have any
1482	effect:
1483	\list
1484	\li The type is implemented in C++
1485	\li The type is an inline component.
1486	\endlist
1487	If the optional \a parent parameter is given, it should refer to the object
1488	that will become the parent for the created \l Component object. If no mode
1489	was passed, this can be the second argument.
1490	*/
1491
1492	QQmlComponent *QtObject::createComponent(const QUrl &url, QObject *parent) const
1493	{
1494	return createComponent(url, mode: QQmlComponent::PreferSynchronous, parent);
1495	}
1496
1497	QQmlComponent *QtObject::createComponent(const QUrl &url, QQmlComponent::CompilationMode mode,
1498	QObject *parent) const
1499	{
1500	if (mode != QQmlComponent::Asynchronous && mode != QQmlComponent::PreferSynchronous) {
1501	v4Engine()->throwError(QStringLiteral("Invalid compilation mode %1").arg(a: mode));
1502	return nullptr;
1503	}
1504
1505	if (url.isEmpty())
1506	return nullptr;
1507
1508	QQmlEngine *engine = qmlEngine();
1509	if (!engine)
1510	return nullptr;
1511
1512	auto [context, effectiveContext] = getContexts();
1513	if (!context)
1514	return nullptr;
1515
1516	QQmlComponent *c = new QQmlComponent(engine, context->resolvedUrl(url), mode, parent);
1517	QQmlComponentPrivate::get(c)->creationContext = effectiveContext;
1518	QQmlData::get(object: c, create: true)->explicitIndestructibleSet = false;
1519	QQmlData::get(object: c)->indestructible = false;
1520	return c;
1521	}
1522
1523	QQmlComponent *QtObject::createComponent(const QString &moduleUri, const QString &typeName,
1524	QObject *parent) const
1525	{
1526	return createComponent(moduleUri, typeName, mode: QQmlComponent::PreferSynchronous, parent);
1527	}
1528
1529	QQmlComponent *QtObject::createComponent(const QString &moduleUri, const QString &typeName, QQmlComponent::CompilationMode mode, QObject *parent) const
1530	{
1531	if (mode != QQmlComponent::Asynchronous && mode != QQmlComponent::PreferSynchronous) {
1532	v4Engine()->throwError(QStringLiteral("Invalid compilation mode %1").arg(a: mode));
1533	return nullptr;
1534	}
1535
1536	QQmlEngine *engine = qmlEngine();
1537	if (!engine)
1538	return nullptr;
1539
1540	if (moduleUri.isEmpty() || typeName.isEmpty())
1541	return nullptr;
1542
1543	auto [context, effectiveContext] = getContexts();
1544	if (!context)
1545	return nullptr;
1546
1547	QQmlComponent *c = new QQmlComponent(engine, moduleUri, typeName, mode, parent);
1548	if (c->isError() && !parent && moduleUri.endsWith(s: u".qml")) {
1549	v4Engine()->throwTypeError(
1550	QStringLiteral("Invalid arguments; did you swap mode and parent"));
1551	}
1552	QQmlComponentPrivate::get(c)->creationContext = effectiveContext;
1553	QQmlData::get(object: c, create: true)->explicitIndestructibleSet = false;
1554	QQmlData::get(object: c)->indestructible = false;
1555	return c;
1556	}
1557
1558	#if QT_CONFIG(translation)
1559	QString QtObject::uiLanguage() const
1560	{
1561	if (const QJSEngine *e = jsEngine())
1562	return e->uiLanguage();
1563	return QString();
1564	}
1565
1566	void QtObject::setUiLanguage(const QString &uiLanguage)
1567	{
1568	if (QJSEngine *e = jsEngine())
1569	e->setUiLanguage(uiLanguage);
1570	}
1571
1572	QBindable<QString> QtObject::uiLanguageBindable()
1573	{
1574	if (QJSEngine *e = jsEngine())
1575	return QBindable<QString>(&QJSEnginePrivate::get(e)->uiLanguage);
1576	return QBindable<QString>();
1577	}
1578	#endif
1579
1580	#if QT_CONFIG(qml_locale)
1581	/*!
1582	\qmlmethod Qt::locale(name)
1583
1584	Returns a JS object representing the locale with the specified
1585	\a name, which has the format "language[_territory][.codeset][@modifier]"
1586	or "C", where:
1587
1588	\list
1589	\li \c language is a lowercase, two-letter, ISO 639 language code,
1590	\li \c territory is an uppercase, two-letter, ISO 3166 country code, and
1591	\li \c codeset and \c modifier are ignored.
1592	\endlist
1593
1594	If the string violates the locale format, or language is not a
1595	valid ISO 369 code, the "C" locale is used instead. If country
1596	is not present, or is not a valid ISO 3166 code, the most
1597	appropriate country is chosen for the specified language.
1598
1599	\sa Locale
1600	*/
1601	QLocale QtObject::locale() const
1602	{
1603	return QLocale();
1604	}
1605
1606	QLocale QtObject::locale(const QString &name) const
1607	{
1608	return QLocale(name);
1609	}
1610	#endif
1611
1612	void Heap::QQmlBindingFunction::init(const QV4::JavaScriptFunctionObject *bindingFunction)
1613	{
1614	Scope scope(bindingFunction->engine());
1615	ScopedContext context(scope, bindingFunction->scope());
1616	JavaScriptFunctionObject::init(scope: context, function: bindingFunction->function());
1617	this->bindingFunction.set(e: internalClass->engine, newVal: bindingFunction->d());
1618	}
1619
1620	ReturnedValue QQmlBindingFunction::virtualCall(
1621	const FunctionObject *f, const Value *, const Value *, int)
1622	{
1623	// Mark this as a callable object, so that we can perform the binding magic on it.
1624	return f->engine()->throwTypeError(QStringLiteral("Bindings must not be called directly."));
1625	}
1626
1627	QQmlSourceLocation QQmlBindingFunction::currentLocation() const
1628	{
1629	QV4::CppStackFrame *frame = engine()->currentStackFrame;
1630	if (frame->v4Function) // synchronous loading:
1631	return QQmlSourceLocation(frame->source(), frame->lineNumber(), 0);
1632	else // async loading:
1633	return bindingFunction()->function->sourceLocation();
1634	}
1635
1636	DEFINE_OBJECT_VTABLE(QQmlBindingFunction);
1637
1638	/*!
1639	\qmlmethod Qt::binding(function)
1640
1641	Returns a JavaScript object representing a \l{Property Binding}{property binding},
1642	with a \a function that evaluates the binding.
1643
1644	There are two main use-cases for the function: firstly, to apply a
1645	property binding imperatively from JavaScript code:
1646
1647	\snippet qml/qtBinding.1.qml 0
1648
1649	and secondly, to apply a property binding when initializing property values
1650	of dynamically constructed objects (via \l{Component::createObject()}
1651	{Component.createObject()} or \l{Loader::setSource()}{Loader.setSource()}).
1652
1653	For example, assuming the existence of a DynamicText component:
1654	\snippet qml/DynamicText.qml 0
1655
1656	the output from:
1657	\snippet qml/qtBinding.2.qml 0
1658
1659	and from:
1660	\snippet qml/qtBinding.3.qml 0
1661
1662	should both be:
1663	\code
1664	Root text extra text
1665	Modified root text extra text
1666	Dynamic text extra text
1667	Modified dynamic text extra text
1668	\endcode
1669
1670	This function cannot be used in property binding declarations
1671	(see the documentation on \l{qml-javascript-assignment}{binding
1672	declarations and binding assignments}) except when the result is
1673	stored in an array bound to a var property.
1674
1675	\snippet qml/qtBinding.4.qml 0
1676
1677	\since 5.0
1678	*/
1679	QJSValue QtObject::binding(const QJSValue &function) const
1680	{
1681	const QV4::JavaScriptFunctionObject *f
1682	= QJSValuePrivate::asManagedType<JavaScriptFunctionObject>(jsval: &function);
1683	QV4::ExecutionEngine *e = v4Engine();
1684	if (!f) {
1685	return QJSValuePrivate::fromReturnedValue(
1686	d: e->throwError(
1687	QStringLiteral(
1688	"binding(): argument (binding expression) must be a function")));
1689	}
1690
1691	return QJSValuePrivate::fromReturnedValue(
1692	d: Encode(e->memoryManager->allocate<QQmlBindingFunction>(args&: f)));
1693	}
1694
1695	void QtObject::callLater(QQmlV4FunctionPtr args)
1696	{
1697	m_engine->delayedCallQueue()->addUniquelyAndExecuteLater(engine: m_engine, args);
1698	}
1699
1700
1701	QQmlPlatform *QtObject::platform()
1702	{
1703	if (!m_platform)
1704	m_platform = new QQmlPlatform(this);
1705	return m_platform;
1706	}
1707
1708	QQmlApplication *QtObject::application()
1709	{
1710	if (!m_application)
1711	// Only allocate an application object once
1712	m_application = QQml_guiProvider()->application(parent: this);
1713
1714	return m_application;
1715	}
1716
1717	QObject *QtObject::inputMethod() const
1718	{
1719	return QQml_guiProvider()->inputMethod();
1720	}
1721
1722	QObject *QtObject::styleHints() const
1723	{
1724	return QQml_guiProvider()->styleHints();
1725	}
1726
1727	void QV4::Heap::ConsoleObject::init()
1728	{
1729	Object::init();
1730	QV4::Scope scope(internalClass->engine);
1731	QV4::ScopedObject o(scope, this);
1732
1733	o->defineDefaultProperty(QStringLiteral("debug"), code: QV4::ConsoleObject::method_log);
1734	o->defineDefaultProperty(QStringLiteral("log"), code: QV4::ConsoleObject::method_log);
1735	o->defineDefaultProperty(QStringLiteral("info"), code: QV4::ConsoleObject::method_info);
1736	o->defineDefaultProperty(QStringLiteral("warn"), code: QV4::ConsoleObject::method_warn);
1737	o->defineDefaultProperty(QStringLiteral("error"), code: QV4::ConsoleObject::method_error);
1738	o->defineDefaultProperty(QStringLiteral("assert"), code: QV4::ConsoleObject::method_assert);
1739
1740	o->defineDefaultProperty(QStringLiteral("count"), code: QV4::ConsoleObject::method_count);
1741	o->defineDefaultProperty(QStringLiteral("profile"), code: QV4::ConsoleObject::method_profile);
1742	o->defineDefaultProperty(QStringLiteral("profileEnd"), code: QV4::ConsoleObject::method_profileEnd);
1743	o->defineDefaultProperty(QStringLiteral("time"), code: QV4::ConsoleObject::method_time);
1744	o->defineDefaultProperty(QStringLiteral("timeEnd"), code: QV4::ConsoleObject::method_timeEnd);
1745	o->defineDefaultProperty(QStringLiteral("trace"), code: QV4::ConsoleObject::method_trace);
1746	o->defineDefaultProperty(QStringLiteral("exception"), code: QV4::ConsoleObject::method_exception);
1747	}
1748
1749
1750	enum ConsoleLogTypes {
1751	Log,
1752	Info,
1753	Warn,
1754	Error
1755	};
1756
1757	static QString jsStack(QV4::ExecutionEngine *engine) {
1758	QString stack;
1759
1760	int i = 0;
1761	for (CppStackFrame *f = engine->currentStackFrame; f && i < 10; f = f->parentFrame(), ++i) {
1762	QString stackFrame;
1763
1764	if (f->isJSTypesFrame() && static_cast<JSTypesStackFrame *>(f)->isTailCalling()) {
1765	stackFrame = QStringLiteral("[elided tail calls]");
1766	} else {
1767	const int line = f->lineNumber();
1768	if (line != f->missingLineNumber()) {
1769	stackFrame = QStringLiteral("%1 (%2:%3)").arg(
1770	args: f->function(), args: f->source(), args: QString::number(qAbs(t: line)));
1771	} else {
1772	stackFrame = QStringLiteral("%1 (%2)").arg(
1773	args: f->function(), args: f->source());
1774	}
1775	}
1776
1777	if (i)
1778	stack += QLatin1Char('\n');
1779	stack += stackFrame;
1780	}
1781	return stack;
1782	}
1783
1784	static QString serializeArray(Object *array, ExecutionEngine *v4, QSet<QV4::Heap::Object *> &alreadySeen) {
1785	Scope scope(v4);
1786	ScopedValue val(scope);
1787	QString result;
1788	alreadySeen.insert(value: array->d());
1789
1790	ScopedObject detached(scope);
1791	if (Sequence *reference = array->as<Sequence>())
1792	detached = ReferenceObject::detached(ref: reference->d());
1793	else
1794	detached = array;
1795
1796	result += QLatin1Char('[');
1797	const uint length = detached->getLength();
1798	for (uint i = 0; i < length; ++i) {
1799	if (i != 0)
1800	result += QLatin1Char(',');
1801	val = detached->get(idx: i);
1802	if (val->isManaged() && val->managed()->isArrayLike())
1803	if (!alreadySeen.contains(value: val->objectValue()->d()))
1804	result += serializeArray(array: val->objectValue(), v4, alreadySeen);
1805	else
1806	result += QLatin1String("[Circular]");
1807	else
1808	result += val->toQStringNoThrow();
1809	}
1810	result += QLatin1Char(']');
1811
1812	alreadySeen.remove(value: array->d());
1813	return result;
1814	};
1815
1816	static ReturnedValue writeToConsole(const FunctionObject *b, const Value *argv, int argc,
1817	ConsoleLogTypes logType, bool printStack = false)
1818	{
1819	const QLoggingCategory *loggingCategory = nullptr;
1820	QString result;
1821	QV4::Scope scope(b);
1822	QV4::ExecutionEngine *v4 = scope.engine;
1823
1824	int start = 0;
1825	if (argc > 0) {
1826	if (const QObjectWrapper* wrapper = argv[0].as<QObjectWrapper>()) {
1827	if (QQmlLoggingCategoryBase *category
1828	= qobject_cast<QQmlLoggingCategoryBase *>(object: wrapper->object())) {
1829	if (category->category())
1830	loggingCategory = category->category();
1831	else
1832	THROW_GENERIC_ERROR("A QmlLoggingCatgory was provided without a valid name");
1833	start = 1;
1834	}
1835	}
1836	}
1837
1838
1839	for (int i = start, ei = argc; i < ei; ++i) {
1840	if (i != start)
1841	result.append(c: QLatin1Char(' '));
1842
1843	QSet<QV4::Heap::Object *> alreadySeenElements;
1844	if (argv[i].isManaged() && argv[i].managed()->isArrayLike())
1845	result.append(s: serializeArray(array: argv[i].objectValue(), v4, alreadySeen&: alreadySeenElements));
1846	else
1847	result.append(s: argv[i].toQStringNoThrow());
1848	}
1849
1850	if (printStack)
1851	result += QLatin1Char('\n') + jsStack(engine: v4);
1852
1853	if (!loggingCategory)
1854	loggingCategory = v4->qmlEngine() ? &lcQml() : &lcJs();
1855	QV4::CppStackFrame *frame = v4->currentStackFrame;
1856	const QByteArray baSource = frame ? frame->source().toUtf8() : QByteArray();
1857	const QByteArray baFunction = frame ? frame->function().toUtf8() : QByteArray();
1858	QMessageLogger logger(baSource.constData(), frame ? frame->lineNumber() : 0,
1859	baFunction.constData(), loggingCategory->categoryName());
1860
1861	switch (logType) {
1862	case Log:
1863	if (loggingCategory->isDebugEnabled())
1864	logger.debug(msg: "%s", result.toUtf8().constData());
1865	break;
1866	case Info:
1867	if (loggingCategory->isInfoEnabled())
1868	logger.info(msg: "%s", result.toUtf8().constData());
1869	break;
1870	case Warn:
1871	if (loggingCategory->isWarningEnabled())
1872	logger.warning(msg: "%s", result.toUtf8().constData());
1873	break;
1874	case Error:
1875	if (loggingCategory->isCriticalEnabled())
1876	logger.critical(msg: "%s", result.toUtf8().constData());
1877	break;
1878	default:
1879	break;
1880	}
1881
1882	return Encode::undefined();
1883	}
1884
1885	DEFINE_OBJECT_VTABLE(ConsoleObject);
1886
1887	ReturnedValue ConsoleObject::method_error(const FunctionObject *b, const Value *, const Value *argv, int argc)
1888	{
1889	return writeToConsole(b, argv, argc, logType: Error);
1890	}
1891
1892	ReturnedValue ConsoleObject::method_log(const FunctionObject *b, const Value *, const Value *argv, int argc)
1893	{
1894	//console.log
1895	//console.debug
1896	//print
1897	return writeToConsole(b, argv, argc, logType: Log);
1898	}
1899
1900	ReturnedValue ConsoleObject::method_info(const FunctionObject *b, const Value *, const Value *argv, int argc)
1901	{
1902	return writeToConsole(b, argv, argc, logType: Info);
1903	}
1904
1905	ReturnedValue ConsoleObject::method_profile(const FunctionObject *b, const Value *, const Value *, int)
1906	{
1907	QV4::Scope scope(b);
1908	QV4::ExecutionEngine *v4 = scope.engine;
1909
1910	QV4::CppStackFrame *frame = v4->currentStackFrame;
1911	const QByteArray baSource = frame->source().toUtf8();
1912	const QByteArray baFunction = frame->function().toUtf8();
1913	QMessageLogger logger(baSource.constData(), frame->lineNumber(), baFunction.constData());
1914	QQmlProfilerService *service = QQmlDebugConnector::service<QQmlProfilerService>();
1915	if (!service) {
1916	logger.warning(msg: "Cannot start profiling because debug service is disabled. Start with -qmljsdebugger=port:XXXXX.");
1917	} else {
1918	service->startProfiling(engine: v4->jsEngine());
1919	logger.debug(msg: "Profiling started.");
1920	}
1921
1922	return QV4::Encode::undefined();
1923	}
1924
1925	ReturnedValue ConsoleObject::method_profileEnd(const FunctionObject *b, const Value *, const Value *, int)
1926	{
1927	QV4::Scope scope(b);
1928	QV4::ExecutionEngine *v4 = scope.engine;
1929
1930	QV4::CppStackFrame *frame = v4->currentStackFrame;
1931	const QByteArray baSource = frame->source().toUtf8();
1932	const QByteArray baFunction = frame->function().toUtf8();
1933	QMessageLogger logger(baSource.constData(), frame->lineNumber(), baFunction.constData());
1934
1935	QQmlProfilerService *service = QQmlDebugConnector::service<QQmlProfilerService>();
1936	if (!service) {
1937	logger.warning(msg: "Ignoring console.profileEnd(): the debug service is disabled.");
1938	} else {
1939	service->stopProfiling(engine: v4->jsEngine());
1940	logger.debug(msg: "Profiling ended.");
1941	}
1942
1943	return QV4::Encode::undefined();
1944	}
1945
1946	ReturnedValue ConsoleObject::method_time(const FunctionObject *b, const Value *, const Value *argv, int argc)
1947	{
1948	QV4::Scope scope(b);
1949	if (argc != 1)
1950	THROW_GENERIC_ERROR("console.time(): Invalid arguments");
1951
1952	QString name = argv[0].toQStringNoThrow();
1953	scope.engine->startTimer(timerName: name);
1954	return QV4::Encode::undefined();
1955	}
1956
1957	ReturnedValue ConsoleObject::method_timeEnd(const FunctionObject *b, const Value *, const Value *argv, int argc)
1958	{
1959	QV4::Scope scope(b);
1960	if (argc != 1)
1961	THROW_GENERIC_ERROR("console.timeEnd(): Invalid arguments");
1962
1963	QString name = argv[0].toQStringNoThrow();
1964	bool wasRunning;
1965	qint64 elapsed = scope.engine->stopTimer(timerName: name, wasRunning: &wasRunning);
1966	if (wasRunning) {
1967	qDebug(msg: "%s: %llims", qPrintable(name), elapsed);
1968	}
1969	return QV4::Encode::undefined();
1970	}
1971
1972	ReturnedValue ConsoleObject::method_count(const FunctionObject *b, const Value *, const Value *argv, int argc)
1973	{
1974	// first argument: name to print. Ignore any additional arguments
1975	QString name;
1976	if (argc > 0)
1977	name = argv[0].toQStringNoThrow();
1978
1979	Scope scope(b);
1980	QV4::ExecutionEngine *v4 = scope.engine;
1981
1982	QV4::CppStackFrame *frame = v4->currentStackFrame;
1983
1984	QString scriptName = frame->source();
1985
1986	int value = v4->consoleCountHelper(file: scriptName, line: frame->lineNumber(), column: 0);
1987	QString message = name + QLatin1String(": ") + QString::number(value);
1988
1989	QMessageLogger(qPrintable(scriptName), frame->lineNumber(),
1990	qPrintable(frame->function()))
1991	.debug(msg: "%s", qPrintable(message));
1992
1993	return QV4::Encode::undefined();
1994	}
1995
1996	ReturnedValue ConsoleObject::method_trace(const FunctionObject *b, const Value *, const Value *, int argc)
1997	{
1998	QV4::Scope scope(b);
1999	if (argc != 0)
2000	THROW_GENERIC_ERROR("console.trace(): Invalid arguments");
2001
2002	QV4::ExecutionEngine *v4 = scope.engine;
2003
2004	QString stack = jsStack(engine: v4);
2005
2006	QV4::CppStackFrame *frame = v4->currentStackFrame;
2007	QMessageLogger(frame->source().toUtf8().constData(), frame->lineNumber(),
2008	frame->function().toUtf8().constData())
2009	.debug(catFunc: v4->qmlEngine() ? lcQml : lcJs, msg: "%s", qPrintable(stack));
2010
2011	return QV4::Encode::undefined();
2012	}
2013
2014	ReturnedValue ConsoleObject::method_warn(const FunctionObject *b, const Value *, const Value *argv, int argc)
2015	{
2016	return writeToConsole(b, argv, argc, logType: Warn);
2017	}
2018
2019	ReturnedValue ConsoleObject::method_assert(const FunctionObject *b, const Value *, const Value *argv, int argc)
2020	{
2021	QV4::Scope scope(b);
2022	if (argc == 0)
2023	THROW_GENERIC_ERROR("console.assert(): Missing argument");
2024
2025	QV4::ExecutionEngine *v4 = scope.engine;
2026
2027	if (!argv[0].toBoolean()) {
2028	QString message;
2029	for (int i = 1, ei = argc; i < ei; ++i) {
2030	if (i != 1)
2031	message.append(c: QLatin1Char(' '));
2032
2033	message.append(s: argv[i].toQStringNoThrow());
2034	}
2035
2036	QString stack = jsStack(engine: v4);
2037
2038	QV4::CppStackFrame *frame = v4->currentStackFrame;
2039	QMessageLogger(frame->source().toUtf8().constData(), frame->lineNumber(),
2040	frame->function().toUtf8().constData())
2041	.critical(msg: "%s\n%s",qPrintable(message), qPrintable(stack));
2042
2043	}
2044	return QV4::Encode::undefined();
2045	}
2046
2047	ReturnedValue ConsoleObject::method_exception(const FunctionObject *b, const Value *, const Value *argv, int argc)
2048	{
2049	QV4::Scope scope(b);
2050	if (argc == 0)
2051	THROW_GENERIC_ERROR("console.exception(): Missing argument");
2052
2053	return writeToConsole(b, argv, argc, logType: Error, printStack: true);
2054	}
2055
2056	void QV4::GlobalExtensions::init(Object *globalObject, QJSEngine::Extensions extensions)
2057	{
2058	ExecutionEngine *v4 = globalObject->engine();
2059	Scope scope(v4);
2060
2061	if (extensions.testFlag(flag: QJSEngine::TranslationExtension)) {
2062	#if QT_CONFIG(translation)
2063	globalObject->defineDefaultProperty(QStringLiteral("qsTranslate"), code: QV4::GlobalExtensions::method_qsTranslate);
2064	globalObject->defineDefaultProperty(QStringLiteral("QT_TRANSLATE_NOOP"), code: QV4::GlobalExtensions::method_qsTranslateNoOp);
2065	globalObject->defineDefaultProperty(QStringLiteral("qsTr"), code: QV4::GlobalExtensions::method_qsTr);
2066	globalObject->defineDefaultProperty(QStringLiteral("QT_TR_NOOP"), code: QV4::GlobalExtensions::method_qsTrNoOp);
2067	globalObject->defineDefaultProperty(QStringLiteral("qsTrId"), code: QV4::GlobalExtensions::method_qsTrId);
2068	globalObject->defineDefaultProperty(QStringLiteral("QT_TRID_NOOP"), code: QV4::GlobalExtensions::method_qsTrIdNoOp);
2069
2070	// Initialize the Qt global object for the uiLanguage property
2071	ScopedString qtName(scope, v4->newString(QStringLiteral("Qt")));
2072	ScopedObject qt(scope, globalObject->get(name: qtName));
2073	if (!qt)
2074	v4->createQtObject();
2075
2076	// string prototype extension
2077	scope.engine->stringPrototype()->defineDefaultProperty(QStringLiteral("arg"), code: QV4::GlobalExtensions::method_string_arg);
2078	#endif
2079	}
2080
2081	if (extensions.testFlag(flag: QJSEngine::ConsoleExtension)) {
2082	globalObject->defineDefaultProperty(QStringLiteral("print"), code: QV4::ConsoleObject::method_log);
2083
2084
2085	QV4::ScopedObject console(scope, globalObject->engine()->memoryManager->allocate<QV4::ConsoleObject>());
2086	globalObject->defineDefaultProperty(QStringLiteral("console"), value: console);
2087	}
2088
2089	if (extensions.testFlag(flag: QJSEngine::GarbageCollectionExtension)) {
2090	globalObject->defineDefaultProperty(QStringLiteral("gc"), code: QV4::GlobalExtensions::method_gc);
2091	}
2092	}
2093
2094
2095	#if QT_CONFIG(translation)
2096	/*!
2097	\qmlmethod string Qt::qsTranslate(string context, string sourceText, string disambiguation, int n)
2098
2099	Returns a translated version of \a sourceText within the given \a context, optionally based on a
2100	\a disambiguation string and value of \a n for strings containing plurals;
2101	otherwise returns \a sourceText itself if no appropriate translated string
2102	is available.
2103
2104	If the same \a sourceText is used in different roles within the
2105	same translation \a context, an additional identifying string may be passed in
2106	for \a disambiguation.
2107
2108	Example:
2109	\snippet qml/qsTranslate.qml 0
2110
2111	Use if you have a translation \a context that differs from the file \a context.
2112
2113	\sa {Internationalization with Qt}
2114	\sa qsTr()
2115	*/
2116	ReturnedValue GlobalExtensions::method_qsTranslate(const FunctionObject *b, const Value *, const Value *argv, int argc)
2117	{
2118	QV4::Scope scope(b);
2119	if (argc < 2)
2120	THROW_GENERIC_ERROR("qsTranslate() requires at least two arguments");
2121	if (!argv[0].isString())
2122	THROW_GENERIC_ERROR("qsTranslate(): first argument (context) must be a string");
2123	if (!argv[1].isString())
2124	THROW_GENERIC_ERROR("qsTranslate(): second argument (sourceText) must be a string");
2125	if ((argc > 2) && !argv[2].isString())
2126	THROW_GENERIC_ERROR("qsTranslate(): third argument (disambiguation) must be a string");
2127
2128	QString context = argv[0].toQStringNoThrow();
2129	QString text = argv[1].toQStringNoThrow();
2130	QString comment;
2131	if (argc > 2) comment = argv[2].toQStringNoThrow();
2132
2133	int i = 3;
2134	if (argc > i && argv[i].isString()) {
2135	qWarning(msg: "qsTranslate(): specifying the encoding as fourth argument is deprecated");
2136	++i;
2137	}
2138
2139	int n = -1;
2140	if (argc > i)
2141	n = argv[i].toInt32();
2142
2143	if (QQmlEnginePrivate *ep = (scope.engine->qmlEngine() ? QQmlEnginePrivate::get(e: scope.engine->qmlEngine()) : nullptr))
2144	if (ep->propertyCapture)
2145	ep->propertyCapture->captureTranslation();
2146
2147	QString result = QCoreApplication::translate(context: context.toUtf8().constData(),
2148	key: text.toUtf8().constData(),
2149	disambiguation: comment.toUtf8().constData(),
2150	n);
2151
2152	return Encode(scope.engine->newString(s: result));
2153	}
2154
2155	/*!
2156	\qmlmethod string Qt::QT_TRANSLATE_NOOP(string context, string sourceText, string disambiguation)
2157
2158	Marks \a sourceText for dynamic translation in the given \a context; i.e, the stored \a sourceText
2159	will not be altered.
2160
2161	If the same \a sourceText is used in different roles within the
2162	same translation context, an additional identifying string may be passed in
2163	for \a disambiguation.
2164
2165	Returns the \a sourceText.
2166
2167	QT_TRANSLATE_NOOP is used in conjunction with the dynamic translation functions
2168	qsTr() and qsTranslate(). It identifies a string as requiring
2169	translation (so it can be identified by \c lupdate), but leaves the actual
2170	translation to the dynamic functions.
2171
2172	Example:
2173	\snippet qml/qtTranslateNoOp.qml 0
2174
2175	\sa {Internationalization with Qt}
2176	*/
2177	ReturnedValue GlobalExtensions::method_qsTranslateNoOp(const FunctionObject *b, const Value *, const Value *argv, int argc)
2178	{
2179	QV4::Scope scope(b);
2180	if (argc < 2)
2181	return QV4::Encode::undefined();
2182	else
2183	return argv[1].asReturnedValue();
2184	}
2185
2186	QString GlobalExtensions::currentTranslationContext(ExecutionEngine *engine)
2187	{
2188	QString context;
2189	CppStackFrame *frame = engine->currentStackFrame;
2190
2191	// The first non-empty source URL in the call stack determines the translation context.
2192	while (frame && context.isEmpty()) {
2193	if (ExecutableCompilationUnit *unit = frame->v4Function->executableCompilationUnit()) {
2194	auto translationContextIndex = unit->unitData()->translationContextIndex();
2195	if (translationContextIndex)
2196	context = unit->stringAt(index: *translationContextIndex);
2197	if (!context.isEmpty())
2198	break;
2199	QString fileName = unit->fileName();
2200	QUrl url(unit->fileName());
2201	if (url.isValid() && url.isRelative()) {
2202	context = url.fileName();
2203	} else {
2204	context = QQmlFile::urlToLocalFileOrQrc(fileName);
2205	if (context.isEmpty() && fileName.startsWith(s: QLatin1String(":/")))
2206	context = fileName;
2207	}
2208	context = QFileInfo(context).completeBaseName();
2209	}
2210	frame = frame->parentFrame();
2211	}
2212
2213	if (context.isEmpty()) {
2214	if (QQmlRefPointer<QQmlContextData> ctxt = engine->callingQmlContext()) {
2215	QString path = ctxt->urlString();
2216	int lastSlash = path.lastIndexOf(c: QLatin1Char('/'));
2217	int lastDot = path.lastIndexOf(c: QLatin1Char('.'));
2218	int length = lastDot - (lastSlash + 1);
2219	context = (lastSlash > -1) ? path.mid(position: lastSlash + 1, n: (length > -1) ? length : -1) : QString();
2220	}
2221	}
2222
2223	return context;
2224	}
2225
2226	/*!
2227	\qmlmethod string Qt::qsTr(string sourceText, string disambiguation, int n)
2228
2229	Returns a translated version of \a sourceText, optionally based on a
2230	\a disambiguation string and value of \a n for strings containing plurals;
2231	otherwise returns \a sourceText itself if no appropriate translated string
2232	is available.
2233
2234	Examples with \a sourceText and \a {n}:
2235
2236	\if defined(onlinedocs)
2237	\tab {qstr}{qstr-1}{sourceText}{checked}
2238	\tab {qstr}{qstr-2}{sourceText and n}{}
2239	\tabcontent {qstr-1}
2240	\else
2241	\section1 Only sourceText
2242	\endif
2243	\snippet qml/qsTr.qml 0
2244	\if defined(onlinedocs)
2245	\endtabcontent
2246	\tabcontent {qstr-2}
2247	\else
2248	\section1 SourceText and n
2249	\endif
2250	\snippet qml/qsTr.qml 1
2251	\if defined(onlinedocs)
2252	\endtabcontent
2253	\endif
2254
2255	If the same \a sourceText is used in different roles within the
2256	same translation context, an additional identifying string may be passed in
2257	for \a disambiguation. For more information and examples, refer to
2258	\l{Disambiguate Identical Text}.
2259
2260	\sa qsTranslate()
2261	\sa {Internationalization with Qt},{Writing Source Code for Translation}
2262	*/
2263	ReturnedValue GlobalExtensions::method_qsTr(const FunctionObject *b, const Value *, const Value *argv, int argc)
2264	{
2265	QV4::Scope scope(b);
2266	if (argc < 1)
2267	THROW_GENERIC_ERROR("qsTr() requires at least one argument");
2268	if (!argv[0].isString())
2269	THROW_GENERIC_ERROR("qsTr(): first argument (sourceText) must be a string");
2270	if ((argc > 1) && !argv[1].isString())
2271	THROW_GENERIC_ERROR("qsTr(): second argument (disambiguation) must be a string");
2272	if ((argc > 2) && !argv[2].isNumber())
2273	THROW_GENERIC_ERROR("qsTr(): third argument (n) must be a number");
2274
2275	const QString context = currentTranslationContext(engine: scope.engine);
2276	const QString text = argv[0].toQStringNoThrow();
2277	const QString comment = argc > 1 ? argv[1].toQStringNoThrow() : QString();
2278	const int n = argc > 2 ? argv[2].toInt32() : -1;
2279
2280	if (QQmlEnginePrivate *ep = (scope.engine->qmlEngine() ? QQmlEnginePrivate::get(e: scope.engine->qmlEngine()) : nullptr))
2281	if (ep->propertyCapture)
2282	ep->propertyCapture->captureTranslation();
2283
2284	QString result = QCoreApplication::translate(context: context.toUtf8().constData(), key: text.toUtf8().constData(),
2285	disambiguation: comment.toUtf8().constData(), n);
2286
2287	return Encode(scope.engine->newString(s: result));
2288	}
2289
2290	/*!
2291	\qmlmethod string Qt::QT_TR_NOOP(string sourceText, string disambiguation)
2292
2293	Marks \a sourceText for dynamic translation; i.e, the stored \a sourceText
2294	will not be altered.
2295
2296	If the same \a sourceText is used in different roles within the
2297	same translation context, an additional identifying string may be passed in
2298	for \a disambiguation.
2299
2300	Returns the \a sourceText.
2301
2302	QT_TR_NOOP is used in conjunction with the dynamic translation functions
2303	qsTr() and qsTranslate(). It identifies a string as requiring
2304	translation (so it can be identified by \c lupdate), but leaves the actual
2305	translation to the dynamic functions.
2306
2307	Example:
2308	\snippet qml/qtTrNoOp.qml 0
2309
2310	\sa {Internationalization with Qt}
2311	*/
2312	ReturnedValue GlobalExtensions::method_qsTrNoOp(const FunctionObject *, const Value *, const Value *argv, int argc)
2313	{
2314	if (argc < 1)
2315	return QV4::Encode::undefined();
2316	else
2317	return argv[0].asReturnedValue();
2318	}
2319
2320	/*!
2321	\qmlmethod string Qt::qsTrId(string id, int n)
2322
2323	Returns a translated string identified by \a id.
2324	If no matching string is found, the id itself is returned. This
2325	should not happen under normal conditions.
2326
2327	If \a n >= 0, all occurrences of \c %n in the resulting string
2328	are replaced with a decimal representation of \a n. In addition,
2329	depending on \a n's value, the translation text may vary.
2330
2331	Example:
2332	\snippet qml/qsTrId.qml 0
2333
2334	It is possible to supply a source string template like:
2335
2336	\tt{//% <string>}
2337
2338	\snippet qml/qsTrId.1.qml 0
2339
2340	or
2341
2342	\tt{\begincomment% <string> \endcomment}
2343
2344	\snippet qml/qsTrId.1.qml 1
2345
2346	Creating binary translation (QM) files suitable for use with this function requires passing
2347	the \c -idbased option to the \c lrelease tool.
2348
2349	\sa QT_TRID_NOOP(), {Internationalization with Qt}
2350	*/
2351	ReturnedValue GlobalExtensions::method_qsTrId(const FunctionObject *b, const Value *, const Value *argv, int argc)
2352	{
2353	QV4::Scope scope(b);
2354	if (argc < 1)
2355	THROW_GENERIC_ERROR("qsTrId() requires at least one argument");
2356	if (!argv[0].isString())
2357	THROW_TYPE_ERROR_WITH_MESSAGE("qsTrId(): first argument (id) must be a string");
2358	if (argc > 1 && !argv[1].isNumber())
2359	THROW_TYPE_ERROR_WITH_MESSAGE("qsTrId(): second argument (n) must be a number");
2360
2361	int n = -1;
2362	if (argc > 1)
2363	n = argv[1].toInt32();
2364
2365	if (QQmlEnginePrivate *ep = (scope.engine->qmlEngine() ? QQmlEnginePrivate::get(e: scope.engine->qmlEngine()) : nullptr))
2366	if (ep->propertyCapture)
2367	ep->propertyCapture->captureTranslation();
2368
2369	return Encode(scope.engine->newString(s: qtTrId(id: argv[0].toQStringNoThrow().toUtf8().constData(), n)));
2370	}
2371
2372	/*!
2373	\qmlmethod string Qt::QT_TRID_NOOP(string id)
2374
2375	Marks \a id for dynamic translation.
2376
2377	Returns the \a id.
2378
2379	QT_TRID_NOOP is used in conjunction with the dynamic translation function
2380	qsTrId(). It identifies a string as requiring translation (so it can be identified
2381	by \c lupdate), but leaves the actual translation to qsTrId().
2382
2383	Example:
2384	\snippet qml/qtTrIdNoOp.qml 0
2385
2386	\sa qsTrId(), {Internationalization with Qt}
2387	*/
2388	ReturnedValue GlobalExtensions::method_qsTrIdNoOp(const FunctionObject *, const Value *, const Value *argv, int argc)
2389	{
2390	if (argc < 1)
2391	return QV4::Encode::undefined();
2392	else
2393	return argv[0].asReturnedValue();
2394	}
2395	#endif // translation
2396
2397	/*!
2398	\qmlmethod void Qt::gc()
2399
2400	Runs the garbage collector.
2401
2402	This is equivalent to calling QJSEngine::collectGarbage().
2403
2404	\sa {Garbage Collection}
2405	*/
2406	ReturnedValue GlobalExtensions::method_gc(const FunctionObject *b, const Value *, const Value *, int)
2407	{
2408	auto mm = b->engine()->memoryManager;
2409	mm->runFullGC();
2410
2411	return QV4::Encode::undefined();
2412	}
2413
2414	ReturnedValue GlobalExtensions::method_string_arg(const FunctionObject *b, const Value *thisObject, const Value *argv, int argc)
2415	{
2416	QV4::Scope scope(b);
2417	if (argc != 1)
2418	THROW_GENERIC_ERROR("String.arg(): Invalid arguments");
2419
2420	QString value = thisObject->toQString();
2421
2422	QV4::ScopedValue arg(scope, argv[0]);
2423	if (arg->isInteger())
2424	RETURN_RESULT(scope.engine->newString(value.arg(arg->integerValue())));
2425	else if (arg->isDouble())
2426	RETURN_RESULT(scope.engine->newString(value.arg(arg->doubleValue())));
2427	else if (arg->isBoolean())
2428	RETURN_RESULT(scope.engine->newString(value.arg(arg->booleanValue())));
2429
2430	RETURN_RESULT(scope.engine->newString(value.arg(arg->toQString())));
2431	}
2432
2433	/*!
2434	\qmlmethod Qt::callLater(function)
2435	\qmlmethod Qt::callLater(function, argument1, argument2, ...)
2436	\since 5.8
2437	Use this function to eliminate redundant calls to a function or signal.
2438
2439	The function passed as the first argument to Qt.callLater()
2440	will be called later, once the QML engine returns to the event loop.
2441
2442	When this function is called multiple times in quick succession with the
2443	same function as its first argument, that function will be called only once.
2444
2445	For example:
2446	\snippet qml/qtLater.qml 0
2447
2448	Any additional arguments passed to Qt.callLater() will
2449	be passed on to the function invoked. Note that if redundant calls
2450	are eliminated, then only the last set of arguments will be passed to the
2451	function.
2452	*/
2453
2454	QT_END_NAMESPACE
2455
2456	#include "moc_qqmlbuiltinfunctions_p.cpp"
2457