src/qml/doc/src/syntax/imports.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27 /*!
  28 \page qtqml-syntax-imports.html
  29 \title Import Statements
  30 \brief Description of import statements in QML
  31
  32 \section1 Syntax of an Import Statement
  33
  34
  35 The \c import statement is used to provide the QML engine with access to the modules that define the types that are referred to from within the QML file.
  36
  37 The syntax for the \c import statement is:
  38
  39 \code
  40 import <module> <major version>.<minor version> [as <namespace>]
  41 \endcode
  42
  43 When a QML file is loaded by the engine, the only QML types that are automatically made available to that file are those that are \l{Defining Object Types through QML Documents}{defined by .qml files} within the same directory. Any types defined elsewhere are not accessible unless an \c import statement has imported the module that contains the required type. For example, the \c QtQuick module must be imported in order to use any of its QML types:
  44
  45 \qml
  46 import QtQuick 2.0
  47
  48 Rectangle {}    // won't work if import line is missing, engine will refuse to load the file
  49 \endqml
  50
  51 The \c <module> can be either a filesystem path to the module, or an identifier for the module if it is accessible to the import path. For example:
  52
  53 \code
  54 import "../relative/path/to/module"
  55 import "/absolute/path/to/module"
  56 import com.company.module
  57 \endcode
  58
  59 (See \l {QML Modules} for more information on defining and importing located and installed modules.)
  60
  61
  62 \note Import paths are network transparent: applications can import documents from remote paths just as simply as documents from local paths. See the general URL resolution rules for \l{qtqml-documents-networktransparency.html}{Network Transparency} in QML documents.
  63
  64
  65 \section1 Debugging
  66
  67 The \c QML_IMPORT_TRACE environment variable can be useful for debugging
  68 when there are problems with finding and loading modules. See
  69 \l{Debugging module imports} for more information.
  70
  71
  72 \section1 QML Import Path
  73
  74 When an \l{qtqml-modules-installedmodules.html}{installed module} is imported, the QML engine
  75 searches the \e{import path} for a matching module.
  76
  77 This import path, as returned by QQmlEngine::importPathList(), defines the default
  78 locations to be searched by the engine. By default, this list contains:
  79
  80 \list
  81 \li The directory of the current file
  82 \li The location specified by QLibraryInfo::ImportsPath
  83 \li Paths specified by the \c QML_IMPORT_PATH environment variable
  84 \endlist
  85
  86 Additional import paths can be added through QQmlEngine::addImportPath() or the
  87 \c QML_IMPORT_PATH environment variable. When running the \l {Prototyping with qmlscene}{qmlscene}
  88 tool, you can also use the \c -I option to add an import path.
  89
  90
  91
  92 \section1 Namespaced Imports
  93
  94
  95
  96 The \c import statement may optionally use the \c as keyword to specify that the module should be imported into a particular namespace. If a namespace is specified, then any references to the types made available by the module must be prefixed by the namespace qualifier.
  97
  98 Below, the QtQuick module is imported into the namespace "CoreItems". Now, any references to types from the \c QtQuick module must be prefixed with the \c CoreItems name:
  99
 100 \qml
 101 import QtQuick 2.0 as CoreItems
 102
 103 CoreItems.Rectangle {
 104     width: 100; height: 100
 105
 106     CoreItems.Text { text: "Hello, world!" }
 107
 108     // WRONG! No namespace prefix - the Text type won't be found
 109     Text { text: "Hello, world!" }
 110 }
 111 \endqml
 112
 113 A namespace acts as an identifier for a module within the scope of the file. The namespace does not become an attribute of the root object that can be referred to externally as can be done with properties, signals and methods.
 114
 115 The namespaced import is useful if there is a requirement to use two QML types that have the same name but are located in different modules. In this case the two modules can be imported into different namespaces to ensure the code is referring to the correct type:
 116
 117 \qml
 118 import QtQuick 2.0 as CoreItems
 119 import "../textwidgets" as MyModule
 120
 121 CoreItems.Rectangle {
 122     width: 100; height: 100
 123
 124     MyModule.Text { text: "Hello from my custom text item!" }
 125     CoreItems.Text { text: "Hello from QtQuick!" }
 126 }
 127 \endqml
 128
 129 Note that multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace. For example:
 130
 131 \snippet qml/imports/merged-named-imports.qml imports
 132
 133
 134
 135
 136 \section1 Relative Directory Imports
 137
 138 \section1 JavaScript File Imports
 139
 140
 141 JavaScript files must always be imported with a named import:
 142
 143 \qml
 144 import "somescript.js" as MyScript
 145
 146 Item {
 147     //...
 148     Component.onCompleted: MyScript.doSomething()
 149 }
 150 \endqml
 151
 152 The qualifier ("MyScript" in the above example) must be unique within the QML document.
 153 Unlike ordinary modules, multiple scripts cannot be imported into the same namespace.
 154
 155 Javascript files can be provided by modules, by adding Namespace definitions to the
 156 \l{Syntax of a qmldir file}{qmldir file} for the module.  For example:
 157
 158 \code
 159 SystemFunctions 1.0 SystemFunctions.js
 160 UserFunctions 1.0 UserFunctions.js
 161 \endcode
 162
 163 Javascript can be imported from a module, where they will have the namespace defined
 164 for them in the module's \c qmldir file:
 165
 166 \qml
 167 import projects.MyQMLProject.MyFunctions 1.0
 168
 169 Window {
 170     Component.onCompleted: { SystemFunctions.cleanUp(); }
 171 }
 172 \endqml
 173
 174 Javascript provided by modules can also be imported into namespaces:
 175
 176 \qml
 177 import projects.MyQMLProject.MyFunctions 1.0 as MyFuncs
 178 import org.example.Functions 1.0 as TheirFuncs
 179
 180 Window {
 181     Component.onCompleted: {
 182         MyFuncs.SystemFunctions.cleanUp();
 183         TheirFuncs.SystemFunctions.shutdown();
 184     }
 185 }
 186 \endqml
 187
 188
 189 \section1 Version Specification
 190
 191 \section1 Import Qualifier
 192
 193 */