diff options
Diffstat (limited to 'doc/src/qtquick1/javascriptblocks.qdoc')
| -rw-r--r-- | doc/src/qtquick1/javascriptblocks.qdoc | 554 |
1 files changed, 0 insertions, 554 deletions
diff --git a/doc/src/qtquick1/javascriptblocks.qdoc b/doc/src/qtquick1/javascriptblocks.qdoc deleted file mode 100644 index 04aa78a5b6..0000000000 --- a/doc/src/qtquick1/javascriptblocks.qdoc +++ /dev/null @@ -1,554 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativejavascript.html -\inqmlmodule QtQuick 1 -\title Integrating JavaScript - -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 web browser. -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. - -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. -These inline functions are added as methods to the QML element that contains -them. - -\code -Item { - function factorial(a) { - a = parseInt(a); - if (a <= 0) - return 1; - else - return a * factorial(a - 1); - } - - MouseArea { - anchors.fill: parent - onClicked: console.log(factorial(10)) - } -} -\endcode - -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. These files -can be imported into QML files using an \c import statement, in the same way -that \l {Modules}{modules} are imported. - -For example, the \c {factorial()} method in the above example for \l {Inline JavaScript} -could be moved into an external file named \c factorial.js, and accessed like this: - -\code -import "factorial.js" as MathFunctions -Item { - MouseArea { - anchors.fill: parent - onClicked: console.log(MathFunctions.factorial(10)) - } -} -\endcode - -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 component's \l {QDeclarativeComponent::status()}{status} is set to -"Loading" until the script has been downloaded. - -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. (This also means qualifiers cannot -be named the same as built-in JavaScript objects such as \c Date and \c Math). - - -\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 -// factorial.js -.pragma library - -function factorial(a) { - a = parseInt(a); - if (a <= 0) - return 1; - else - return a * factorial(a - 1); -} -\endcode - -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. - - -\section2 Importing One JavaScript File From Another - -If a JavaScript file needs to use functions defined inside another JavaScript file, -the other file can be imported using the \l {QML:Qt::include()}{Qt.include()} -function. This imports all functions from the other file into the current file's -namespace. - -For example, the QML code below left calls \c showCalculations() in \c script.js, -which in turn can call \c factorial() in \c factorial.js, as it has included -\c factorial.js using \l {QML:Qt::include()}{Qt.include()}. - -\table -\row -\o {1,2} \snippet doc/src/snippets/declarative/integrating-javascript/includejs/app.qml 0 -\o \snippet doc/src/snippets/declarative/integrating-javascript/includejs/script.js 0 -\row -\o \snippet doc/src/snippets/declarative/integrating-javascript/includejs/factorial.js 0 -\endtable - -Notice that calling \l {QML:Qt::include()}{Qt.include()} imports all functions from -\c factorial.js into the \c MyScript namespace, which means the QML component can also -access \c factorial() directly as \c MyScript.factorial(). - -In QtQuick 2.0, support has been added to allow JavaScript files to import other -JavaScript files and also QML modules using a variation of the standard QML import -syntax (where all of the previously described rules and qualifications apply). - -A JavaScript file may import another in the following fashion: -\code -.import "filename.js" as UniqueQualifier -\endcode -For example: -\code -.import "factorial.js" as MathFunctions -\endcode - -A JavaScript file may import a QML module in the following fashion: -\code -.import Module.Name MajorVersion.MinorVersion as UniqueQualifier -\endcode -For example: -\code -.import Qt.test 1.0 as JsQtTest -\endcode -In particular, this may be useful in order to access functionality provided -via a module API; see qmlRegisterModuleApi() for more information. - -Due to the ability of a JavaScript file to import another script or QML module in -this fashion in QtQuick 2.0, some extra semantics are defined: -\list -\o a script with imports will not inherit imports from the QML file which imported it (so accessing Component.error will fail, for example) -\o a script without imports will inherit imports from the QML file which imported it (so accessing Component.error will succeed, for example) -\o a shared script (i.e., defined as .pragma library) does not inherit imports from any QML file even if it imports no other scripts -\endlist - -The first semantic is conceptually correct, given that a particular script -might be imported by any number of QML files. The second semantic is retained -for the purposes of backwards-compatibility. The third semantic remains -unchanged from the current semantics for shared scripts, but is clarified here -in respect to the newly possible case (where the script imports other scripts -or modules). - -\section1 Running JavaScript at Startup - -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 -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. - -The QML \l Component element provides an \e attached \c onCompleted property that -can be used to trigger the execution of script code at startup after the -QML environment has been completely established. For example: - -\code -Rectangle { - function startupFunction() { - // ... startup code - } - - Component.onCompleted: startupFunction(); -} -\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 \c onCompleted() -handler to execute at startup, they are run sequentially in an undefined order. - -Likewise, the \l {Component::onDestruction} attached property is triggered on -component destruction. - - -\section1 JavaScript and Property Binding - -Property bindings can be created in JavaScript by assigning the property with a \c function -that returns the required value. - -See \l {qml-javascript-assignment}{Property Assignment versus Property Binding} for details. - - -\section1 Receiving QML Signals in JavaScript - -To receive a QML signal, use the signal's \c connect() method to connect it to a JavaScript -function. - -For example, the following code connects the MouseArea \c clicked signal to the \c jsFunction() -in \c script.js: - -\table -\row -\o \snippet doc/src/snippets/declarative/integrating-javascript/connectjs.qml 0 -\o \snippet doc/src/snippets/declarative/integrating-javascript/script.js 0 -\endtable - -The \c jsFunction() will now be called whenever MouseArea's \c clicked signal is emitted. - -See \l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals} -{Connecting Signals to Methods and Signals} for more information. - - -\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 -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. - -\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 -properties it \l {QML Scope}{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}. - -\o 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 variant type -property may hold a "scarce resource" (image or pixmap). There are several -important semantics of scarce resources which should be noted: - -\list -\o By default, a scarce resource is automatically released by the declarative engine as soon as evaluation of the expression in which the scarce resource is allocated is complete if there are no other references to the resource -\o A client may explicitly preserve a scarce resource, which will ensure that the resource will not be released until all references to the resource are released and the JavaScript engine runs its garbage collector -\o A client may explicitly destroy a scarce resource, which will immediately release the resource -\endlist - -In most cases, allowing the engine to automatically release the resource is -the correct choice. In some cases, however, this may result in an invalid -variant being returned from a function in JavaScript, and in those cases it -may be necessary for clients to manually preserve or destroy resources for -themselves. - -For the following examples, imagine that we have defined the following class: -\code -class AvatarExample : public QObject -{ - Q_OBJECT - Q_PROPERTY(QPixmap avatar READ avatar WRITE setAvatar NOTIFY avatarChanged) -public: - AvatarExample(QObject *parent = 0) : QObject(parent), m_value(100, 100) { m_value.fill(Qt::blue); } - ~AvatarExample() {} - - QPixmap avatar() const { return m_value; } - void setAvatar(QPixmap v) { m_value = v; emit avatarChanged(); } - -signals: - void avatarChanged(); - -private: - QPixmap m_value; -}; -\endcode - -and that we have registered it with the QML type-system as follows: -\code -qmlRegisterType<AvatarExample>("Qt.example", 1, 0, "AvatarExample"); -\endcode - -The AvatarExample class has a property which is a pixmap. When the property -is accessed in JavaScript scope, a copy of the resource will be created and -stored in a JavaScript object which can then be used within JavaScript. This -copy will take up valuable system resources, and so by default the scarce -resource copy in the JavaScript object will be released automatically by the -declarative engine once evaluation of the JavaScript expression is complete, -unless the client explicitly preserves it. - -\section2 Example One: Automatic Release - -In this example, the resource will be automatically -released after the binding expression evaluation is -complete. - -\qml -// exampleOne.qml -import QtQuick 1.0 -import Qt.example 1.0 - -QtObject { - property AvatarExample a; - a: AvatarExample { id: example } - property variant avatar: example.avatar -} -\endqml - -\code -QDeclarativeComponent component(&engine, "exampleOne.qml"); -QObject *object = component.create(); -// The scarce resource will have been released automatically -// after the binding expression was evaluated. -// Since the scarce resource was not released explicitly prior -// to the binding expression being evaluated, we get the -// expected result: -//object->property("scarceResourceCopy").isValid() == true -delete object; -\endcode - -\section2 Example Two: Explicit Preservation - -In this example, the resource must be explicitly preserved in order -to prevent the declarative engine from automatically releasing the -resource after evaluation of the imported script. - -\code -// exampleTwo.js -.import Qt.example 1.0 as QtExample - -var component = Qt.createComponent("exampleOne.qml"); -var exampleOneElement = component.createObject(null); -var avatarExample = exampleOneElement.a; -var retn = avatarExample.avatar; - -// without the following call, the scarce resource held -// by retn would be automatically released by the engine -// after the import statement in exampleTwo.qml, prior -// to the variable assignment. -retn.preserve(); - -function importAvatar() { - return retn; -} -\endcode - -\qml -// exampleTwo.qml -import QtQuick 1.0 -import Qt.example 1.0 -import "exampleTwo.js" as ExampleTwoJs - -QtObject { - property variant avatar: ExampleTwoJs.importAvatar() -} -\endqml - -\code -QDeclarativeComponent component(&engine, "exampleTwo.qml"); -QObject *object = component.create(); -// The resource was preserved explicitly during evaluation of the -// JavaScript expression. Thus, during property assignment, the -// scarce resource was still valid, and so we get the expected result: -//object->property("avatar").isValid() == true -// The scarce resource may not have been cleaned up by the JS GC yet; -// it will continue to consume system resources until the JS GC runs. -delete object; -\endcode - -\section2 Example Three: Explicit Destruction - -In the following example, we release (via destroy()) an explicitly preserved -scarce resource variant. This example shows how a client may free system -resources by releasing the scarce resource held in a JavaScript object, if -required, during evaluation of a JavaScript expression. - -\code -// exampleThree.js -.import Qt.example 1.0 as QtExample - -var component = Qt.createComponent("exampleOne.qml"); -var exampleOneElement = component.createObject(null); -var avatarExample = exampleOneElement.a; -var retn = avatarExample.avatar; -retn.preserve(); - -function importAvatar() { - return retn; -} - -function releaseAvatar() { - retn.destroy(); -} -\endcode - -\qml -// exampleThree.qml -import QtQuick 1.0 -import Qt.example 1.0 -import "exampleThree.js" as ExampleThreeJs - -QtObject { - property variant avatarOne - property variant avatarTwo - - Component.onCompleted: { - avatarOne = ExampleThreeJs.importAvatar(); // valid at this stage - ExampleThreeJs.releaseAvatar(); // explicit release - avatarTwo = ExampleThreeJs.importAvatar(); // invalid at this stage - } -} -\endqml - -\code -QDeclarativeComponent component(&engine, "exampleThree.qml"); -QObject *object = component.create(); -// The scarce resource was explicitly preserved by the client during -// the evaluation of the imported script, and so the scarce resource -// remains valid until the explicit call to releaseAvatar(). As such, -// we get the expected results: -//object->property("avatarOne").isValid() == true -//object->property("avatarTwo").isValid() == false -// Because the scarce resource was released explicitly, it will no longer -// be consuming any system resources (beyond what a normal JS Object would; -// that small overhead will exist until the JS GC runs, as per any other -// JavaScript object). -delete object; -\endcode - -*/ |