diff options
Diffstat (limited to 'src/qml/doc/src/javascript/resources.qdoc')
-rw-r--r-- | src/qml/doc/src/javascript/resources.qdoc | 158 |
1 files changed, 158 insertions, 0 deletions
diff --git a/src/qml/doc/src/javascript/resources.qdoc b/src/qml/doc/src/javascript/resources.qdoc new file mode 100644 index 0000000000..b2299d7a0d --- /dev/null +++ b/src/qml/doc/src/javascript/resources.qdoc @@ -0,0 +1,158 @@ +/**************************************************************************** +** +** 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 qtqml-javascript-resources.html +\title Defining JavaScript Resources In QML +\brief Description of how JavaScript files may be defined for use in QML + +The program logic for a QML application may be defined in JavaScript. The +JavaScript code may either be defined in-line in QML documents, or separated +into JavaScript files (known as \c {JavaScript Resources} in QML). + +There are two different kinds of JavaScript resources which are supported in +QML: code-behind implementation files, and shared (library) files. Both kinds +of JavaScript resource may be \l{qtqml-javascript-imports.html}{imported} by +other JavaScript resources, or included in \l{qtqml-modules-topic.html} +{QML modules}. + +\section1 Code-Behind Implementation Resource + +Most JavaScript files imported into a QML document are stateful implementations +for the QML document importing them. In these cases, each instance of the QML +object type defined in the document requires a separate copy of the JavaScript +objects and state in order to behave correctly. + +The default behavior when importing JavaScript files is to provide a unique, +isolated copy for each QML component instance. If that JavaScript file does +not import any resources or modules with a \c{.import} statement, its code will +run in the same scope as the QML component instance and consequently can access +and manipulate the objects and properties declared in that QML component. +Otherwise, it will have its own unique scope, and objects and properties of the +QML component should be passed to the functions of the JavaScript file as +parameters if they are required. + +An example of a code-behind implementation resource follows: + +\qml +// MyButton.qml +import QtQuick 2.0 +import "my_button_impl.js" as Logic // a new instance of this JavaScript resource is loaded for each instance of Button.qml + +Rectangle { + id: rect + width: 200 + height: 100 + color: "red" + + MouseArea { + id: mousearea + anchors.fill: parent + onClicked: Logic.onClicked(rect) + } +} +\endqml + +\qml +// my_button_impl.js +var clickCount = 0; // this state is separate for each instance of MyButton +function onClicked(btn) { + clickCount += 1; + if ((clickCount % 5) == 0) { + obj.color = Qt.rgba(1,0,0,1); + } else { + obj.color = Qt.rgba(0,1,0,1); + } +} +\endqml + +In general, simple logic should be defined in-line in the QML file, but more +complex logic should be separated into code-behind implementation resources +for maintainability and readability. + +\section1 Shared JavaScript Resources (Libraries) + +Some JavaScript files act more like libraries - they provide a set of 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 +shared library through the use of a pragma, as shown in the following example. + +\code +// factorial.js +.pragma library + +var factorialCount = 0; + +function factorial(a) { + a = parseInt(a); + + // factorial recursion + if (a > 0) + return a * factorial(a - 1); + + // shared state + factorialCount += 1; + + // recursion base-case. + return 1; +} + +function factorialCallCount() { + return factorialCount; +} +\endcode + +The pragma declaration must appear before any JavaScript code excluding comments. + +Note that multiple QML documents can import \c{"factorial.js"} and call the +factorial and factorialCallCount functions that it provides. The state of the +JavaScript import is shared across the QML documents which import it, and thus +the return value of the factorialCallCount function may be non-zero when called +within a QML document which never calls the factorial function. + +For example: + +\qml +// Calculator.qml +import QtQuick 2.0 +import "factorial.js" as FactorialCalculator // this JavaScript resource is only ever loaded once by the engine, even if multiple instances of Calculator.qml are created + +Text { + width: 500 + height: 100 + property int input: 17 + text: "The factorial of " + input + " is: " + FactorialCalculator.factorial(input) +} +\endqml + +As they are shared, .pragma library files cannot access QML component instance +objects or properties directly, although QML values can be passed as function +parameters. + +*/ |