diff options
author | Bea Lam <bea.lam@nokia.com> | 2010-04-12 14:45:51 +1000 |
---|---|---|
committer | Bea Lam <bea.lam@nokia.com> | 2010-04-12 14:45:51 +1000 |
commit | 1e3b3551b8498e1f4dc92982e2a040ba90a6bf26 (patch) | |
tree | dee1f64c3a9e26e07bc9cea00b90e800b932a6f2 /doc/src/declarative/javascriptblocks.qdoc | |
parent | 20a00436174faf746be14f5c36908710eeb44101 (diff) | |
parent | 381ea9c22eb8f6b3701376a650202f094e17746d (diff) | |
download | qt4-tools-1e3b3551b8498e1f4dc92982e2a040ba90a6bf26.tar.gz |
Merge branch '4.7' of scm.dev.nokia.troll.no:qt/qt-qml into 4.7
Conflicts:
doc/src/declarative/javascriptblocks.qdoc
Diffstat (limited to 'doc/src/declarative/javascriptblocks.qdoc')
-rw-r--r-- | doc/src/declarative/javascriptblocks.qdoc | 58 |
1 files changed, 29 insertions, 29 deletions
diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc index 5fc39380ec..8ffe58c3d8 100644 --- a/doc/src/declarative/javascriptblocks.qdoc +++ b/doc/src/declarative/javascriptblocks.qdoc @@ -41,25 +41,25 @@ /*! \page qdeclarativejavascript.html -\title Integrating JavaScript +\title Integrating JavaScript -QML encourages building UIs declaratively, using \l {Property Binding} and the +QML encourages building UIs declaratively, using \l {Property Binding} and the composition of existing \l {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 webbrowser. 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 +QML this will throw an exception, so all local variables should be explicitly declared. -In addition to the standard JavaScript properties, the \l {QML Global Object} +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. \section1 Inline JavaScript -Small JavaScript functions can be written inline with other QML declarations. +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. @@ -73,14 +73,14 @@ Item { return a * factorial(a - 1); } - MouseRegion { + MouseArea { anchors.fill: parent onClicked: print(factorial(10)) } } \endcode -As methods, inline functions on the root element in a QML component can be +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. @@ -97,7 +97,7 @@ could be moved into an external file named \c factorial.js, and accessed like th \code import "factorial.js" as MathFunctions Item { - MouseRegion { + MouseArea { anchors.fill: parent onClicked: print(MathFunctions.factorial(10)) } @@ -108,24 +108,24 @@ 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 \l {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 stays in the -\l {QDeclarativeComponent::status()}{"Loading" status} until the script has been +resource, the QML document has a "Loading" +\l {QDeclarativeComponent::status()}{status} until the script has been downloaded. -Imported JavaScript files are always qualified using the "as" keyword. The +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. \section2 Code-Behind Implementation 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 +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 +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. \section2 Stateless JavaScript libraries @@ -134,8 +134,8 @@ 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 +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. \code @@ -162,7 +162,7 @@ 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 \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 +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. @@ -184,21 +184,21 @@ 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 \c onCompleted() handler to execute at startup, they are run sequentially in an undefined order. -\section1 QML JavaScript Restrictions +\section1 QML JavaScript Restrictions QML executes standard JavaScript code, with the following restrictions: \list \o JavaScript code cannot modify the global object. -In QML, the global object is constant - existing properties cannot be modified or +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, +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 +Assuming that the \c a variable does not exist in the scope chain, the following code is illegal in QML. \code @@ -216,18 +216,18 @@ 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, +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. \o 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 +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 +Global code that only accesses script local variable is permitted. This is an example of valid global code. \code @@ -241,8 +241,8 @@ Global code that accesses QML objects will not run correctly. 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 +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}. \endlist |