aboutsummaryrefslogtreecommitdiffstats
path: root/src/qml/doc/src/javascript
diff options
context:
space:
mode:
Diffstat (limited to 'src/qml/doc/src/javascript')
-rw-r--r--src/qml/doc/src/javascript/date.qdoc132
-rw-r--r--src/qml/doc/src/javascript/dynamicobjectcreation.qdoc38
-rw-r--r--src/qml/doc/src/javascript/expressions.qdoc36
-rw-r--r--src/qml/doc/src/javascript/finetuning.qdoc67
-rw-r--r--src/qml/doc/src/javascript/functionlist.qdoc36
-rw-r--r--src/qml/doc/src/javascript/hostenvironment.qdoc74
-rw-r--r--src/qml/doc/src/javascript/imports.qdoc55
-rw-r--r--src/qml/doc/src/javascript/memory.qdoc211
-rw-r--r--src/qml/doc/src/javascript/number.qdoc53
-rw-r--r--src/qml/doc/src/javascript/qmlglobalobject.qdoc135
-rw-r--r--src/qml/doc/src/javascript/qtjavascript.qdoc28
-rw-r--r--src/qml/doc/src/javascript/resources.qdoc28
-rw-r--r--src/qml/doc/src/javascript/string.qdoc50
-rw-r--r--src/qml/doc/src/javascript/topic.qdoc55
-rw-r--r--src/qml/doc/src/javascript/xmlhttprequest.qdoc301
15 files changed, 734 insertions, 565 deletions
diff --git a/src/qml/doc/src/javascript/date.qdoc b/src/qml/doc/src/javascript/date.qdoc
index 431f9649a0..26ce1d5d29 100644
--- a/src/qml/doc/src/javascript/date.qdoc
+++ b/src/qml/doc/src/javascript/date.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2021 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\qmltype Date
@@ -31,98 +7,48 @@
\brief Provides date functions.
The QML Date object extends the
- \l{Mozilla Developer Network Date Reference}{JS Date object} with
+ \l{ECMAScript Specification of Date}{JS Date object} with
locale aware functions.
- Functions that accept a locale format may be either an enumeration
- value:
- \table
- \row \li Locale.LongFormat \li The long version of the string; for example, returning "January" as a month name.
- \row \li Locale.ShortFormat \li The short version of the string; for example, returning "Jan" as a month name.
- \row \li Locale.NarrowFormat \li A special version for use when space is limited;
- for example, returning "J" as a month name. Note that the narrow format might contain
- the same text for different months and days or it can even be an empty string if the
- locale doesn't support narrow names, so you should avoid using it for date formatting.
- Also, for the system locale this format is the same as ShortFormat.
- \endtable
+ Functions that accept a \c format argument take either Locale.LongFormat,
+ Locale.ShortFormat, Locale.NarrowFormat enumeration values,
+ or a string specifying the format.
- or a string specifying the format These expressions may be used for format dates:
- \table
- \header \li Expression \li Output
- \row \li d \li the day as number without a leading zero (1 to 31)
- \row \li dd \li the day as number with a leading zero (01 to 31)
- \row \li ddd
- \li the abbreviated localized day name (e.g. 'Mon' to 'Sun').
- \row \li dddd
- \li the long localized day name (e.g. 'Monday' to 'Sunday').
- \row \li M \li the month as number without a leading zero (1 to 12)
- \row \li MM \li the month as number with a leading zero (01 to 12)
- \row \li MMM
- \li the abbreviated localized month name (e.g. 'Jan' to 'Dec').
- \row \li MMMM
- \li the long localized month name (e.g. 'January' to 'December').
- \row \li yy \li the year as two digit number (00 to 99)
- \row \li yyyy \li the year as four digit number. If the year is negative,
- a minus sign is prepended in addition.
- \endtable
+ The form of the supported format strings is as described in the
+ documentation of \l QDate::toString(), \l QTime::toString() and \l
+ QDateTime::toString().
- All other input characters will be ignored. Any sequence of characters that
- are enclosed in singlequotes will be treated as text and not be used as an
- expression. Two consecutive singlequotes ("''") are replaced by a singlequote
- in the output.
+ If the date is invalid, an empty string is returned.
- Example format strings (assuming that the Date is the 20 July
- 1969):
-
- \table
- \header \li Format \li Result
- \row \li dd.MM.yyyy \li 20.07.1969
- \row \li ddd MMMM d yy \li Sun July 20 69
- \row \li 'The day is' dddd \li The day is Sunday
- \endtable
+ \section1 Format Enumeration Values
- These expressions may be used for formatting time:
+ Use the enumeration values when you want a format that matches the locale
+ preferences.
\table
- \header \li Expression \li Output
- \row \li h
- \li the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display)
- \row \li hh
- \li the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display)
- \row \li H
- \li the hour without a leading zero (0 to 23, even with AM/PM display)
- \row \li HH
- \li the hour with a leading zero (00 to 23, even with AM/PM display)
- \row \li m \li the minute without a leading zero (0 to 59)
- \row \li mm \li the minute with a leading zero (00 to 59)
- \row \li s \li the second without a leading zero (0 to 59)
- \row \li ss \li the second with a leading zero (00 to 59)
- \row \li z \li the milliseconds without leading zeroes (0 to 999)
- \row \li zzz \li the milliseconds with leading zeroes (000 to 999)
- \row \li AP or A
- \li use AM/PM display. \e AP will be replaced by either "AM" or "PM".
- \row \li ap or a
- \li use am/pm display. \e ap will be replaced by either "am" or "pm".
- \row \li t \li the timezone (for example "CEST")
+ \row \li Locale.LongFormat \li Longer format
+ \row \li Locale.ShortFormat \li Shorter format
+ \row \li Locale.NarrowFormat \li In this context same as Locale.ShortFormat
\endtable
- All other input characters will be ignored. Any sequence of characters that
- are enclosed in singlequotes will be treated as text and not be used as an
- expression. Two consecutive singlequotes ("''") are replaced by a singlequote
- in the output.
+ The format that the enumerations represent will depend on your locale, but also
+ the method that the enumeration is used for.
- Example format strings (assuming that the QTime is 14:13:09.042)
+ For example, for the \c en_US locale, these format strings are used:
\table
- \header \li Format \li Result
- \row \li hh:mm:ss.zzz \li 14:13:09.042
- \row \li h:m:s ap \li 2:13:9 pm
- \row \li H:m:s a \li 14:13:9 pm
+ \header \li Function \li Locale Enum \li Format String
+ \row \li fromLocaleDateString, toLocaleDateString \li Locale.LongFormat \li \c{dddd, MMMM d, yyyy}
+ \row \li fromLocaleDateString, toLocaleDateString \li Locale.ShortFormat \li \c{M/d/yy}
+ \row \li fromLocaleTimeString, toLocaleTimeString \li Locale.LongFormat \li \c{h:mm:ss AP t}
+ \row \li fromLocaleTimeString, toLocaleTimeString \li Locale.ShortFormat \li \c{h:mm AP}
+ \row \li fromLocaleString, toLocaleString \li Locale.LongFormat \li \c{dddd, MMMM d, yyyy h:mm:ss AP t}
+ \row \li fromLocaleString, toLocaleString \li Locale.ShortFormat \li \c{M/d/yy h:mm AP}
\endtable
- If the date is invalid, an empty string will be returned.
+ \section1 Further Notes
- Note: Using the locale-aware functions to perform date or time formatting can
+ Using the locale-aware functions to perform date or time formatting can
result in incorrectly formatted times, due to an inconsistency in specification
between Qt and JS. ECMA-262 specifies that historical dates should be intrepreted
by projecting the current rules for daylight-saving onto past years, while Qt uses
@@ -132,7 +58,7 @@
hour, if DST is currently in effect, while it was not for the time specified, or
vice versa.
- Note: There are different date formats with different understandings of negative years. Common
+ There are different date formats with different understandings of negative years. Common
human language does not have a year 0. The year after 1BC is 1AD. This understanding is
reflected when printing or parsing dates in one of the formats not standardized by ECMAScript.
That is: toString(), toLocaleString(), toUTCString() and friends. ECMAScript does standardize
diff --git a/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc b/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc
index be4db4c917..f20111d154 100644
--- a/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc
+++ b/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2017 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtqml-javascript-dynamicobjectcreation.html
@@ -35,10 +11,6 @@ useful to delay instantiation of objects until necessary, thereby improving
application startup time. It also allows visual objects to be dynamically
created and added to the scene in reaction to user input or other events.
-See the \l {QML Example - Dynamic Scene}{Dynamic Scene example} for a
-demonstration of the concepts discussed on this page.
-
-
\section1 Creating Objects Dynamically
There are two ways to create objects dynamically from JavaScript. You can
@@ -126,6 +98,12 @@ It is also possible to instantiate components without blocking via the
\section2 Creating an Object from a String of QML
+\warning Creating objects from a string of QML is extremely slow since the engine has to compile the
+passed QML string every time you do it. Furthermore, it's very easy to produce invalid QML when
+programmatically constructing QML code. It's much better to keep your QML components as separate
+files and add properties and methods to customize their behavior than to produce new components by
+string manipulation.
+
If the QML is not defined until runtime, you can create a QML object from
a string of QML using the \l{QtQml::Qt::createQmlObject()}{Qt.createQmlObject()}
function, as in the following example:
diff --git a/src/qml/doc/src/javascript/expressions.qdoc b/src/qml/doc/src/javascript/expressions.qdoc
index b83127389a..d4f0115033 100644
--- a/src/qml/doc/src/javascript/expressions.qdoc
+++ b/src/qml/doc/src/javascript/expressions.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2017 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtqml-javascript-expressions.html
\title JavaScript Expressions in QML Documents
@@ -147,7 +123,7 @@ Rectangle {
TapHandler {
id: inputHandler
- onTapped: {
+ onTapped: {
// arbitrary JavaScript expression
console.log("Tapped!")
}
@@ -310,14 +286,14 @@ signal just before being destroyed.
resources in Qt 5.0.0, so mark this section as internal for now.
It should eventually become public API
- There is another section about scarce resources in basictypes.qdoc. It should
+ There is another section about scarce resources in valuetypes.qdoc. It should
be enabled at the same time.
\section1 Scarce Resources in JavaScript
-As described in the documentation for \l{QML Basic Types}, a \c var type
+As described in the documentation for \l{QML Value Types}, a \c var type
property may hold a \e{scarce resource} (image or pixmap). There are several
important semantics of scarce resources which should be noted:
@@ -339,7 +315,7 @@ For the following examples, imagine that we have defined the following class:
and that we have registered it with the QML type-system as follows:
-\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 0
+\snippet qml/integrating-javascript/scarceresources/scarceresources.pro 0
The AvatarExample class has a property which is a pixmap. When the property
is accessed in JavaScript scope, a copy of the resource will be created and
diff --git a/src/qml/doc/src/javascript/finetuning.qdoc b/src/qml/doc/src/javascript/finetuning.qdoc
index fcd710db8b..0e8a913a2a 100644
--- a/src/qml/doc/src/javascript/finetuning.qdoc
+++ b/src/qml/doc/src/javascript/finetuning.qdoc
@@ -1,33 +1,9 @@
-/****************************************************************************
-**
-** Copyright (C) 2019 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2019 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtqml-javascript-finetuning.html
-\title Fine-tuning the JavaScript Engine
+\title Configuring the JavaScript Engine
\brief Describes the environment variables available, to control how Javascript is run.
Running JavaScript code can be influenced by a few environment variables, particularly:
@@ -44,8 +20,11 @@ Running JavaScript code can be influenced by a few environment variables, partic
considered for JIT compilation. The default value is 3 times.
\row
\li \c{QV4_FORCE_INTERPRETER}
- \li Setting this environment variable disables the JIT and runs all
- functions through the interpreter, no matter how often they are called.
+ \li Setting this environment variable runs all functions and expressions through the
+ interpreter. The JIT is never used, no matter how often a function or expression is
+ called. Functions and expressions may still be compiled ahead of time using
+ \l{qmlcachegen} or \l{qmlsc}, but only the generated byte code is used at run time. Any
+ generated C++ code and the machine code resulting from it is ignored.
\row
\li \c{QV4_JS_MAX_STACK_SIZE}
\li The JavaScript engine reserves a special memory area as a stack to run JavaScript.
@@ -82,9 +61,12 @@ Running JavaScript code can be influenced by a few environment variables, partic
\li \c{QV4_MAX_CALL_DEPTH}
\li Stack overflows when running (as opposed to compiling) JavaScript are prevented by
controlling the call depth: the number of nested function invocations. By
- default, an exception is generated if the call depth exceeds 1234. If it contains a
- number, this environment variable overrides the maximum call depth. Beware that the
- recursion limit when compiling JavaScript is not affected.
+ default, an exception is generated if the call depth exceeds a maximum number tuned
+ to the platform's default stack size. If the \c{QV4_MAX_CALL_DEPTH} environment
+ variable contains a number, this number is used as maximum call depth. Beware that
+ the recursion limit when compiling JavaScript is not affected. The default maximum
+ call depth is 1234 on most platforms. On QNX it is 640 because on QNX the default
+ stack size is smaller than on most platforms.
\row
\li \c{QV4_MM_AGGRESSIVE_GC}
\li Setting this environment variable runs the garbage collector before each memory
@@ -98,7 +80,28 @@ Running JavaScript code can be influenced by a few environment variables, partic
provide this information, there's a convention to create a special file called
\c{perf-<pid>.map} in \e{/tmp} which perf then reads. This environment variable, if
set, causes the JIT to generate this file.
+ \row
+ \li \c{QV4_SHOW_BYTECODE}
+ \li Outputs the IR bytecode generated by Qt to the console.
+ Has to be combined with \c{QML_DISABLE_DISK_CACHE} or already cached bytecode will not
+ be shown.
+ \row
+ \li \c{QV4_DUMP_BASIC_BLOCKS}
+ \li Outputs the basic blocks of each function compiled ahead of time. The details of the
+ blocks are printed to the console. Additionally, control flow graphs with the byte code
+ for each block are generated in the DOT format for each compiled function. The value of
+ \c {QV4_DUMP_BASIC_BLOCKS} is used as the path to the folder where the DOT files should
+ be generated. If the path is any of ["-", "1", "true"] or if files can't be opened,
+ the graphs are dumped to stdout instead.
+ \row
+ \li \c{QV4_VALIDATE_BASIC_BLOCKS}
+ \li Performs checks on the basic blocks of a function compiled ahead of time to validate
+ its structure and coherence. If the validation fails, an error message is printed to
+ the console.
\endtable
+\l{The QML Disk Cache} accepts further environment variables that allow fine tuning its behavior.
+In particular \c{QML_DISABLE_DISK_CACHE} may be useful for debugging.
+
*/
diff --git a/src/qml/doc/src/javascript/functionlist.qdoc b/src/qml/doc/src/javascript/functionlist.qdoc
index 7a6a922480..d656bc2234 100644
--- a/src/qml/doc/src/javascript/functionlist.qdoc
+++ b/src/qml/doc/src/javascript/functionlist.qdoc
@@ -1,37 +1,13 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2017 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtqml-javascript-functionlist.html
\title List of JavaScript Objects and Functions
\brief A list of objects, functions, and properties supported in QML.
This reference contains a list of objects, functions and
- properties supported by the \l{QQmlEngine}{QML engine}. For a detailed
- description, see the \l{ECMA-262} specification.
+ properties supported by the \l{QJSEngine}{JavaScript engine} in Qt.
+ For a detailed description, see the \l{ECMA-262} specification.
\section1 The Global Object
@@ -233,9 +209,9 @@
\li [Symbol.iterator]()
\endlist
- Additionally, the QML engine adds the following functions to the \l String prototype:
+ Additionally, the QML engine adds the following functions to the \c String prototype:
\list
- \li \l {String::arg}{arg()}
+ \li \l {string}{string::arg()}
\endlist
diff --git a/src/qml/doc/src/javascript/hostenvironment.qdoc b/src/qml/doc/src/javascript/hostenvironment.qdoc
index c22c392b80..a27fe48fbe 100644
--- a/src/qml/doc/src/javascript/hostenvironment.qdoc
+++ b/src/qml/doc/src/javascript/hostenvironment.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2017 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtqml-javascript-hostenvironment.html
\title JavaScript Host Environment
@@ -42,6 +18,9 @@ Like a browser or server-side JavaScript environment, the QML runtime implements
all of the built-in types and functions defined by the standard, such as Object, Array, and Math.
The QML runtime implements the 7th edition of the standard.
+\l{Nullish Coalescing} (\c{??}) (since Qt 5.15) and \l{Optional Chaining} (\c{?.}) (since Qt 6.2)
+are also implemented in the QML runtime.
+
The standard ECMAScript built-ins are not explicitly documented in the QML documentation. For more
information on their use, please refer to the ECMA-262 7th edition standard or one of the many online
JavaScript reference and tutorial sites, such as the \l{W3Schools JavaScript Reference} (JavaScript Objects
@@ -51,6 +30,47 @@ specific to the browser environment. In the case of the W3Schools link above, th
Reference} section generally covers the standard, while the \c{Browser Objects Reference} and \c{HTML DOM
Objects Reference} sections are browser specific (and thus not applicable to QML).
+\section1 Type annotations and assertions
+
+Function declarations in QML documents can, and should, contain type
+annotations. Type annotations are appended to the declaration of arguments and
+to the function itself, for annotating the return type. The following function
+takes an \c int and a \c string parameter, and returns a \c QtObject:
+
+\qml
+function doThings(a: int, b: string) : QtObject { ... }
+\endqml
+
+Type annotations help tools like \l{Qt Creator} and \l{qmllint Reference}{qmllint} to make sense
+of the code and provide better diagnostics. Moreover, they make functions easier
+to use from C++. See
+\l {qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++}
+for more information.
+
+Type assertions (sometimes called \e as-casts) can also be used in order to cast an object to a
+different object type. If the object is actually of the given type, then the type assertion returns
+the same object. If not, it returns \c null. In the following snippet we assert that the \c parent
+object is a \c Rectangle before accessing a specific member of it.
+
+\qml
+Item {
+ property color parentColor: (parent as Rectangle)?.color || "red"
+}
+\endqml
+
+The optional chaining (\c{?.}) avoids throwing an exception if the parent is
+actually not a rectangle. In that case "red" is chosen as \c parentColor.
+
+Since Qt 6.7 type annotations are always enforced when calling functions. Values
+are coerced to the required types as necessary. Previously, type annotations were
+ignored by the interpreter and the JIT compiler, but enforced by \l{qmlcachegen}
+and \l{qmlsc} when compiling to C++. This could lead to differences in behavior in
+some corner cases. In order to explicitly request the old behavior of the
+interpreter and JIT you can add the following to your QML document:
+
+\qml
+pragma FunctionSignatureBehavior: Ignored
+\endqml
\section1 QML Global Object
@@ -69,7 +89,7 @@ QML engine can be found in the \l{List of JavaScript Objects and Functions}.
Note that QML makes the following modifications to native objects:
\list
-\li An \l {String::arg}{arg()} function is added to the \l String prototype.
+\li An \l {string}{arg()} function is added to the \c String prototype.
\li Locale-aware conversion functions are added to the \l Date and \l Number prototypes.
\endlist
diff --git a/src/qml/doc/src/javascript/imports.qdoc b/src/qml/doc/src/javascript/imports.qdoc
index 8e26c4aadd..ef5376cb54 100644
--- a/src/qml/doc/src/javascript/imports.qdoc
+++ b/src/qml/doc/src/javascript/imports.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2017 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtqml-javascript-imports.html
\title Importing JavaScript Resources in QML
@@ -64,7 +40,7 @@ objects such as \c Date and \c Math).
The functions defined in an imported JavaScript file are available to objects
defined in the importing QML document, via the
\c{"Qualifier.functionName(params)"} syntax. Functions in JavaScript resources
-may take parameters whose type can be any of the supported QML basic types or
+may take parameters whose types can be any QML value types or
object types, as well as normal JavaScript types. The normal
\l{qtqml-cppintegration-data.html}{data type conversion rules} will apply to
parameters and return values when calling such functions from QML.
@@ -95,17 +71,18 @@ or modules).
A JavaScript resource may import another in the following fashion:
\code
-.import "filename.js" as Qualifier
+import * as MathFunctions from "factorial.mjs";
\endcode
-For example:
+Or:
\code
-import * as MathFunctions from "factorial.mjs";
+.import "filename.js" as Qualifier
\endcode
-The latter is standard ECMAScript syntax for importing ECMAScript modules, and
+The former is standard ECMAScript syntax for importing ECMAScript modules, and
only works from within ECMAScript modules as denoted by the \c mjs file
-extension. The former is an extension to JavaScript provided by the \c QML
-engine and will work also with non-modules.
+extension. The latter is an extension to JavaScript provided by the \c QML
+engine and will work also with non-modules. As an extension superseded by the
+ECMAScript standard, its usage is discouraged.
When a JavaScript file is imported this way, it is imported with a qualifier.
The functions in that file are then accessible from the importing script via the
@@ -154,7 +131,15 @@ var importedEnumValue = JsQtTest.MyQmlObject.EnumValue3
\endcode
In particular, this may be useful in order to access functionality provided
-via a singleton type; see qmlRegisterSingletonType() for more information.
+via a singleton type; see QML_SINGLETON for more information.
+
+Your JavaScript resource by default can access all imports of the component
+that imports the resource. It does not have access to the componpents's imports
+if it is declared as a stateless library (using \c{.pragma library}) or contains
+an explicit \c{.import} statment.
+
+\note The .import syntax doesn't work for scripts used in \l {WorkerScript}
+
+\sa {Defining JavaScript Resources in QML}
-\note The .import syntax doesn't work for scripts used in the \l {WorkerScript}
*/
diff --git a/src/qml/doc/src/javascript/memory.qdoc b/src/qml/doc/src/javascript/memory.qdoc
new file mode 100644
index 0000000000..54f48f48df
--- /dev/null
+++ b/src/qml/doc/src/javascript/memory.qdoc
@@ -0,0 +1,211 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+/*!
+
+\page qtqml-javascript-memory.html
+\title Memory Management in the JavaScript Engine
+\brief Describes how the JavaScript Engine manages memory.
+
+\section1 Introduction
+
+This document describes the \e dynamic memory management of the JavaScript
+Engine in QML. It is a rather technical, in depth description. You only need
+to read this if you care about the exact characteristics of JavaScript memory
+management in QML. In particular, it can be helpful if you're trying to
+optimize your application for maximum performance.
+
+\note By compiling your QML code to C++ using the \l{Qt Quick Compiler}
+you can avoid much of the JavaScript heap usage. The generated C++ code uses the
+familiar C++ stack and heap for storing objects and values. The
+\l{JavaScript Host Environment}, however, always uses some JavaScript-managed
+memory, no matter if you use it or not. If you use features that cannot be
+compiled to C++, the engine will fall back to interpretation or JIT compilation
+and use JavaScript objects stored on the JavaScript heap, though.
+
+\section1 Basic Principles
+
+The JavaScript engine in QML has a dedicated memory manager that requests
+address space in units of multiple pages from the operating system. Objects,
+strings, and other managed values created in JavaScript are then placed in this
+address space, using the JavaScript engine's own allocation scheme. The
+JavaScript engine does not use the C library's malloc() and free(), nor the
+default implementations of C++'s new and delete to allocate memory for
+JavaScript objects.
+
+Requests for address space are generally done with mmap() on Unix-like systems
+and with VirtualAlloc() on windows. There are several platform-specific
+implementations of those primitives. Address space reserved this way is not
+immediately committed to physical memory. Rather, the operating system notices
+when a page of memory is actually accessed and only then commits it. Therefore,
+the address space is practically free and having a lot of it gives the
+JavaScript memory manager the leverage it needs to place objects in an efficient
+way on the JavaScript heap. Furthermore, there are platform-specific techniques
+to tell the operating system that a chunk of address space, though still
+reserved, does not have to be mapped into physical memory for the time being.
+The operating system can then decommit the memory as needed and use it for other
+tasks. Crucially, most operating systems do not guarantee immediate action on
+such a decommit request. They will only decommit the memory when it is actually
+needed for something else. On Unix-like systems we generally use madvise() for
+this. Windows has specific flags to VirtualFree() to do the equivalent.
+
+\note There are memory profiling tools that do not understand this mechanism and
+over-report JavaScript memory usage.
+
+All values stored on the JavaScript heap are subject to garbage collection.
+None of the values are immediately "deleted" when they go out of scope or are
+otherwise "dropped". Only the garbage collector may remove values from the
+JavaScript heap and return memory (see \l{Garbage Collection} below for how
+this works).
+
+\section1 QObject-based Types
+
+QObject-based types, and in particular everything you can phrase as a QML
+element, are allocated on the C++ heap. Only a small wrapper around the pointer
+is placed on the JavaScript heap when a QObject is accessed from JavaScript.
+Such a wrapper, however, can own the QObject it points to. See
+\l{QJSEngine::ObjectOwnership}. If the wrapper owns the object, it will be
+deleted when the wrapper is garbage-collected. You can then also manually
+trigger the deletion by calling the destroy() method on it. destroy() internally
+calls \l{QObject::deleteLater()}. It will therefore not immediately delete the
+object, but wait for the next event loop iteration.
+
+QML-declared \e properties of objects are stored on the JavaScript heap. They
+live as long as the object they belong to lives. Afterwards they are removed the
+next time the garbage collector runs.
+
+\section1 Object Allocation
+
+In JavaScript, any structured type is an object. This includes function objects,
+arrays, regular expressions, date objects and much more. QML has a number of
+internal object types, such as the above mentioned QObject wrapper. Whenever
+an object is created, the memory manager locates some storage for it on the
+JavaScript heap.
+
+JavaScript strings are also managed values, but their string data is not
+allocated on the JavaScript heap. Similar to QObject wrappers, the heap objects
+for strings are just thin wrappers around a pointer to string data.
+
+When allocating memory for an object, the size of the object is first rounded up
+to 32 byte alignment. Each 32 byte piece of address space is called a "slot".
+For objects smaller than a "huge size" threshold, the memory manager performs
+a series of attempts to place the object in memory:
+\list
+\li The memory manager keeps linked lists of previously freed pieces of heap,
+ called "bins". Each bin holds pieces of heap with a fixed per-bin size in
+ slots. If the bin for the right size is not empty, it picks the first entry
+ and places the object there.
+\li The memory that hasn't been used yet is managed via a bumper allocator. A
+ bumper pointer points to the byte beyond the occupied address space. If
+ there is still enough unused address space, the bumper is increased
+ accordingly, and the object is placed in unused space.
+\li A separate bin is kept for previously freed pieces of heap of varying sizes
+ larger than the specific sizes mentioned above. The memory manager
+ traverses this list and tries to find a piece it can split to accommodate
+ the new object.
+\li The memory manager searches the lists of specifically sized bins
+ larger than the object to be allocated and tries to split one of those.
+\li Finally, if none of the above works, the memory manager reserves more
+ address space and allocates the object using the bumper allocator.
+\endlist
+
+Huge objects are handled by their own allocator. For each of those one or more
+separate memory pages are obtained from the OS and managed separately.
+
+Additionally, each new chunk of address space the memory manager obtains from
+the OS gets a header that holds a number of flags for each slot:
+\list
+\li \e{object}: The first slot occupied by an object is flagged with this bit.
+\li \e{extends}: Any further slots occupied by an object are flagged with this
+ bit.
+\li \e{mark}: When the garbage collector runs, it sets this bit if the object is
+ still in use.
+\endlist
+
+\section1 Internal Classes
+
+In order to minimize the required storage for metadata on what members
+an object holds, the JavaScript engine assigns an "internal class" to each
+object. Other JavaScript engines call this "hidden class" or "shape".
+Internal classes are deduplicated and kept in a tree. If a property is
+added to an object, the children of the current internal class are checked to
+see if the same object layout has occurred before. If so, we can use the
+resulting internal class right away. Otherwise we have to create a new one.
+
+Internal classes are stored in their own section of the JavaScript heap that
+otherwise works the same way as the general object allocation described above.
+This is because internal classes have to be kept alive while the objects using
+them are collected. Internal classes are then collected in a separate pass.
+
+The actual property attributes stored in internal classes are \e not kept on
+the JavaScript heap, though, but rather managed using new and delete.
+
+\section1 Garbage Collection
+
+The garbage collector used in the JavaScript engine is a non-moving,
+stop-the-world Mark and Sweep design. In the \e mark phase we traverse all the
+known places where live references to objects can be found. In particular:
+
+\list
+\li JavaScript globals
+\li Undeletable parts of QML and JavaScript compilation units
+\li The JavaScript stack
+\li The persistent value storage. This is where QJSValue and similar classes
+ keep references to JavaScript objects.
+\endlist
+
+For any object found in those places the mark bits are set recursively for
+anything it references.
+
+In the \e sweep phase the garbage collector then traverses the whole heap and
+frees any objects not marked before. The resulting released memory is sorted
+into the bins to be used for further allocations. If a chunk of address space
+is completely empty, it is decommitted, but the address space is retained
+(see \l{Basic Principles} above). If the memory usage grows again, the same
+address space is re-used.
+
+The garbage collector is triggered either manually by calling the \l [QML] {Qt::}{gc()} function
+or by a heuristic that takes the following aspects into account:
+
+\list
+\li The amount of memory managed by object on the JavaScript heap, but not
+ directly allocated on the JavaScript heap, such as strings and internal
+ class member data. A dynamic threshold is maintained for those. If it is
+ surpassed, the garbage collector runs and the threshold is increased. If
+ the amount of managed external memory falls far below the threshold, the
+ threshold is decreased.
+\li The total address space reserved. The internal memory allocation on the
+ JavaScript heap is only considered after at least some address space has
+ been reserved.
+\li The additional address space reservation since the last garbage collector
+ run. If the amount of address space is more than double the amount of
+ used memory after the last garbage collector run, we run the garbage
+ collector again.
+\endlist
+
+\section1 Analyzing Memory Usage
+
+In order to observe the development of both the address space and the number
+of objects allocated in it, it is best to use a specialized tool. The
+\l{Qt Creator: QML Profiler}{QML Profiler} provides a visualization that
+helps here. More generic tools cannot see what the JavaScript memory manager
+does within the address space it reserves and may not even notice that part
+of the address space is not committed to physical memory.
+
+Another way to debug memory usage are the
+\l{QLoggingCategory}{logging categories} \e{qt.qml.gc.statistics} and
+\e{qt.qml.gc.allocatorStats}. If you enable the \e{Debug} level for
+qt.qml.gc.statistics, the garbage collector will print some information every
+time it runs:
+
+\list
+\li How much total address space is reserved
+\li How much memory was in use before and after the garbage collection
+\li How many objects of various sizes were allocated so far
+\endlist
+
+The \e{Debug} level for qt.qml.gc.allocatorStats prints more detailed
+statistics that also include how the garbage collector was triggered, timings
+for the mark and sweep phases and a detailed breakdown of memory usage by bytes
+and chunks of address space.
+
+*/
diff --git a/src/qml/doc/src/javascript/number.qdoc b/src/qml/doc/src/javascript/number.qdoc
index 288232255c..a37fd8051b 100644
--- a/src/qml/doc/src/javascript/number.qdoc
+++ b/src/qml/doc/src/javascript/number.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2017 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\qmltype Number
@@ -58,21 +34,32 @@
If \a locale is not specified, the default locale will be used.
The following example shows a number formatted for the German locale:
- \code
+ \qml
import QtQuick 2.0
Text {
text: "The value is: " + Number(4742378.423).toLocaleString(Qt.locale("de_DE"))
}
- \endcode
+ \endqml
+
+ You can customize individual fields of the \a{locale} to tightly control
+ the output:
+ \qml
+ let locale = Qt.locale("de_DE");
+ let a = Number(1000).toLocaleString(locale)); // a == 1.000,00
+ locale.numberOptions = Locale.OmitGroupSeparator;
+ let b = Number(1000).toLocaleString(locale)); // b == 1000,00
+ \endqml
You can apply toLocaleString() directly to constants, provided the decimal
is included in the constant, e.g.
- \code
+ \qml
123.0.toLocaleString(Qt.locale("de_DE")) // OK
123..toLocaleString(Qt.locale("de_DE")) // OK
123.toLocaleString(Qt.locale("de_DE")) // fails
- \endcode
+ \endqml
+
+ \sa {QtQml::Locale}{Locale}
*/
/*!
@@ -93,12 +80,14 @@
If \a locale is not supplied the default locale will be used.
For example, using the German locale:
- \code
+ \qml
var german = Qt.locale("de_DE");
var d;
d = Number.fromLocaleString(german, "1234,56") // d == 1234.56
d = Number.fromLocaleString(german, "1.234,56") // d == 1234.56
d = Number.fromLocaleString(german, "1234.56") // throws exception
d = Number.fromLocaleString(german, "1.234") // d == 1234.0
- \endcode
+ \endqml
+
+ \sa {QtQml::Locale}{Locale}
*/
diff --git a/src/qml/doc/src/javascript/qmlglobalobject.qdoc b/src/qml/doc/src/javascript/qmlglobalobject.qdoc
index bba796f9ea..1bd03fad54 100644
--- a/src/qml/doc/src/javascript/qmlglobalobject.qdoc
+++ b/src/qml/doc/src/javascript/qmlglobalobject.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtqml-javascript-qmlglobalobject.html
\title QML Global Object
@@ -31,100 +7,27 @@
The QML JavaScript host environment implements the following host objects and functions.
-These are built in and can be used from any JavaScript code loaded in QML, without
+They are built-in, so you can use them from any JavaScript code loaded in QML, without
additional imports:
\list
-\li The \l{QmlGlobalQtObject}{Qt object}: This object is specific to QML, and provides helper methods
+\li The \l{QmlGlobalQtObject}{Qt object}: A QML object that offers helper methods
and properties specific to the QML environment.
-\li qsTr(), qsTranslate(), qsTrId(), QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and QT_TRID_NOOP() functions:
- These functions are specific to QML, and provide \l{Overview of the Translation Process}{translation capabilities} to the QML environment.
-\li gc() function: This function is specific to QML, and provides a way to manually trigger garbage collection.
-\li print() function: This function is specific to QML, and provides a simple way to output information to the console.
-\li The \l{Console API}{console object}: This object implements a subset of the \l{http://getfirebug.com/wiki/index.php/Console_API}{FireBug Console API}.
-\li \l{XMLHttpRequest}, DOMException: These objects implement a subset of the \l{http://www.w3.org/TR/XMLHttpRequest/}{W3C XMLHttpRequest specification}.
-\endlist
-
-\note The \l {QJSEngine::}{globalObject()} function cannot be used to modify
-the global object of a \l QQmlEngine. For more information about this, see
+\li \l {Qt::}{qsTr()}, \l {Qt::}{qsTranslate()}, \l {Qt::}{qsTrId()}, \l {Qt::}{QT_TR_NOOP()()},
+ \l {Qt::}{QT_TRANSLATE_NOOP()}, \l {Qt::}{QT_TRID_NOOP()} functions:
+ QML functions that let you translate \l{Mark Strings for Translation}
+ {strings} and \l{Mark Translatable Data Text Strings}{string literals} in the
+ QML environment.
+\li gc() function: A QML function that manually triggers garbage collection.
+\li print() function: A QML function that prints output to the console.
+\li The \l{Console API}{console object}: Implements a subset of the
+ \l{http://getfirebug.com/wiki/index.php/Console_API}{FireBug Console API}.
+\li \l{XMLHttpRequest}, DOMException: Implements a subset of the
+ \l{http://www.w3.org/TR/XMLHttpRequest/}{W3C XMLHttpRequest specification}.
+\endlist
+
+\note You cannot use the \l {QJSEngine::}{globalObject()} function to change
+the global object of a \l QQmlEngine. For more information, see
\l {JavaScript Environment Restrictions}.
-\target XMLHttpRequest
-\section1 XMLHttpRequest
-
-The XMLHttpRequest object, which can be used to asynchronously obtain
-data from over a network.
-
-The XMLHttpRequest API implements the same \l {http://www.w3.org/TR/XMLHttpRequest/}{W3C standard}
-as many popular web browsers with following exceptions:
-\list
-\li QML's XMLHttpRequest does not enforce the same origin policy.
-\endlist
-
-Additionally, the \c responseXML XML DOM tree currently supported by QML is a reduced subset
-of the \l {http://www.w3.org/TR/DOM-Level-3-Core/}{DOM Level 3 Core} API supported in a web
-browser. The following objects and properties are supported by the QML implementation:
-
-\table
-\header
-\li \b {Node}
-\li \b {Document}
-\li \b {Element}
-\li \b {Attr}
-\li \b {CharacterData}
-\li \b {Text}
-
-\row
-\li
-\list
-\li nodeName
-\li nodeValue
-\li nodeType
-\li parentNode
-\li childNodes
-\li firstChild
-\li lastChild
-\li previousSibling
-\li nextSibling
-\li attributes
-\endlist
-
-\li
-\list
-\li xmlVersion
-\li xmlEncoding
-\li xmlStandalone
-\li documentElement
-\endlist
-
-\li
-\list
-\li tagName
-\endlist
-
-\li
-\list
-\li name
-\li value
-\li ownerElement
-\endlist
-
-\li
-\list
-\li data
-\li length
-\endlist
-
-\li
-\list
-\li isElementContentWhitespace
-\li wholeText
-\endlist
-
-\endtable
-
-The \l{Qt Quick Examples - XMLHttpRequest}{XMLHttpRequest example} demonstrates
-how to use the XMLHttpRequest object to make a request and read the response
-headers.
-
*/
diff --git a/src/qml/doc/src/javascript/qtjavascript.qdoc b/src/qml/doc/src/javascript/qtjavascript.qdoc
index aa4dce6a37..d226b4428e 100644
--- a/src/qml/doc/src/javascript/qtjavascript.qdoc
+++ b/src/qml/doc/src/javascript/qtjavascript.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2017 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtjavascript.html
diff --git a/src/qml/doc/src/javascript/resources.qdoc b/src/qml/doc/src/javascript/resources.qdoc
index 60f97c2007..d60101806a 100644
--- a/src/qml/doc/src/javascript/resources.qdoc
+++ b/src/qml/doc/src/javascript/resources.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2017 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtqml-javascript-resources.html
\title Defining JavaScript Resources in QML
diff --git a/src/qml/doc/src/javascript/string.qdoc b/src/qml/doc/src/javascript/string.qdoc
deleted file mode 100644
index 47922ff17a..0000000000
--- a/src/qml/doc/src/javascript/string.qdoc
+++ /dev/null
@@ -1,50 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \qmltype String
- \inqmlmodule QtQml
- \brief The String object represents a string value.
-
- The QML String object extends the JS String object with
- the arg() function.
-
- \sa {ECMA-262}{ECMAScript Language Specification}
-*/
-
-/*!
- \qmlmethod string String::arg(value)
-
- Returns a copy of this string with the lowest numbered place marker replaced by \a value,
- i.e., %1, %2, ..., %99. The following example prints "There are 20 items":
-
- \code
- var message = "There are %1 items"
- var count = 20
- console.log(message.arg(count))
- \endcode
-*/
diff --git a/src/qml/doc/src/javascript/topic.qdoc b/src/qml/doc/src/javascript/topic.qdoc
index 05fb1ddfdc..2302f90fbe 100644
--- a/src/qml/doc/src/javascript/topic.qdoc
+++ b/src/qml/doc/src/javascript/topic.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2017 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtqml-javascript-topic.html
\title Integrating QML and JavaScript
@@ -48,6 +24,25 @@ See the documentation page titled
\l{qtqml-javascript-expressions.html}{JavaScript Expressions in QML Documents}
for more information about using JavaScript expressions in QML.
+\section1 Dynamic QML Object Creation from JavaScript
+
+QML supports the dynamic creation of objects from within JavaScript. This is
+useful to delay instantiation of objects until necessary, thereby improving
+application startup time. It also allows visual objects to be dynamically
+created and added to the scene in reaction to user input or other events. This
+functionality can be used in two main ways.
+
+Object can be created dynamically from JavaScript in an imperative way using
+\l{qtqml-javascript-dynamicobjectcreation.html}{dynamic creation of objects}.
+This can be useful, for example, when QML is used as an application scripting
+language.
+
+\note When creating user interfaces, the preferred way of creating objects
+dynamically is to use declarative constructs as these integrate best with the
+QML engine and tooling. Various types exist to enable this functionality such
+as the \l{Loader}, \l{Instantiator}, \l{Repeater} types.
+
+
\section1 JavaScript Resources
Application logic defined in JavaScript functions may be separated into
@@ -81,11 +76,15 @@ These limitations and extensions are documented in the description of the
\l{qtqml-javascript-hostenvironment.html}{JavaScript Host Environment} provided
by the QML engine.
-\section1 Fine Tuning the JavaScript engine
+There is also an in depth description of the
+\l{qtqml-javascript-memory.html}{memory management} employed by the JavaScript
+engine.
+
+\section1 Configuring the JavaScript engine
For specific use cases you may want to override some of the parameters the
JavaScript engine uses for handling memory and compiling JavaScript. See
-\l{qtqml-javascript-finetuning.html}{Fine Tuning the JavaScript engine} for
+\l{qtqml-javascript-finetuning.html}{Configuring the JavaScript engine} for
more information on these parameters.
*/
diff --git a/src/qml/doc/src/javascript/xmlhttprequest.qdoc b/src/qml/doc/src/javascript/xmlhttprequest.qdoc
new file mode 100644
index 0000000000..b8624073c5
--- /dev/null
+++ b/src/qml/doc/src/javascript/xmlhttprequest.qdoc
@@ -0,0 +1,301 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+ \qmltype XMLHttpRequest
+ \inqmlmodule QtQml
+ \brief Object for sending requests to a server.
+
+ The \c XMLHttpRequest object allows scripts to perform HTTP client functionality,
+ such as submitting form data or loading data asynchronously from a server.
+
+ The \c XMLHttpRequest API is a partial implementation of the
+ \l {https://www.w3.org/TR/2014/WD-XMLHttpRequest-20140130/}{W3C XHR Level 1 standard}
+ with the following exception:
+ \list
+ \li It does not enforce the same origin policy.
+ \endlist
+
+ \section1 Sending requests
+
+ Use the following steps to send a request using the \c XMLHttpRequest API:
+ \list 1
+ \li Create a \c XMLHttpRequest object.
+ \li Assign a callback function to the \l {XMLHttpRequest::onreadystatechange}{onreadystatechange} signal handler.
+ \li Call \l {XMLHttpRequest::open}{open()} with the appropriate HTTP method and URL to request.
+ \li Call \l {XMLHttpRequest::send}{send()}
+ \endlist
+
+ The callback function handles the HTTP response for a request.
+ It's a good practice to check if the \l{XMLHttpRequest::readyState}{readyState} is \c DONE in the handler,
+ before you use one of the following methods to read the response:
+ \list
+ \li \l {XMLHttpRequest::response}{response}
+ \li \l {XMLHttpRequest::responseText}{responseText}
+ \li \l {XMLHttpRequest::responseXML}{responseXML}
+ \endlist
+
+ The following example demonstrates how to send a request and read the response:
+
+ \snippet qml/XHRForm.qml 0
+
+ The earlier snippet connects the button's clicked signal to an external \c sendRequest function.
+ A resource URL is passed as the first argument, and a callback function to handle UI updates is passed as the second.
+ The \c sendRequest function, which exists in an external \c request.js file, can be implemented like this:
+
+ \snippet qml/xmlhttprequest.js 0
+
+ The earlier snippet follows the four simple steps mentioned at the beginning.
+ It instantiates the \c XMLHttpRequest object first, and assigns a callback function to handle the response.
+ It also calls \l {XMLHttpRequest::open}{open()} with an HTTP method and URL, before it sends the request to the server.
+ Notice that the second argument to \c sendRequest is called at the end of \l {XMLHttpRequest::onreadystatechange}{onreadystatechange},
+ in order to handle UI updates based on the HTTP response.
+
+ Set the \c QML_XHR_DUMP environment variable to \c 1 if you want to debug a request.
+ This will log the following information:
+ \list
+ \li Method type (GET or POST), URL, and body of sent requests.
+ \li URL and body of responses received.
+ \li Network error, if any.
+ \endlist
+
+ \section1 Accessing local files
+
+ By default, you cannot use the \c XMLHttpRequest object to read files from your local file system.
+ If you wish to use this feature to access local files, you can set the following environment variables to \c 1.
+ \list
+ \li QML_XHR_ALLOW_FILE_READ
+ \li QML_XHR_ALLOW_FILE_WRITE
+ \endlist
+ \warning Use this feature only if you know that the application runs trusted QML and JavaScript code.
+
+ \section1 responseXML document
+
+ The \c responseXML XML DOM tree currently supported by QML is a reduced subset of
+ the \l {http://www.w3.org/TR/DOM-Level-3-Core/}{DOM Level 3 Core} API supported in a web browser.
+ The following objects and properties are supported by the QML implementation:
+
+ \table
+ \header
+ \li \b {Node}
+ \li \b {Document}
+ \li \b {Element}
+ \li \b {Attr}
+ \li \b {CharacterData}
+ \li \b {Text}
+
+ \row
+ \li
+ \list
+ \li nodeName
+ \li nodeValue
+ \li nodeType
+ \li parentNode
+ \li childNodes
+ \li firstChild
+ \li lastChild
+ \li previousSibling
+ \li nextSibling
+ \li attributes
+ \endlist
+
+ \li
+ \list
+ \li xmlVersion
+ \li xmlEncoding
+ \li xmlStandalone
+ \li documentElement
+ \endlist
+
+ \li
+ \list
+ \li tagName
+ \endlist
+
+ \li
+ \list
+ \li name
+ \li value
+ \li ownerElement
+ \endlist
+
+ \li
+ \list
+ \li data
+ \li length
+ \endlist
+
+ \li
+ \list
+ \li isElementContentWhitespace
+ \li wholeText
+ \endlist
+
+ \endtable
+*/
+
+/*!
+ \qmlmethod void XMLHttpRequest::abort()
+
+ Cancels the current request.
+
+ It changes the \l {XMLHttpRequest::readyState}{readyState} property to be \c XMLHttpRequest.UNSENT and emits the \c readystatechange signal.
+*/
+
+/*!
+ \qmlmethod string XMLHttpRequest::getAllResponseHeaders()
+
+ Returns a \c String of headers received from the last response.
+
+ The following is an example response header:
+ \code
+ content-encoding: gzip
+ content-type: text/html; charset=UTF-8
+ date: Mon, 06 Feb 2023 09:00:08 GMT
+ expires: Mon, 13 Feb 2023 09:00:08 GMT
+ last-modified: Thu, 17 Oct 2019 07:18:26 GMT
+ \endcode
+
+ \sa {XMLHttpRequest::getResponseHeader}{getResponseHeader()}
+*/
+
+/*!
+ \qmlmethod string XMLHttpRequest::getResponseHeader(headerName)
+
+ Returns either the \a headerName value from the last response, or an empty \c String, if the \a headerName is missing.
+
+ \sa {XMLHttpRequest::getAllResponseHeaders}{getAllResponseHeaders()}
+*/
+
+/*!
+ \qmlmethod void XMLHttpRequest::open(method, url, async)
+
+ Specify the HTTP \a method you want the request to use, as well as the \a url you wish to request.
+ You should make sure to always call this function before \l {XMLHttpRequest::send}{send()}.
+ An optional third parameter \a async can be used to decide whether the request should be asynchronous or not.
+ The default value is \c true.
+
+ Emits the \c readystatechange signal, which calls the \l {XMLHttpRequest::onreadystatechange}{onreadystatechange} handler with
+ the \l {XMLHttpRequest::readyState}{readyState} property set to \c XMLHttpRequest.OPENED.
+*/
+
+/*!
+ \qmlmethod void XMLHttpRequest::send(data)
+
+ Sends the request to the server.
+ You can use the optional argument \a data to add extra data to the body of the request.
+ This can be useful for POST requests, where you typically want the request to contain extra data.
+
+ The \l {XMLHttpRequest::readyState}{readyState} property is updated once a response has been received from the server,
+ and while the response is being processed. It will first be set to \c HEADERS_RECEIVED, then to \c LOADING,
+ and finally \c DONE, once the response has been fully processed.
+ The \c readystatechange signal is emitted every time \l {XMLHttpRequest::readyState}{readyState} is updated.
+*/
+
+/*!
+ \qmlmethod void XMLHttpRequest::setRequestHeader(header, value)
+
+ Adds a new header to the next request you wish to send.
+ This is a key-value pair, which has the name \a header and the corresponding \a value.
+*/
+
+/*!
+ \qmlmethod void XMLHttpRequest::overrideMimeType(mime)
+ \since 6.6
+
+ Forces the \c XMLHttpRequest to interpret the data received in the next HTTP response,
+ as if it had the MIME type \a mime, rather than the one provided by the server.
+*/
+
+/*!
+ \qmlproperty function XMLHttpRequest::onreadystatechange
+
+ Choose a callback function you want to get invoked whenever the \l {XMLHttpRequest::readyState}{readyState} of the \c XMLHttpRequest object changes.
+
+ \sa {XMLHttpRequest::readyState}{readyState}
+*/
+
+/*!
+ \qmlproperty enumeration XMLHttpRequest::readyState
+ \readonly
+
+ Indicates the current state of the \c XMLHttpRequest object.
+
+ The value can be one of the following:
+ \value XMLHttpRequest.UNSENT The request is not initialized, which is the state before calling \l {XMLHttpRequest::open}{open()}.
+ \value XMLHttpRequest.OPENED The request is initialized, meaning \l {XMLHttpRequest::open}{open()} was previously called, but no further progress.
+ \value XMLHttpRequest.HEADERS_RECEIVED Received a reply from the sever, but the request is not fully processed yet.
+ \value XMLHttpRequest.LOADING Downloading data from the server.
+ \value XMLHttpRequest.DONE Finished processing the request.
+
+ \sa {XMLHttpRequest::onreadystatechange}{onreadystatechange}
+*/
+
+/*!
+ \qmlproperty string XMLHttpRequest::responseURL
+ \readonly
+ \since 6.6
+
+ Returns the url that was used to retrieve the response data, after any redirects have occurred.
+*/
+
+/*!
+ \qmlproperty string XMLHttpRequest::responseText
+ \readonly
+
+ Returns a \c String containing the data received from the last response.
+
+ \sa {XMLHttpRequest::responseXML}{responseXML}
+*/
+
+/*!
+ \qmlproperty var XMLHttpRequest::responseXML
+ \readonly
+
+ Returns either a \c Document, or \c null, if the response content cannot be parsed as XML or HTML.
+ See the \l {responseXML document}{responseXML document} section for more information.
+
+ \sa {XMLHttpRequest::responseText}{responseText}
+*/
+
+/*!
+ \qmlproperty var XMLHttpRequest::response
+ \readonly
+
+ Returns either a \c String, an \c ArrayBuffer, or a \c Document,
+ depending on the \l {XMLHttpRequest::responseType}{responseType} of the last request.
+
+ \sa {XMLHttpRequest::responseType}{responseType}, {XMLHttpRequest::responseText}{responseText}, {XMLHttpRequest::responseXML}{responseXML}
+*/
+
+/*!
+ \qmlproperty string XMLHttpRequest::responseType
+
+ Returns a \c String describing the content type of the last response received.
+ \list
+ \li If the response type is "text" or an empty \c String, the response content is a UTF-16 encoded \c String.
+ \li If the response type is "arraybuffer", it means that the response content is an \c ArrayBuffer containing binary data.
+ \li If the response type is "json", the response content should be a JSON \c Document.
+ \li If the response type is "document", it means that the response content is an XML \c Document, which can be safely read with the \l {XMLHttpRequest::responseXML}{responseXML} property.
+ \endlist
+
+ \sa {XMLHttpRequest::response}{response}
+*/
+
+/*!
+ \qmlproperty int XMLHttpRequest::status
+ \readonly
+
+ Returns the status code for the last response received.
+
+ \sa {XMLHttpRequest::statusText}{statusText}
+*/
+
+/*!
+ \qmlproperty string XMLHttpRequest::statusText
+ \readonly
+
+ Returns a \c String that has the status message associated with the status code for the last response received.
+
+ \sa {XMLHttpRequest::status}{status}
+*/
generated by cgit v1.2.3 (git 2.25.1) at 2024-06-20 17:39:57 +0000