expressions.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-expressions.html
\title JavaScript Expressions in QML Documents
\brief Description of where JavaScript expressions are valid in QML documents
 
 
The \l{JavaScript Host Environment} provided by QML can run valid standard
JavaScript constructs such as conditional operators, arrays, variable setting,
and loops. In addition to the standard JavaScript properties, the \l {QML Global
Object} includes a number of helper methods that simplify building UIs and
interacting with the QML environment.
 
The JavaScript environment provided by QML is stricter than that in a web
browser. For example, in QML you cannot add to, or modify, members of the
JavaScript global object. In regular JavaScript, it is possible to do this
accidentally by using a variable without declaring it. In QML this will throw
an exception, so all local variables must be explicitly declared. See
\l{JavaScript Environment Restrictions} for a complete description of the
restrictions on JavaScript code executed from QML.
 
Various parts of \l{QML Documents}{QML documents} can contain JavaScript code:
 
\list 1
  \li The body of \l{Property Binding}{property bindings}. These JavaScript
      expressions describe relationships between QML object \l{Property Attributes}
      {properties}. When \e dependencies of a property change, the property
      is automatically updated too, according to the specified relationship.
  \li The body of \l{Signal Attributes}{Signal handlers}. These JavaScript
      statements are automatically evaluated whenever a QML object emits the
      associated signal.
  \li The definition of \l{Method Attributes}{custom methods}. JavaScript functions
      that are defined within the body of a QML object become methods of that
      object.
  \li Standalone \l{Importing JavaScript Resources in QML}{JavaScript resource
      (.js) files}. These files are actually separate from QML documents, but
      they can be imported into QML documents. Functions and variables that are
      defined within the imported files can be used in property bindings, signal
      handlers, and custom methods.
\endlist
 
 
 
\section1 JavaScript in property bindings
 
In the following example, the \c color property of \l Rectangle depends on the
\c pressed property of \l TapHandler. This relationship is described using a
conditional expression:
 
\qml
import QtQuick 2.12
 
Rectangle {
    id: colorbutton
    width: 200; height: 80;
 
    color: inputHandler.pressed ? "steelblue" : "lightsteelblue"
 
    TapHandler {
        id: inputHandler
    }
}
\endqml
 
In fact, any JavaScript expression (no matter how complex) may be used in a
property binding definition, as long as the result of the expression is a
value whose type can be assigned to the property. This includes side effects.
However, complex bindings and side effects are discouraged because they can
reduce the performance, readability, and maintainability of the code.
 
