1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
4\page qtqml-javascript-hostenvironment.html
5\title JavaScript Host Environment
6\brief Description of the JavaScript host environment provided by the QML engine
9QML provides a JavaScript host environment tailored to writing QML applications.
10This environment is different from the host environment provided by a browser
11or a server-side JavaScript environment such as Node.js. For example, QML does
12not provide a \c window object or \c{DOM API} as commonly found in a browser environment.
16Like a browser or server-side JavaScript environment, the QML runtime implements the
17\l{ECMA-262}{ECMAScript Language Specification} standard. This provides access to
18all of the built-in types and functions defined by the standard, such as Object, Array, and Math.
19The QML runtime implements the 7th edition of the standard.
21\l{Nullish Coalescing} (\c{??}) (since Qt 5.15) and \l{Optional Chaining} (\c{?.}) (since Qt 6.2)
22are also implemented in the QML runtime.
24The standard ECMAScript built-ins are not explicitly documented in the QML documentation. For more
25information on their use, please refer to the ECMA-262 7th edition standard or one of the many online
26JavaScript reference and tutorial sites, such as the \l{W3Schools JavaScript Reference} (JavaScript Objects
27Reference section). Many sites focus on JavaScript in the browser, so in some cases you may need to double
28check the specification to determine whether a given function or object is part of standard ECMAScript or
29specific to the browser environment. In the case of the W3Schools link above, the \c{JavaScript Objects
30Reference} section generally covers the standard, while the \c{Browser Objects Reference} and \c{HTML DOM
31Objects Reference} sections are browser specific (and thus not applicable to QML).
33\section1 Type annotations and assertions
35Function declarations in QML documents can, and should, contain type
36annotations. Type annotations are appended to the declaration of arguments and
37to the function itself, for annotating the return type. The following function
38takes an \c int and a \c string parameter, and returns a \c QtObject:
41function doThings(a: int, b: string) : QtObject { ... }
44Type annotations help tools like \l{Qt Creator} and \l{qmllint Reference}{qmllint} to make sense
45of the code and provide better diagnostics. Moreover, they make functions easier
47\l {qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++}
50Type assertions (sometimes called \e as-casts) can also be used in order to cast an object to a
51different object type. If the object is actually of the given type, then the type assertion returns
52the same object. If not, it returns \c null. In the following snippet we assert that the \c parent
53object is a \c Rectangle before accessing a specific member of it.
57 property color parentColor: (parent as Rectangle)?.color || "red"
61The optional chaining (\c{?.}) avoids throwing an exception if the parent is
62actually not a rectangle. In that case "red" is chosen as \c parentColor.
64Since Qt 6.7 type annotations are always enforced when calling functions. Values
65are coerced to the required types as necessary. Previously, type annotations were
66ignored by the interpreter and the JIT compiler, but enforced by \l{qmlcachegen}
67and \l{qmlsc} when compiling to C++. This could lead to differences in behavior in
68some corner cases. In order to explicitly request the old behavior of the
69interpreter and JIT you can add the following to your QML document:
72pragma FunctionSignatureBehavior: Ignored
75\section1 QML Global Object
77The QML JavaScript host environment implements a number of host objects and functions, as
78detailed in the \l{QML Global Object} documentation.
80These host objects and functions are always available, regardless of whether any modules
84\section1 JavaScript Objects and Functions
86A list of the JavaScript objects, functions and properties supported by the
87QML engine can be found in the \l{List of JavaScript Objects and Functions}.
89Note that QML makes the following modifications to native objects:
92\li An \l {string}{arg()} function is added to the \c String prototype.
93\li Locale-aware conversion functions are added to the \l Date and \l Number prototypes.
96In addition, QML also extends the behavior of the instanceof function to
97allow for type checking against QML types. This means that you may use it to
98verify that a variable is indeed the type you expect, for example:
102 if (!v instanceof Item) {
103 throw new TypeError("I need an Item type!");
110\section1 JavaScript Environment Restrictions
112QML implements the following restrictions for JavaScript code:
115\li JavaScript code written in a \c .qml file cannot modify the global object.
116 JavaScript code in a .js file can modify the global object,
117 and those modifications will be visible to the .qml file when
118 \l {Importing a JavaScript Resource from a QML Document}{imported}.
120In QML, the global object is constant - existing properties cannot be modified
121or deleted, and no new properties may be created.
123Most JavaScript programs do not intentionally modify the global object.
124However, JavaScript's automatic creation of undeclared variables is an implicit
125modification of the global object, and is prohibited in QML.
127Assuming that the \c a variable does not exist in the scope chain, the
128following code is illegal in QML:
131// Illegal modification of undeclared variable
133for (var ii = 1; ii < 10; ++ii)
135console.log("Result: " + a);
138It can be trivially modified to this legal code.
142for (var ii = 1; ii < 10; ++ii)
144console.log("Result: " + a);
147Any attempt to modify the global object - either implicitly or explicitly - will
148cause an exception. If uncaught, this will result in a warning being printed,
149that includes the file and line number of the offending code.
151\li Global code is run in a reduced scope.
153During startup, if a QML file includes an external JavaScript file with "global"
154code, it is executed in a scope that contains only the external file itself and
155the global object. That is, it will not have access to the QML objects and
156properties it \l {Scope and Naming Resolution}{normally would}.
158Global code that only accesses script local variables is permitted. This is an
159example of valid global code.
162var colors = [ "red", "blue", "green", "orange", "purple" ];
165Global code that accesses QML objects will not run correctly.
168// Invalid global code - the "rootObject" variable is undefined
169var initialPosition = { rootObject.x, rootObject.y }
172This restriction exists as the QML environment is not yet fully established.
173To run code after the environment setup has completed, see
174\l {JavaScript in Application Startup Code}.
176\li The value of \c this is undefined in QML in the majority of contexts.
178The \c this keyword is supported when binding properties from JavaScript.
179In QML binding expressions, QML signal handlers, and QML declared functions,
180\c this refers to the scope object. In all other situations, the value of
181\c this is undefined in QML.
183To refer to a specific object, provide an \c id. For example:
187 width: 200; height: 100
188 function mouseAreaClicked(area) {
189 console.log("Clicked in area at: " + area.x + ", " + area.y);
191 // This will pass area to the function
194 y: 50; height: 50; width: 200
195 onClicked: mouseAreaClicked(area)
200\sa {Scope and Naming Resolution}