Integrating JavaScript

QML JavaScript Restrictions

QML executes standard JavaScript code, with the following restrictions:

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

• 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 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 currently undefined in QML in the majority of contexts

  The this keyword is supported when binding properties from JavaScript. In all other situations, 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)
       }
   }