src/qml/doc/src/javascript/resources.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27 /*!
  28 \page qtqml-javascript-resources.html
  29 \title Defining JavaScript Resources In QML
  30 \brief Description of how JavaScript files may be defined for use in QML
  31
  32 The program logic for a QML application may be defined in JavaScript.  The
  33 JavaScript code may either be defined in-line in QML documents, or separated
  34 into JavaScript files (known as \c {JavaScript Resources} in QML).
  35
  36 There are two different kinds of JavaScript resources which are supported in
  37 QML: code-behind implementation files, and shared (library) files.  Both kinds
  38 of JavaScript resource may be \l{qtqml-javascript-imports.html}{imported} by
  39 other JavaScript resources, or included in \l{qtqml-modules-topic.html}
  40 {QML modules}.
  41
  42 \section1 Code-Behind Implementation Resource
  43
  44 Most JavaScript files imported into a QML document are stateful implementations
  45 for the QML document importing them.  In these cases, each instance of the QML
  46 object type defined in the document requires a separate copy of the JavaScript
  47 objects and state in order to behave correctly.
  48
  49 The default behavior when importing JavaScript files is to provide a unique,
  50 isolated copy for each QML component instance.  If that JavaScript file does
  51 not import any resources or modules with a \c{.import} statement, its code will
  52 run in the same scope as the QML component instance and consequently can access
  53 and manipulate the objects and properties declared in that QML component.
  54 Otherwise, it will have its own unique scope, and objects and properties of the
  55 QML component should be passed to the functions of the JavaScript file as
  56 parameters if they are required.
  57
  58 An example of a code-behind implementation resource follows:
  59
  60 \qml
  61 // MyButton.qml
  62 import QtQuick 2.0
  63 import "my_button_impl.js" as Logic // a new instance of this JavaScript resource is loaded for each instance of Button.qml
  64
  65 Rectangle {
  66     id: rect
  67     width: 200
  68     height: 100
  69     color: "red"
  70
  71     MouseArea {
  72         id: mousearea
  73         anchors.fill: parent
  74         onClicked: Logic.onClicked(rect)
  75     }
  76 }
  77 \endqml
  78
  79 \qml
  80 // my_button_impl.js
  81 var clickCount = 0;   // this state is separate for each instance of MyButton
  82 function onClicked(btn) {
  83     clickCount += 1;
  84     if ((clickCount % 5) == 0) {
  85         obj.color = Qt.rgba(1,0,0,1);
  86     } else {
  87         obj.color = Qt.rgba(0,1,0,1);
  88     }
  89 }
  90 \endqml
  91
  92 In general, simple logic should be defined in-line in the QML file, but more
  93 complex logic should be separated into code-behind implementation resources
  94 for maintainability and readability.
  95
  96 \section1 Shared JavaScript Resources (Libraries)
  97
  98 Some JavaScript files act more like libraries - they provide a set of helper
  99 functions that take input and compute output, but never manipulate QML
 100 component instances directly.
 101
 102 As it would be wasteful for each QML component instance to have a unique copy of
 103 these libraries, the JavaScript programmer can indicate a particular file is a
 104 shared library through the use of a pragma, as shown in the following example.
 105
 106 \code
 107 // factorial.js
 108 .pragma library
 109
 110 var factorialCount = 0;
 111
 112 function factorial(a) {
 113     a = parseInt(a);
 114
 115     // factorial recursion
 116     if (a > 0)
 117         return a * factorial(a - 1);
 118
 119     // shared state
 120     factorialCount += 1;
 121
 122     // recursion base-case.
 123     return 1;
 124 }
 125
 126 function factorialCallCount() {
 127     return factorialCount;
 128 }
 129 \endcode
 130
 131 The pragma declaration must appear before any JavaScript code excluding comments.
 132
 133 Note that multiple QML documents can import \c{"factorial.js"} and call the
 134 factorial and factorialCallCount functions that it provides.  The state of the
 135 JavaScript import is shared across the QML documents which import it, and thus
 136 the return value of the factorialCallCount function may be non-zero when called
 137 within a QML document which never calls the factorial function.
 138
 139 For example:
 140
 141 \qml
 142 // Calculator.qml
 143 import QtQuick 2.0
 144 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
 145
 146 Text {
 147     width: 500
 148     height: 100
 149     property int input: 17
 150     text: "The factorial of " + input + " is: " + FactorialCalculator.factorial(input)
 151 }
 152 \endqml
 153
 154 As they are shared, .pragma library files cannot access QML component instance
 155 objects or properties directly, although QML values can be passed as function
 156 parameters.
 157
 158 */