Update imports and module documentation

Recently, the qmldir syntax was modified to allow a module identifier
directive to be specified.  This allows us to guarantee that types
provided in that namespace are not overridden by other modules.

Given this fundamental change, the documentation needed to be updated
to reflect the new terminology surrounding imports:
   - modules
       - identified vs legacy
   - directories
       - local and remote directory imports
   - JavaScript resources
       - scripts which can be imported directly

Change-Id: I5a3d38de93d0186e79b87f2b3050f2b802088348
Reviewed-by: Bea Lam <bea.lam@nokia.com>

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