src/qml/doc/src/javascript/hostenvironment.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27 /*!
  28 \page qtqml-javascript-hostenvironment.html
  29 \title JavaScript Host Environment
  30 \brief Description of the JavaScript host environment provided by the QML engine
  31
  32
  33 QML provides a JavaScript host environment tailored to writing QML applications.
  34 This environment is different from the host environment provided by a browser
  35 or a server-side JavaScript environment such as Node.js. For example, QML does
  36 not provide a \c window object or \c{DOM API} as commonly found in a browser environment.
  37
  38 \section1 Common Base
  39
  40 Like a browser or server-side JavaScript environment, the QML runtime implements the
  41 \l{ECMA-262}{ECMAScript Language Specification} standard. This provides access to
  42 all of the built-in types and functions defined by the standard, such as Object, Array, and Math.
  43 The QML runtime implements the 5th edition of the standard, which is the same edition commonly
  44 implemented by browsers.
  45
  46 The standard ECMAScript built-ins are not explicitly documented in the QML documentation. For more
  47 information on their use, please refer to the ECMA-262 5th edition standard or one of the many online
  48 JavaScript reference and tutorial sites, such as the \l{W3Schools JavaScript Reference} (JavaScript Objects
  49 Reference section). Many sites focus on JavaScript in the browser, so in some cases you may need to double
  50 check the specification to determine whether a given function or object is part of standard ECMAScript or
  51 specific to the browser environment. In the case of the W3Schools link above, the \c{JavaScript Objects
  52 Reference} section generally covers the standard, while the \c{Browser Objects Reference} and \c{HTML DOM
  53 Objects Reference} sections are browser specific (and thus not applicable to QML).
  54
  55
  56 \section1 QML Global Object
  57
  58 The QML JavaScript host environment implements a number of host objects and functions, as
  59 detailed in the \l{QML Global Object} documentation.
  60
  61 These host objects and functions are always available, regardless of whether any modules
  62 have been imported.
  63
  64
  65 \section1 JavaScript Objects and Functions
  66
  67 A list of the JavaScript objects, functions and properties supported by the
  68 QML engine can be found in the \l{List of JavaScript Objects and Functions}.
  69
  70 Note that QML makes the following modifications to native objects:
  71
  72 \list
  73 \li An \l {String::arg}{arg()} function is added to the \l String prototype.
  74 \li Locale-aware coversion functions are added to the \l Date and \l Number prototypes.
  75 \endlist
  76
  77
  78 \section1 JavaScript Environment Restrictions
  79
  80 QML implements the following restrictions for JavaScript code:
  81
  82 \list
  83 \li JavaScript code cannot modify the global object.
  84
  85 In QML, the global object is constant - existing properties cannot be modified
  86 or deleted, and no new properties may be created.
  87
  88 Most JavaScript programs do not intentionally modify the global object.
  89 However, JavaScript's automatic creation of undeclared variables is an implicit
  90 modification of the global object, and is prohibited in QML.
  91
  92 Assuming that the \c a variable does not exist in the scope chain, the
  93 following code is illegal in QML:
  94
  95 \code
  96 // Illegal modification of undeclared variable
  97 a = 1;
  98 for (var ii = 1; ii < 10; ++ii)
  99     a = a * ii;
 100 console.log("Result: " + a);
 101 \endcode
 102
 103 It can be trivially modified to this legal code.
 104
 105 \code
 106 var a = 1;
 107 for (var ii = 1; ii < 10; ++ii)
 108     a = a * ii;
 109 console.log("Result: " + a);
 110 \endcode
 111
 112 Any attempt to modify the global object - either implicitly or explicitly - will
 113 cause an exception.  If uncaught, this will result in an warning being printed,
 114 that includes the file and line number of the offending code.
 115
 116 \li Global code is run in a reduced scope.
 117
 118 During startup, if a QML file includes an external JavaScript file with "global"
 119 code, it is executed in a scope that contains only the external file itself and
 120 the global object.  That is, it will not have access to the QML objects and
 121 properties it \l {Scope and Naming Resolution}{normally would}.
 122
 123 Global code that only accesses script local variable is permitted.  This is an
 124 example of valid global code.
 125
 126 \code
 127 var colors = [ "red", "blue", "green", "orange", "purple" ];
 128 \endcode
 129
 130 Global code that accesses QML objects will not run correctly.
 131
 132 \code
 133 // Invalid global code - the "rootObject" variable is undefined
 134 var initialPosition = { rootObject.x, rootObject.y }
 135 \endcode
 136
 137 This restriction exists as the QML environment is not yet fully established.
 138 To run code after the environment setup has completed, refer to
 139 \l {Running JavaScript at Startup}.
 140
 141 \li The value of \c this is currently undefined in QML in the majority of contexts.
 142
 143 The \c this keyword is supported when binding properties from JavaScript.
 144 In all other situations, the value of
 145 \c this is undefined in QML.
 146
 147 To refer to any element, provide an \c id.  For example:
 148
 149 \qml
 150 Item {
 151     width: 200; height: 100
 152     function mouseAreaClicked(area) {
 153         console.log("Clicked in area at: " + area.x + ", " + area.y);
 154     }
 155     // This will not work because this is undefined
 156     MouseArea {
 157         height: 50; width: 200
 158         onClicked: mouseAreaClicked(this)
 159     }
 160     // This will pass area2 to the function
 161     MouseArea {
 162         id: area2
 163         y: 50; height: 50; width: 200
 164         onClicked: mouseAreaClicked(area2)
 165     }
 166 }
 167 \endqml
 168
 169 \endlist
 170
 171
 172
 173 */