diff options
Diffstat (limited to 'src/qml/doc/src/javascript/hostenvironment.qdoc')
| -rw-r--r-- | src/qml/doc/src/javascript/hostenvironment.qdoc | 74 |
1 files changed, 46 insertions, 28 deletions
diff --git a/src/qml/doc/src/javascript/hostenvironment.qdoc b/src/qml/doc/src/javascript/hostenvironment.qdoc index bc75f843fb..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,7 +18,8 @@ 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. -Since Qt 5.15 \l{Nullish Coalescing} is also implemented in the QML runtime. +\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 @@ -53,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 @@ -71,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 |