Make title capitalization more consistent in QML documentation.

[profile/ivi/qtdeclarative.git] / src / qml / doc / src / javascript / expressions.qdoc

/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\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,
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, 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 should be explicitly declared.  A complete
description of the limitations of JavaScript code in QML is included in an
\l{JavaScript Expression Restrictions in QML}{upcoming section}.

There are various ways in which JavaScript expressions may be defined and used
in QML, including property bindings, signal handlers, custom methods and
JavaScript imports.




\section1 JavaScript Expressions in QML Objects

QML \l{QML Object Types}{object types} defined in \l{QML Documents}
{QML documents} can make use of JavaScript expressions which implement program
logic.  There are four ways that JavaScript can be used in a QML document:

\list
  \li \l{QML Object Attributes#property-initialization}{properties} can be
      assigned \l{Property Binding}{bindings} which are defined with
      JavaScript expressions, and which are automatically evaluated by the
      \l{QQmlEngine}{QML engine} when any properties accessed in the binding
      change, in order to ensure always-up-to-date property values.  Binding
      expressions can also perform function evaluation as an explicit side
      effect
  \li \l{QML Object Attributes#signal-handlers}{signal handlers} can be defined
      which are automatically evaluated when the object emits the associated
      signal
  \li \l{QML Object Attributes#custom-methods}{custom methods} can be defined
      in QML files as JavaScript functions
  \li JavaScript files providing functions and variables can be
      \l{Importing JavaScript Files in QML Documents}{imported} in a QML
      document
\endlist



\section2 Property Bindings

During startup, the QML engine will set up and initialize the property
bindings. The JavaScript conditional operator is a valid property binding.

\qml
import QtQuick 2.0

Rectangle {
    id: colorbutton
    width: 200; height: 80;

    color: mousearea.pressed ? "steelblue" : "lightsteelblue"

    MouseArea {
        id: mousearea
        anchors.fill: parent
    }
}
\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.

There are two ways to define a property binding: the first (and most common)
is, as previously shown, in a \l{QML Object Attributes#property-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.0

Rectangle {
    id: colorbutton
    width: 200; height: 80;

    color: "red"

    MouseArea {
        id: mousearea
        anchors.fill: parent
    }

    Component.onCompleted: {
        color = Qt.binding(function() { return mousearea.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.



\section2 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 element has a MouseArea and a
Text label. The MouseArea will emit its "pressed" signal when the user presses
the defined interactive area, which will automatically trigger the
\l{MouseArea::}{onPressed} handler, which can be defined by clients. The QML
engine will execute the JavaScript expressions defined in the onPressed and
onReleased handlers, as required. Typically, a signal handler is bound to
JavaScript expressions to initiate other events or to simply assign property
values.

\qml
import QtQuick 2.0

Rectangle {
    id: button
    width: 200; height: 80; color: "lightsteelblue"

    MouseArea {
        id: mousearea
        anchors.fill: parent

        onPressed: {
            // arbitrary JavaScript expression
            label.text = "I am Pressed!"
        }
        onReleased: {
            // arbitrary JavaScript expression
            label.text = "Click Me!"
        }

    }

    Text {
        id: label
        anchors.centerIn: parent
        text: "Press Me!"
    }
}
\endqml

Please see the \l{Signal and Handler Event System} documentation for in-depth
discussion of signals and signal handlers, and see the
\l{QML Object Attributes} documentation for in-depth discussion of how
to define the implementation of signal handlers in QML with JavaScript.



\section2 JavaScript Expressions in 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.



\section3 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.  Methods
defined in this way are often referred to as "inline JavaScript functions" as
their implementation is included in the QML object type definition
(QML document), as opposed to an external JavaScript file.

An example of an inline custom method is as follows:

\qml
import QtQuick 2.0

Item {
    function factorial(a) {
        a = parseInt(a);
        if (a <= 0)
            return 1;
        else
            return a * factorial(a - 1);
    }

    MouseArea {
        anchors.fill: parent
        onClicked: console.log(factorial(10))
    }
}
\endqml

The factorial function will run whenever the MouseArea detects a clicked signal.

Importantly, 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 in-depth discussion of how
to define custom methods in QML with JavaScript code implementations.



\section3 Functions in Imported JavaScript Files

Non-trivial program logic is best separated into external JavaScript files.
These files can be imported into QML files using an \c import statement, in
the same way that \l {QML Modules}{modules} are imported.

For example, the \c {factorial()} method in the above example for
\l{JavaScript Expressions in Custom Methods} could be moved into an external
file named \c factorial.js, and accessed like this:

\qml
import "factorial.js" as MathFunctions

Item {
    MouseArea {
        anchors.fill: parent
        onClicked: console.log(MathFunctions.factorial(10))
    }
}
\endqml

For more information about loading external JavaScript files into QML, read
the section about \l{Importing JavaScript into QML}.



\section3 Connecting Signals to JavaScript Functions

QML object types which emit signals also provide default signal handlers for
their signals, as described in a previous section.  Sometimes, however, a
client will want to cause a signal emitted from one object to trigger a
function defined in another object; and in that case, a signal connection
is often preferable.

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 MouseArea
\c clicked 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() will now be called whenever MouseArea's \c clicked signal
is emitted.

See \l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals}
{Connecting Signals to Methods and Signals} for more information.





\section1 Running JavaScript at Startup

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}s may not have been run.  \l {QML JavaScript Restrictions}
covers the exact limitations of global script code.

Every QML object has an \e attached \l Component property that references the
component within which the object was instantiated.  Every \l Component
will emit a \c completed signal, and thus every object can define an
implementation for the \c onCompleted() handler which can be used to trigger the
execution of script code at startup after the QML environment has been
completely 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, the \l {Component::onDestruction} handler definitions are triggered
on component destruction.






\section1 JavaScript Expression Restrictions in QML

QML executes standard JavaScript code, with the following restrictions:

\list
\li JavaScript code cannot modify the global object.

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 an 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 {QML Scope}{normally would}.

Global code that only accesses script local variable 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, refer to
\l {Running JavaScript at Startup}.

\li The value of \c this is currently undefined in QML in the majority of contexts

The \c this keyword is supported when binding properties from JavaScript.
In all other situations, the value of
\c this is undefined in QML.

To refer to any element, 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 not work because this is undefined
    MouseArea {
        height: 50; width: 200
        onClicked: mouseAreaClicked(this)
    }
    // This will pass area2 to the function
    MouseArea {
        id: area2
        y: 50; height: 50; width: 200
        onClicked: mouseAreaClicked(area2)
    }
}
\endqml

\endlist

\section1 Scarce Resources in JavaScript

As described in the documentation for \l{QML Basic Types}, a \c var type
property may hold a "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/avatarExample.cpp 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.

\snippet qml/integrating-javascript/scarceresources/exampleOne.qml 0

\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

\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.

\snippet qml/integrating-javascript/scarceresources/exampleThree.js 0

\snippet qml/integrating-javascript/scarceresources/exampleThree.qml 0

\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.

\snippet qml/integrating-javascript/scarceresources/exampleFour.js 0

\snippet qml/integrating-javascript/scarceresources/exampleFour.qml 0

\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

\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 5

*/