diff options
Diffstat (limited to 'doc/src/declarative/javascriptblocks.qdoc')
| -rw-r--r-- | doc/src/declarative/javascriptblocks.qdoc | 175 |
1 files changed, 100 insertions, 75 deletions
diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc index 98183bb..0006967 100644 --- a/doc/src/declarative/javascriptblocks.qdoc +++ b/doc/src/declarative/javascriptblocks.qdoc @@ -41,95 +41,123 @@ /*! \page qdeclarativejavascript.html -\title JavaScript Blocks +\title Integrating JavaScript QML encourages building UIs declaratively, using \l {Property Binding} and the -composition of existing \l {QML Elements}. If imperative code is required to implement -more advanced behavior, the \l Script element can be used to add JavaScript code directly -to a QML file, or to include an external JavaScript file. +composition of existing \l {QML Elements}. To allow the implementation of more +advanced behavior, QML integrates tightly with imperative JavaScript code. -The \l Script element is a QML language \e intrinsic. It can be used anywhere in a -QML file, \e except as the root element of a file or sub-component, but cannot be -assigned to an object property or given an id. The included JavaScript is evaluated -in a scope chain. The \l {QML Scope} documentation covers the specifics of scoping -in QML. +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 +declared. -A restriction on the JavaScript used in QML is that you cannot add new members to the -global object. This happens transparently when you try to use a variable without -declaring it, and so declaring local variables is required when using Java script in -QML. +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. -The global object in QML has a variety of helper functions added to it, to aid UI -implementation. See \l{QML Global Object} for further details. +\section1 Inline JavaScript -Note that if you are adding a function that should be called by external elements, -you do not need the \l Script element. See \l {Extending types from QML#Adding new methods} -{Adding new methods} for information about adding slots that can be called externally. - -\section1 Inline Script - -Small blocks of JavaScript can be included directly inside a \l {QML Document} as -the body of the \l Script element. +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. \code -Rectangle { - Script { - function factorial(a) { - a = Integer(a); - if (a <= 0) - return 1; - else - return a * factorial(a - 1); - } +Item { + function factorial(a) { + a = Integer(a); + if (a <= 0) + return 1; + else + return a * factorial(a - 1); + } + + MouseRegion { + anchors.fill: parent + onClicked: print(factorial(10)) } } \endcode -Good programming practice dictates that only small script snippets should be written -inline. QML prohibits the declaration of anything other than functions in an inline -script block. For example, the following script is illegal as an inline script block -as it declares the non-function variable \c lastResult. +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. + +\section1 Separate JavaScript files + +Large blocks of JavaScript should be written in separate files. Like element +types, external JavaScript files are \c {import}'ed into QML files. + +The \c {factorial()} method used in the \l {Inline JavaScript} section could +be refactored into an external file, and accessed like this. \code -// Illegal inline code block -var lastResult = 0 -function factorial(a) { - a = Integer(a); - if (a <= 0) - lastResult = 1; - else - lastResult = a * factorial(a - 1); - return lastResult; +import "factorial.js" as MathFunctions +Item { + MouseRegion { + anchors.fill: parent + onClicked: print(MathFunctions.factorial(10)) + } } \endcode -\section1 Including an External File +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 will remain in the +\l {QDeclarativeComponent::status()}{waiting state} until the script has been +downloaded. -To avoid cluttering the QML file, large script blocks should be in a separate file. -The \l Script element's \c source property is used to load script from an external -file. +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. -If the previous factorial code that was illegal as an inline script block was saved -into a "factorial.js" file, it could be included like this. +\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 +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. + +\section2 Stateless JavaScript libraries + +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. \code -Rectangle { - Script { - source: "factorial.js" - } +.pragma library + +function factorial(a) { + a = Integer(a); + if (a <= 0) + return 1; + else + return a * factorial(a - 1); } \endcode -The \c source property may reference a relative file, or an absolute path. In the -case of a relative file, the location is resolved relative to the location of the -\l {QML Document} that contains the \l Script element. If the script file is not -accessible, an error will occur. If the source is on a network resource, the -enclosing QML document will remain in the \l {QDeclarativeComponent::status()}{waiting state} -until the script has been retrieved. +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. -\section1 Running Script at Startup +\section1 Running JavaScript at Startup -It is occasionally necessary to run a block of JavaScript code at application (or +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 @@ -144,10 +172,8 @@ The following QML code shows how to use the \c Component::onCompleted property. \code Rectangle { - Script { - function startupFunction() { - // ... startup code - } + function startupFunction() { + // ... startup code } Component.onCompleted: startupFunction(); @@ -155,21 +181,20 @@ Rectangle { \endcode 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 script to -execute at startup, they are run sequentially in an undefined order. +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. -\section1 QML Script Restrictions +\section1 QML JavaScript Restrictions -QML \l Script blocks contain standard JavaScript code. QML introduces the following -restrictions. +QML executes standard JavaScript code, with the following restrictions: \list -\o Script code cannot modify the global object. +\o 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 explicitly 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. @@ -197,7 +222,7 @@ that includes the file and line number of the offending code. \o Global code is run in a reduced scope -During startup, if a \l Script block includes an external file with "global" +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 {QML Scope}{normally would}. |