hostenvironment.qdoc

Go to the documentation of this file.

// 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
\brief Description of the JavaScript host environment provided by the QML engine
 
 
QML provides a JavaScript host environment tailored to writing QML applications.
This environment is different from the host environment provided by a browser
or a server-side JavaScript environment such as Node.js. For example, QML does
not provide a \c window object or \c{DOM API} as commonly found in a browser environment.
 
\section1 Common Base
 
Like a browser or server-side JavaScript environment, the QML runtime implements the
\l{ECMA-262}{ECMAScript Language Specification} standard. This provides access to
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
Reference section). Many sites focus on JavaScript in the browser, so in some cases you may need to double
check the specification to determine whether a given function or object is part of standard ECMAScript or
specific to the browser environment. In the case of the W3Schools link above, the \c{JavaScript Objects
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} 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.
 
By default, type annotations are ignored by the interpreter and the JIT
compiler, but enforced by \l{qmlcachegen} and \l{qmlsc} when compiling to C++.
This can lead to differences in behavior if you either pass values that
are not actually of the declared type or if you modify instances of
\l{QML Value Types} passed as typed arguments. Value types are passed by
reference by the interpreter and JIT, but by value when compiled to C++.
 
You can eliminate those differences by either forcing the interpreter and JIT
to also respect type annotations or by having \l{qmlcachegen} and \l{qmlsc}
ignore type annotations. The former has a performance cost when using the
interpreter or JIT, the latter makes the compilation to C++ avoid any JavaScript
functions, and any bindings and signal handlers that call JavaScript functions.
Therefore less code will be compiled to C++.
 
In order to always enforce type annotations, add the following to your QML
document:
\qml
pragma FunctionSignatureBehavior: Enforced
\endqml
 
In order to always ignore type annotations, add the following instead:
\qml
pragma FunctionSignatureBehavior: Ignored
\endqml
 
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.
 
\section1 QML Global Object
 
The QML JavaScript host environment implements a number of host objects and functions, as
detailed in the \l{QML Global Object} documentation.
 
These host objects and functions are always available, regardless of whether any modules
have been imported.
 
 
\section1 JavaScript Objects and Functions
 
A list of the JavaScript objects, functions and properties supported by the
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()} function is added to the \c String prototype.
\li Locale-aware conversion functions are added to the \l Date and \l Number prototypes.
\endlist
 
In addition, QML also extends the behavior of the instanceof function to
allow for type checking against QML types. This means that you may use it to
verify that a variable is indeed the type you expect, for example:
 
\qml
    var v = something();
    if (!v instanceof Item) {
        throw new TypeError("I need an Item type!");
    }
 
    ...
\endqml
 
 
\section1 JavaScript Environment Restrictions
 
QML implements the following restrictions for JavaScript code:
 
\list
\li JavaScript code written in a \c .qml file cannot modify the global object.
    JavaScript code in a .js file can modify the global object,
    and those modifications will be visible to the .qml file when
    \l {Importing a JavaScript Resource from a QML Document}{imported}.
 
In QML, the global object is constant - existing properties cannot be modified
or deleted, and no new properties may be created.
 
Most JavaScript programs do not intentionally modify the global object.
However, JavaScript's automatic creation of undeclared variables is an implicit
modification of the global object, and is prohibited in QML.
 
Assuming that the \c a variable does not exist in the scope chain, the
following code is illegal in QML:
 
\code
// Illegal modification of undeclared variable
a = 1;
for (var ii = 1; ii < 10; ++ii)
    a = a * ii;
console.log("Result: " + a);
\endcode
 
It can be trivially modified to this legal code.
 
\code
var a = 1;
for (var ii = 1; ii < 10; ++ii)
    a = a * ii;
console.log("Result: " + a);
\endcode
 
Any attempt to modify the global object - either implicitly or explicitly - will
cause an exception.  If uncaught, this will result in a warning being printed,
that includes the file and line number of the offending code.
 
\li Global code is run in a reduced scope.
 
During startup, if a QML file includes an external JavaScript file with "global"
code, it is executed in a scope that contains only the external file itself and
the global object.  That is, it will not have access to the QML objects and
properties it \l {Scope and Naming Resolution}{normally would}.
 
Global code that only accesses script local variables is permitted.  This is an
example of valid global code.
 
\code
var colors = [ "red", "blue", "green", "orange", "purple" ];
\endcode
 
Global code that accesses QML objects will not run correctly.
 
\code
// Invalid global code - the "rootObject" variable is undefined
var initialPosition = { rootObject.x, rootObject.y }
\endcode
 
This restriction exists as the QML environment is not yet fully established.
To run code after the environment setup has completed, see
\l {JavaScript in Application Startup Code}.
 
\li The value of \c this is undefined in QML in the majority of contexts.
 
The \c this keyword is supported when binding properties from JavaScript.
In QML binding expressions, QML signal handlers, and QML declared functions,
\c this refers to the scope object. In all other situations, the value of
\c this is undefined in QML.
 
To refer to a specific object, provide an \c id.  For example:
 
\qml
Item {
    width: 200; height: 100
    function mouseAreaClicked(area) {
        console.log("Clicked in area at: " + area.x + ", " + area.y);
    }
    // This will pass area to the function
    MouseArea {
        id: area
        y: 50; height: 50; width: 200
        onClicked: mouseAreaClicked(area)
    }
}
\endqml
 
\sa {Scope and Naming Resolution}
 
\endlist
 
 
 
*/