diff options
Diffstat (limited to 'src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc')
-rw-r--r-- | src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc b/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc new file mode 100644 index 0000000000..7a6fb58c27 --- /dev/null +++ b/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc @@ -0,0 +1,203 @@ +/**************************************************************************** +** +** 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-syntax-directoryimports.html +\title Importing QML Document Directories +\brief Description of directory import statements in QML + +A local directory of QML files can be imported without any additional setup or +configuration. A remote directory of QML files can also be imported, but +requires a directory listing \c qmldir file to exist. A local directory may +optionally contain a directory listing \c qmldir file in order to define the +type names which should be provided to clients which import the directory, and +to specify JavaScript resources which should be made available to importers. + + +\section1 Local Directory Imports + +Any QML file on the local file system can import a local directory as using an +import statement that refers to the directory's absolute or relative file +system path, enabling the file to use the \l{qtqml-typesystem-objecttypes.html} +{object types} defined within that directory. + +If the local directory contains a directory listing \c qmldir file, the types +will be made available with the type names specified in the \c qmldir file; +otherwise, they will be made available with type names derived from the +filenames of the QML documents. Only filenames beginning with an uppercase +letter and ending with ".qml" will be exposed as types if no \c qmldir file +is specified in the directory. + +\section2 An Example + +Consider the following QML project directory structure. Under the top level directory \c myapp, +there are a set of common UI components in a sub-directory named \c mycomponents, and the main +application code in a sub-directory named \c main, like this: + +\code +myapp + |- mycomponents + |- CheckBox.qml + |- DialogBox.qml + |- Slider.qml + |- main + |- application.qml +\endcode + +The \c main/application.qml file can import the \c mycomponents directory using +the relative path to that directory, allowing it to use the QML object types +defined within that directory: + +\qml +import "../mycomponents" + +DialogBox { + CheckBox { + // ... + } + Slider { + // ... + } +} +\endqml + +The directory may be imported into a qualified local namespace, in which case +uses of any types provided in the directory must be qualified: + +\qml +import "../mycomponents" as MyComponents + +MyComponents.DialogBox { + // ... +} +\endqml + +The ability to import a local directory is convenient for cases such as +in-application component sets and application prototyping, although any code +that imports such modules must must update their relevant \c import statements +if the module directory moves to another location. This can be avoided if +\l{qtqml-modules-identifiedmodules.html}{QML modules} are used instead, +as an installed module is imported with a unique identifier string rather than +a file system path. + + +\section1 Remotely Located Directories + +A directory of QML files can also be imported from a remote location if the +directory contains a directory listing \c qmldir file. + +For example, if the \c myapp directory in the previous example was hosted at +"http://www.my-example-server.com", and the \c mycomponents directory +contained a \c qmldir file defined as follows: + +\code +CheckBox CheckBox.qml +DialogBox DialogBox.qml +Slider Slider.qml +\endcode + +Then, the directory could be imported using the URL to the remote +\c mycomponents directory: + +\qml +import "http://www.my-example-server.com/myapp/mycomponents" + +DialogBox { + CheckBox { + // ... + } + Slider { + // ... + } +} +\endqml + +Note that when a file imports a directory over a network, it can only access QML +and JavaScript files specified in the \c qmldir file located in the directory. + +\warning When importing directories from a remote server, developers should +always be careful to only load directories from trusted sources to avoid +loading malicious code. + + +\section1 Directory Listing qmldir Files + +A directory listing \c qmldir file distinctly different from a +\l{qtqml-modules-qmldir.html}{module definition qmldir file}. A directory +listing \c qmldir file allows a group of QML documents to be quickly and easily +shared, but it does not define a type namespace into which the QML object types +defined by the documents are registered, nor does it support versioning of +those QML object types. + +The syntax of a directory listing \c qmldir file is as follows: +\table + \header + \li Command + \li Syntax + \li Description + + \row + \li Object Type Declaration + \li <TypeName> <FileName> + \li An object type declaration allows a QML document to be exposed with + the given \c <TypeName>. + + Example: + \code +RoundedButton RoundedBtn.qml + \endcode + + \row + \li Internal Object Type Declaration + \li internal <TypeName> <FileName> + \li An internal object type declaration allows a QML document to be + registered as a type which becomes available only to the other + QML documents contained in the directory import. The internal + type will not be made available to clients who import the directory. + + Example: + \code +internal HighlightedButton HighlightedBtn.qml + \endcode + + \li JavaScript Resource Declaration + \li <Identifier> <FileName> + \li A JavaScript resource declaration allows a JavaScript file to be + exposed via the given identifier. + + Example: + \code +MathFunctions mathfuncs.js + \endcode +\endtable + +A local file system directory may optionally include a \c qmldir file. This +allows the engine to only expose certain QML types to clients who import the +directory. Additionally, JavaScript resources in the directory are not exposed +to clients unless they are declared in a \c qmldir file. + +*/ + |