1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** 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. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtqml-javascript-imports.html
\title Importing JavaScript Resources in QML
\brief Description of how to import and use JavaScript resources in QML documents
\l{qtqml-javascript-resources.html}{JavaScript resources} may be imported by
QML documents and other JavaScript resources. JavaScript resources may be
imported via either relative or absolute URLs. In the case of a relative URL,
the location is resolved relative to the location of the \l {QML Document} or
\l{qtqml-javascript-resources.html}{JavaScript Resource} 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 {QQmlComponent::status()}{status} is set to "Loading" until the script has
been downloaded.
JavaScript resources may also import QML modules and other JavaScript
resources. The syntax of an import statement within a JavaScript resource
differs slightly from an import statement within a QML document, which is
documented thoroughly below.
\section1 Importing a JavaScript Resource from a QML Document
A QML document may import a JavaScript resource with the following syntax:
\code
import "ResourceURL" as Qualifier
\endcode
For example:
\code
import "jsfile.js" as Logic
\endcode
Imported JavaScript resources are always qualified using the "as" keyword. The
qualifier for JavaScript resources 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).
The functions defined in an imported JavaScript file are available to objects
defined in the importing QML document, via the
\c{"Qualifier.functionName(params)"} syntax. Functions in JavaScript resources
may take parameters whose type can be any of the supported QML basic types or
object types, as well as normal JavaScript types. The normal
\l{qtqml-cppintegration-data.html}{data type conversion rules} will apply to
parameters and return values when calling such functions from QML.
\section1 Imports Within JavaScript Resources
In QtQuick 2.0, support has been added to allow JavaScript resources to import
other JavaScript resources and also QML type namespaces using a variation of
the standard QML import syntax (where all of the previously described rules and
qualifications apply).
Due to the ability of a JavaScript resource to import another script or QML
module in this fashion in QtQuick 2.0, some extra semantics are defined:
\list
\li a script with imports will not inherit imports from the QML document which imported it (so accessing Component.errorString will fail, for example)
\li a script without imports will inherit imports from the QML document which imported it (so accessing Component.errorString will succeed, for example)
\li a shared script (i.e., defined as .pragma library) does not inherit imports from any QML document even if it imports no other scripts or modules
\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).
\section2 Importing a JavaScript Resource from Another JavaScript Resource
A JavaScript resource may import another in the following fashion:
\code
.import "filename.js" as Qualifier
\endcode
For example:
\code
.import "factorial.js" as MathFunctions
\endcode
\section2 Importing a QML Module from a JavaScript Resource
A JavaScript resource may import a QML module in the following fashion:
\code
.import TypeNamespace MajorVersion.MinorVersion as Qualifier
\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 singleton type; see qmlRegisterSingletonType() for more information.
\note The .import syntax doesn't work for scripts used in the \l {WorkerScript}
\section1 Including a JavaScript Resource from Another JavaScript Resource
When a JavaScript file is imported, it must be imported with a qualifier. The
functions in that file are then accessible from the importing script via the
qualifier (that is, as \tt{Qualifier.functionName(params)}). Sometimes it is
desirable to have the functions made available in the importing context without
needing to qualify them, and in this circumstance the \l{QML:Qt::include()}
{Qt.include()} function may be used to include one JavaScript file from another.
This copies all functions from the other file into the current file's
namespace, but ignores all pragmas and imports defined in that file.
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
\li {1,2} \snippet qml/integrating-javascript/includejs/app.qml 0
\li \snippet qml/integrating-javascript/includejs/script.js 0
\row
\li \snippet qml/integrating-javascript/includejs/factorial.js 0
\endtable
Notice that calling \l {QML:Qt::include()}{Qt.include()} copies 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().
*/
|
