aboutsummaryrefslogtreecommitdiffstats
path: root/src/qml/doc/src/modules/topic.qdoc
diff options
context:
space:
mode:
authorChris Adams <christopher.adams@nokia.com>2012-05-28 17:12:56 +1000
committerQt by Nokia <qt-info@nokia.com>2012-06-21 09:58:56 +0200
commit5e33b0f580d2b20f1a2989bf2ee8dde4525a2e39 (patch)
tree780d25ce7d8955e56ea985a35dd84609df12fbf0 /src/qml/doc/src/modules/topic.qdoc
parent03342a435a88656d64d1445991a4421d244fcb45 (diff)
Create new documentation structure
The documentation currently has no clear separation between Qt QML and Qt Quick. With recent commits like: 6c8378eaf1edbbefe6aaa3672b0127816a004fd7 and ab1e510121c8a679fdaca12ccd30e0f7ac12a26b the separation between the language definition and implementation, provided by Qt QML, and the standard library for the QML language, provided by Qt Quick, is clear. This commit creates a new documentation structure that is more navigable and separates concepts into logical categories, with clear separation between QtQML and QtQuick. It also provides a more generic QML Application Developer Resources page which contains links to information for QML application developers. Change-Id: Ia807ccfbfd24ffa0e1c7f0a51ed9d2ed3aa6a733 Reviewed-by: Martin Jones <martin.jones@nokia.com>
Diffstat (limited to 'src/qml/doc/src/modules/topic.qdoc')
-rw-r--r--src/qml/doc/src/modules/topic.qdoc92
1 files changed, 92 insertions, 0 deletions
diff --git a/src/qml/doc/src/modules/topic.qdoc b/src/qml/doc/src/modules/topic.qdoc
new file mode 100644
index 0000000000..0356c3da73
--- /dev/null
+++ b/src/qml/doc/src/modules/topic.qdoc
@@ -0,0 +1,92 @@
+/****************************************************************************
+**
+** 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-modules-topic.html
+\title Writing Extension Modules For QML
+\brief Description of how to write extension modules for QML
+
+A QML module is an extension to QML which can be imported by clients. A QML
+module can contain QML documents which provide type definitions, JavaScript
+files which provide functionality, and C++ plugins which can provide QML types,
+invokable functions, and other functionality. The module system provided by
+QML allows functionality to be grouped into modules which can be loaded by
+applications which need them, with zero impact upon applications which do not.
+
+A QML module must be imported by client QML application developers using an
+\l{qtqml-syntax-imports.html}{Import Statements}. Some imports must be
+qualified (that is, the imported type or file must be given an identifier),
+while others do not.
+
+The Qt Quick module provides a QML module called QtQuick which can be imported
+via the familiar
+\code
+import QtQuick 2.0
+\endcode
+
+import statement.
+
+QML modules are exposed to the QML type system via a module description file
+called a "qmldir" file.
+
+\section1 Packaging QML and JavaScript Files
+
+A QML document implicitly defines a QML object type. Clients can create
+reusable components by defining types as QML documents and exposing them
+to the type system directly. QML extension module developers can provide
+QML object types defined in QML documents to clients also.
+
+QML extension module developers can also provide functionality in JavaScript
+files. When imported directly, JavaScript files must be imported with a
+qualifier; conversely, when providing a JavaScript file in a QML extension
+module, the module author must provide the qualifier.
+
+See the documentation about \l{qtqml-javascript-topic.html}
+{integrating QML and JavaScript} for more information about what types of
+functionality can be implemented in JavaScript.
+
+\section1 Providing Types And Functionality In A C++ Plugin
+
+An application which has a lot of logic implemented in C++, or which defines
+types in C++ and exposes them to QML, may wish to implement a QML plugin. A
+QML extension module developer may wish to implement some types in a C++ plugin
+(as opposed to defining them via QML documents) to achieve better performance
+or for greater flexibility.
+
+Every C++ plugin for QML has an initialiatization function which is called by
+the QML engine when it loads the plugin. This initialization function must
+register any types that the plugin provides, but must not do anything else
+(for example, instantiating QObjects is not allowed).
+
+\section1 Syntax Of A qmldir File
+
+The standard way to expose a QML extension module to the QML type system is to
+write a \c qmldir file which describes to the QML engine what the module
+contains. The qmldir file and the associated content (QML documents,
+JavaScript files, and C++ plugins) must be placed somewhere into the
+\l{qtqml-syntax-imports.html#qml-import-path}{QML import path}.
+
+*/