QML encourages building UIs declaratively, using Property Binding and the composition of existing QML Elements. To allow the implementation of more advanced behavior, QML integrates tightly with imperative JavaScript code.
The JavaScript environment provided by QML is stricter than that in a web browser. In QML you cannot add, or modify, members of the JavaScript global object. 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.
In addition to the standard JavaScript properties, the QML Global Object includes a number of helper methods that simplify building UIs and interacting with the QML environment.
Small JavaScript functions can be written inline with other QML declarations. These inline functions are added as methods to the QML element that contains them.
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))
}
}
As methods, inline functions on the root element 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 element or, preferably, written in an external JavaScript file.
Large blocks of JavaScript should be written in separate files. These files can be imported into QML files using an import statement, in the same way that modules are imported.
For example, the factorial() method in the above example for Inline JavaScript could be moved into an external file named factorial.js, and accessed like this:
import "factorial.js" as MathFunctions
Item {
MouseArea {
anchors.fill: parent
onClicked: console.log(MathFunctions.factorial(10))
}
}
Both relative and absolute JavaScript URLs can be imported. In the case of a relative URL, the location is resolved relative to the location of the QML Document that contains the import. If the script file is not accessible, an error will occur. If the JavaScript needs to be fetched from a network resource, the QML document has a "Loading" status until the script has been downloaded.
Imported JavaScript files are always qualified using the "as" keyword. The qualifier for JavaScript files must be unique, so there is always a one-to-one mapping between qualifiers and JavaScript files.
Most JavaScript files imported into a QML file are stateful, logic implementations for the QML file importing them. In these cases, for QML component instances to behave correctly each instance requires a separate copy of the JavaScript objects and state.
The default behavior when importing JavaScript files is to provide a unique, isolated copy for each QML component instance. The code runs in the same scope as the QML component instance and consequently can can access and manipulate the objects and properties declared.
Some JavaScript files act more like libraries - they provide a set of stateless helper functions that take input and compute output, but never manipulate QML component instances directly.
As it would be wasteful for each QML component instance to have a unique copy of these libraries, the JavaScript programmer can indicate a particular file is a stateless library through the use of a pragma, as shown in the following example.
// factorial.js
.pragma library
function factorial(a) {
a = parseInt(a);
if (a <= 0)
return 1;
else
return a * factorial(a - 1);
}
The pragma declaration must appear before any JavaScript code excluding comments.
As they are shared, stateless library files cannot access QML component instance objects or properties directly, although QML values can be passed as function parameters.
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 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 Property Bindings may not have been run. QML JavaScript Restrictions covers the exact limitations of global script code.
The QML Component element provides an attached onCompleted property that can be used to trigger the execution of script code at startup after the QML environment has been completely established. For example:
Rectangle {
function startupFunction() {
// ... startup code
}
Component.onCompleted: startupFunction();
}
Any element in a QML file - including nested elements and nested QML component instances - can use this attached property. If there is more than one onCompleted() handler to execute at startup, they are run sequentially in an undefined order.
Likewise, the Component::onDestruction attached property is triggered on component destruction.
When working with both QML and JavaScript, it is important to differentiate between QML Property Binding and JavaScript value assignment. In QML, a property binding is created using the property: value syntax:
Rectangle {
width: otherItem.width
}
The width of the above Rectangle is updated whenever otherItem.width changes. On the other hand, take the following JavaScript code snippet, that runs when the Rectangle is created:
Rectangle {
Component.onCompleted: {
width = otherItem.width;
}
}
The width of this Rectangle is assigned the value of otherItem.width using the property = value syntax in JavaScript. Unlike the QML property: value syntax, this does not invoke QML property binding; the rectangle.width property is set to the value of otherItem.width at the time of the assignment and will not be updated if that value changes.
See Property Binding for more information.
QML executes standard JavaScript code, with the following restrictions:
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 a variable does not exist in the scope chain, the following code is illegal in QML.
// Illegal modification of undeclared variable
a = 1;
for (var ii = 1; ii < 10; ++ii)
a = a * ii;
console.log("Result: " + a);
It can be trivially modified to this legal code.
var a = 1;
for (var ii = 1; ii < 10; ++ii)
a = a * ii;
console.log("Result: " + a);
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.
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 normally would.
Global code that only accesses script local variable is permitted. This is an example of valid global code.
var colors = [ "red", "blue", "green", "orange", "purple" ];
Global code that accesses QML objects will not run correctly.
// Invalid global code - the "rootObject" variable is undefined
var initialPosition = { rootObject.x, rootObject.y }
This restriction exists as the QML environment is not yet fully established. To run code after the environment setup has completed, refer to Running JavaScript at Startup.
The value of this is undefined in QML. To refer to any element, provide an id. For example:
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)
}
}