can take one or two arguments:
\list
\li The first is the parent for the new object. The parent can be a graphical
- object (QtQuick item) or non-graphical object
- (\l{qtqml-typereference-topic.html}{QtQml} \l QtObject or C++
- QObject). Only graphical objects with graphical parent objects will be
- rendered to the QtQuick visual canvas. If you wish to set the parent later
- you can safely pass \c null to this function.
+ object (i.e. of the \l Item type) or non-graphical object (i.e. of the
+ \l QtObject or C++ QObject type). Only graphical objects with graphical
+ parent objects will be rendered to the QtQuick visual canvas. If you wish
+ to set the parent later you can safely pass \c null to this function.
\li The second is optional and is a map of property-value pairs that define
initial any property values for the object. Property values specified by
this argument are applied to the object before its creation is finalized,
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}.
+an exception, so all local variables should be explicitly declared. See
+\l{JavaScript Environment Restrictions} for a complete description of the
+restrictions on JavaScript code executed from QML.
There are various ways in which JavaScript expressions may be defined and used
in QML, including property bindings, signal handlers, custom methods and
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 {JavaScript Expression Restrictions in QML}
-covers the exact limitations of global script code.
+\l {Property Binding}{property bindings} may not have been run.
+\l {JavaScript Environment 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
-
-
-
-\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 {Scope and Naming Resolution}{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
\li trim()
\endlist
+ Additionally, the QML engine adds the following functions to the \l String prototype:
+ \list
+ \li \l {String::arg}{arg()}
+ \endlist
+
+
\section1 Boolean Objects
\section2 Boolean Prototype Object
\li toPrecision(precision)
\endlist
+ Additionally, the QML engine adds the following functions to the \l Number prototype:
+ \list
+ \li \l {Number::fromLocaleString}{fromLocaleString(locale, number)}
+ \li \l {Number::toLocaleCurrencyString}{toLocaleCurrencyString(locale, symbol)}
+ \li \l {Number::toLocaleString}{toLocaleString(locale, format, precision)}
+ \endlist
+
\section1 The Math Object
\section2 Value Properties
\li toJSON()
\endlist
+ Additionally, the QML engine adds the following functions to the \l Date prototype:
+ \list
+ \li \l {Date::timeZoneUpdated}{timeZoneUpdated()}
+ \li \l {Date::toLocaleDateString}{toLocaleDateString(locale, format)}
+ \li \l {Date::toLocaleString}{toLocaleString(locale, format)}
+ \li \l {Date::toLocaleTimeString}{toLocaleTimeString(locale, format)}
+ \endlist
+
\section1 RegExp Objects
\section2 RegExp Prototype Object
Reference} section generally covers the standard, while the \c{Browser Objects Reference} and \c{HTML DOM
Objects Reference} sections are browser specific (and thus not applicable to QML).
-\section1 Host Objects and Functions
+
+\section1 QML Global Object
The QML JavaScript host environment implements a number of host objects and functions, as
detailed in the \l{QML Global Object} documentation.
+These host objects and functions are always available, regardless of whether any modules
+have been imported.
+
-\section1 Native Object Modification
+\section1 JavaScript Objects and Functions
-QML makes the following modifications to native objects:
+A list of the JavaScript objects, functions and properties supported by the
+QML engine can be found in the \l{List of JavaScript Objects and Functions}.
+
+Note that QML makes the following modifications to native objects:
\list
\li An \l {String::arg}{arg()} function is added to the \l String prototype.
\li Locale-aware coversion functions are added to the \l Date and \l Number prototypes.
\endlist
-\section1 Restrictions
+
+\section1 JavaScript Environment Restrictions
QML implements the following restrictions for JavaScript code:
\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.
-\li The value of \c this is undefined in QML in the majority of contexts.
+
+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 {Scope and Naming Resolution}{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
-See \l {JavaScript Expression Restrictions in QML} for more details on these restrictions.
*/
\brief Description of the Qml Global Object
-The QML JavaScript host environment implements the following host objects and functions:
+The QML JavaScript host environment implements the following host objects and functions.
+These are built in and can be used from any JavaScript code loaded in QML, without
+additional imports:
\list
\li The \l{QmlGlobalQtObject}{Qt object}: This object is specific to QML, and provides helper methods
\li \l{qtqml-javascript-topic.html}{Integrating QML and JavaScript}
\list
\li \l{qtqml-javascript-expressions.html}{Using JavaScript Expressions with QML}
+ \li \l{qtqml-javascript-dynamicobjectcreation.html}{Dynamic QML Object Creation from JavaScript}
\li \l{qtqml-javascript-resources.html}{Defining JavaScript Resources In QML}
\li \l{qtqml-javascript-imports.html}{Importing JavaScript Resources In QML}
\li \l{qtqml-javascript-hostenvironment.html}{JavaScript Host Environment}
\list
- \li \l{qtqml-javascript-qmlglobalobject.html}{QML Global Object}
- \li \l{qtqml-javascript-functionlist.html}{List of JavaScript Objects and Functions}
+ \li \l{qtqml-javascript-hostenvironment.html#common-base}{Common Base}
+ \li \l{qtqml-javascript-hostenvironment.html#qml-global-object}{QML Global Object}
+ \li \l{qtqml-javascript-hostenvironment.html#javascript-objects-and-functions}{JavaScript Objects and Functions}
+ \li \l{qtqml-javascript-hostenvironment.html#javascript-environment-restrictions}{JavaScript Environment Restrictions}
\endlist
\endlist
\c this.width.
Note that the value of \c this is not defined outside of its use in property binding.
-See \l {JavaScript Expression Restrictions in QML} for details.
+See \l {JavaScript Environment Restrictions} for details.
*/
projects / profile / ivi / qtdeclarative.git / commitdiff