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.
+
+*/