There are two ways to define a property binding: the most common one
is shown in the example earlier, in a \l{QML Object Attributes#Value Assignment on Initialization}
{property initialization}. The second (and much rarer) way is to assign the
property a function returned from the \l{Qt::binding()}{Qt.binding()} function,
from within imperative JavaScript code, as shown below:
 
\qml
import QtQuick 2.12
 
Rectangle {
    id: colorbutton
    width: 200; height: 80;
 
    color: "red"
 
    TapHandler {
        id: inputHandler
    }
 
    Component.onCompleted: {
        color = Qt.binding(function() { return inputHandler.pressed ? "steelblue" : "lightsteelblue" });
    }
}
\endqml
 
See the \l{Property Binding}{property bindings} documentation for more
information about how to define property bindings, and see the documentation
about \l{qml-javascript-assignment}
{Property Assignment versus Property Binding} for information about how
bindings differ from value assignments.
 
\section1 JavaScript in signal handlers
 
QML object types can emit signals in reaction to certain events occurring.
Those signals can be handled by signal handler functions, which can be defined
by clients to implement custom program logic.
 
Suppose that a button represented by a Rectangle type has a TapHandler and a
Text label. The TapHandler emits its \l{TapHandler::}{tapped} signal when the
user presses the button. The clients can react to the signal in the \c onTapped
handler using JavaScript expressions. The QML engine executes these JavaScript
expressions defined in the handler as required. Typically, a signal handler is
bound to JavaScript expressions to initiate other events or to assign property
values.
 
\qml
import QtQuick 2.12
 
Rectangle {
    id: button
    width: 200; height: 80; color: "lightsteelblue"
 
    TapHandler {
        id: inputHandler
        onTapped: {
            // arbitrary JavaScript expression
            console.log("Tapped!")
        }
    }
 
    Text {
        id: label
        anchors.centerIn: parent
        text: inputHandler.pressed ? "Pressed!" : "Press here!"
    }
}
\endqml
 
For more details about signals and signal handlers, refer to the following
topics:
 
\list
    \li \l{Signal and Handler Event System}
    \li \l{QML Object Attributes}
\endlist
 
\section1 JavaScript in standalone functions
 
Program logic can also be defined in JavaScript functions. These functions can
be defined inline in QML documents (as custom methods) or externally in
imported JavaScript files.
 
\section2 JavaScript in custom methods
 
Custom methods can be defined in QML documents and may be called from signal
handlers, property bindings, or functions in other QML objects. Such methods
are often referred to as \e{inline JavaScript functions} because their
implementation is included in the QML object type definition
(QML document), instead of in an external JavaScript file.
 
An example of an inline custom method is as follows:
 
\qml
import QtQuick 2.12
 
Item {
    function fibonacci(n){
        var arr = [0, 1];
        for (var i = 2; i < n + 1; i++)
            arr.push(arr[i - 2] + arr[i -1]);
 
        return arr;
    }
    TapHandler {
        onTapped: console.log(fibonacci(10))
    }
}
\endqml
 
The fibonacci function is run whenever the TapHandler emits a \c tapped signal.
 
\note The custom methods defined inline in a QML document are exposed to
other objects, and therefore inline functions on the root object in a QML
component can be invoked by callers outside the component. If this is not
desired, the method can be added to a non-root object or, preferably, written
in an external JavaScript file.
 
See the \l{QML Object Attributes} documentation for more information on
defining custom methods in QML using JavaScript.
 
\section2 Functions defined in a JavaScript file
 
Non-trivial program logic is best separated into a separate JavaScript file.
This file can be imported into QML using an \c import statement, like the
QML \l {QML Modules}{modules}.
 
For example, the \c {fibonacci()} method in the earlier example could be moved
into an external file named \c fib.js, and accessed like this:
 
\qml
import QtQuick 2.12
import "fib.js" as MathFunctions
 
Item {
    TapHandler {
        onTapped: console.log(MathFunctions.fibonacci(10))
    }
}
\endqml
 
For more information about loading external JavaScript files into QML, read
the section about \l{Importing JavaScript Resources in QML}.
 
\section2 Connecting signals to JavaScript functions
 
QML object types that emit signals also provide default signal handlers for
their signals, as described in the \l{JavaScript in signal handlers}{previous}
section. Sometimes, however, a client wants to trigger a function defined in a
QML object when another QML object emits a signal. Such scenarios can be handled
by a signal connection.
 
A signal emitted by a QML object may be connected to a JavaScript function
by calling the signal's \c connect() method and passing the JavaScript function
as an argument. For example, the following code connects the TapHandler's
\c tapped signal to the \c jsFunction() in \c script.js:
 
\table
\row
\li \snippet qml/integrating-javascript/connectjs.qml 0
\li \snippet qml/integrating-javascript/script.js 0
\endtable
 
The \c jsFunction() is called whenever the TapHandler's \c tapped signal
is emitted.
 
See \l{qtqml-syntax-signals.html}
{Connecting Signals to Methods and Signals} for more information.
 
\section1 JavaScript in application startup code
 
It is occasionally necessary to run some imperative code at application (or
component instance) startup. While it is tempting to just include the startup
script as \e {global code} in an external script file, this can have severe
limitations as the QML environment may not have been fully established. For
example, some objects might not have been created or some
\l {Property Binding}{property bindings} may not have been established. See
\l {JavaScript Environment Restrictions} for the exact limitations of global
script code.
 
A QML object emits the \c{Component.completed} \l{Signal and Handler Event
System#Attached Signal Handlers}{attached signal} when its instantiation is
complete. The JavaScript code in the corresponding \c{Component.onCompleted}
handler runs after the object is instantiated. Thus, the best place to write
application startup code is in the \c{Component.onCompleted} handler of the
top-level object, because this object emits \c{Component.completed} when the
QML environment is fully established.
 
For example:
 
\qml
import QtQuick 2.0
 
Rectangle {
    function startupFunction() {
        // ... startup code
    }
 
    Component.onCompleted: startupFunction();
}
\endqml
 
Any object in a QML file - including nested objects and nested QML component
instances - can use this attached property. If there is more than one
\c onCompleted() handler to execute at startup, they are run sequentially in
an undefined order.
 
Likewise, every \c Component emits a \l {Component::destruction}{destruction()}
signal just before being destroyed.
 
*/
 
/*
 \internal
    NOTE: TODO Qt 5.1: We are not sufficiently confident about the implementation of scarce
    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 valuetypes.qdoc. It should
    be enabled at the same time.
 
 
 
\section1 Scarce Resources in JavaScript
 
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:
 
\list
\li By default, a scarce resource is automatically released by the declarative engine as soon as evaluation of the expression in which the scarce resource is allocated is complete if there are no other references to the resource
\li A client may explicitly preserve a scarce resource, which will ensure that the resource will not be released until all references to the resource are released and the JavaScript engine runs its garbage collector
\li A client may explicitly destroy a scarce resource, which will immediately release the resource
\endlist
 
In most cases, allowing the engine to automatically release the resource is
the correct choice. In some cases, however, this may result in an invalid
variant being returned from a function in JavaScript, and in those cases it
may be necessary for clients to manually preserve or destroy resources for
themselves.
 
For the following examples, imagine that we have defined the following class:
 
\snippet qml/integrating-javascript/scarceresources/avatarExample.h 0
 
and that we have registered it with the QML type-system as follows:
 
\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
stored in a JavaScript object which can then be used within JavaScript. This
copy will take up valuable system resources, and so by default the scarce
resource copy in the JavaScript object will be released automatically by the
declarative engine once evaluation of the JavaScript expression is complete,
unless the client explicitly preserves it.
 
\section2 Example One: Automatic Release
 
In the following example, the scarce resource will be automatically released
after the binding evaluation is complete. Assume we have the following qml file:
 
\snippet qml/integrating-javascript/scarceresources/exampleOne.qml 0
 
And then use it from C++:
 
\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 1
 
\section2 Example Two: Automatic Release Prevented By Reference
 
In this example, the resource will not be automatically
released after the binding expression evaluation is
complete, because there is a property var referencing the
scarce resource.
 
\snippet qml/integrating-javascript/scarceresources/exampleTwo.qml 0
 
And from C++:
 
\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 2
 
\section2 Example Three: Explicit Preservation
 
In this example, the resource must be explicitly preserved in order
to prevent the declarative engine from automatically releasing the
resource after evaluation of the imported script.
 
We create a JavaScript file:
\snippet qml/integrating-javascript/scarceresources/exampleThree.js 0
 
Import it in QML:
\snippet qml/integrating-javascript/scarceresources/exampleThree.qml 0
 
Run it in C++:
\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 3
 
\section2 Example Four: Explicit Destruction
 
In the following example, we release (via destroy()) an explicitly preserved
scarce resource variant. This example shows how a client may free system
resources by releasing the scarce resource held in a JavaScript object, if
required, during evaluation of a JavaScript expression.
 
We create a JavaScript file:
\snippet qml/integrating-javascript/scarceresources/exampleFour.js 0
 
Import it in QML:
\snippet qml/integrating-javascript/scarceresources/exampleFour.qml 0
 
Run it in C++:
\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 4
 
\section2 Example Five: Explicit Destruction and JavaScript References
 
One thing to be aware of when using "var" type properties is that they
hold references to JavaScript objects. As such, if multiple references
to one scarce resource is held, and the client calls destroy() on one
of those references (to explicitly release the scarce resource), all of
the references will be affected.
 
 
\snippet qml/integrating-javascript/scarceresources/exampleFive.qml 0
 
Run it in C++:
\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 5
 
*/