1 files changed, 136 insertions, 0 deletions
diff --git a/src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc b/src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc
new file mode 100644
index 0000000000..7ac1d400eb
--- /dev/null
+++ b/src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc
@@ -0,0 +1,136 @@
+/****************************************************************************
+**
+** 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-modules-cppplugins.html
+\title Creating C++ Plugins for QML
+\brief Description of how to write C++ plugins for QML
+
+\section1 Creating a Plugin
+
+    The \l{QQmlEngine}{QML engine} load C++ plugins for QML.
+    Such plugins are usually provided in a QML extension module, and can
+    provide types and functionality for use by clients in QML documents
+    which import the module.
+
+    QQmlExtensionPlugin is a plugin interface that makes it possible to
+    create QML extensions that can be loaded dynamically into QML applications.
+    These extensions allow custom QML types to be made available to the
+    QML engine.
+
+    To write a QML extension plugin:
+    \list 1
+    \li Subclass QQmlExtensionPlugin
+        \list
+            \li Use the Q_PLUGIN_METADATA() macro to register the plugin with
+                the Qt meta object system
+            \li Override the \l{QQmlExtensionPlugin::}{registerTypes()} method
+                and call qmlRegisterType() to register the types to be exported
+                by the plugin
+        \endlist
+    \li Write a project file for the plugin
+    \li Create a \l{Module Definition qmldir Files}{qmldir file} to
+        describe the plugin
+    \endlist
+
+    QML extension plugins are for either application-specific or library-like
+    plugins. Library plugins should limit themselves to registering types, as
+    any manipulation of the engine's root context may cause conflicts or other
+    issues in the library user's code.
+
+\section1 Plugin Example
+
+    Suppose there is a new \c TimeModel C++ class that should be made available
+    as a new QML type. It provides the current time through \c hour and \c minute
+    properties.
+
+    \snippet plugins/plugin.cpp 0
+    \dots
+
+    To make this type available, we create a plugin class named \c QExampleQmlPlugin
+    which is a subclass of \l QQmlExtensionPlugin. It overrides the
+    \l{QQmlExtensionPlugin::}{registerTypes()} method in order to register the \c TimeModel
+    type using qmlRegisterType(). It also uses the Q_PLUGIN_METADATA() macro in the class
+    definition to register the plugin with the Qt meta object system using a unique
+    identifier for the plugin.
+
+    \snippet plugins/plugin.cpp plugin
+
+    The \c TimeModel class receives a \c{1.0} version of this plugin library, as
+    a QML type called \c Time. The Q_ASSERT() macro can ensure the type namespace is
+    imported correctly by any QML components that use this plugin. The
+    \l{Defining QML Types from C++} article has more information about registering C++
+    types into the runtime.
+
+    For this example, the TimeExample source directory is in
+    \c{imports/TimeExample}.  The plugin's type namespace will mirror
+    this structure, so the types are registered into the namespace
+    "TimeExample".
+
+    Additionally, the project file, in a \c .pro file, defines the project as a plugin library,
+    specifies it should be built into the \c imports/TimeExample directory, and registers
+    the plugin target name and various other details:
+
+    \code
+    TEMPLATE = lib
+    CONFIG += qt plugin
+    QT += qml
+
+    DESTDIR = imports/TimeExample
+    TARGET = qmlqtimeexampleplugin
+    SOURCES += qexampleqmlplugin.cpp
+    \endcode
+
+    Finally, a \l{Module Definition qmldir Files}{qmldir file} is required
+    in the \c imports/TimeExample directory to describe the plugin and the types that it
+    exports. The plugin includes a \c Clock.qml file along with the \c qmlqtimeexampleplugin
+    that is built by the project (as shown above in the \c .pro file) so both of these
+    need to be specified in the \c qmldir file:
+
+    \quotefile plugins/imports/TimeExample/qmldir
+
+    Once the project is built and installed, the new \c Time component is
+    accessible by any QML component that imports the \c TimeExample
+    module
+
+    \snippet plugins/plugins.qml 0
+
+    The full source code is available in the \l {qml/plugins}{plugins example}.
+
+
+\section1 Reference
+
+    \list
+    \li \l {Writing QML Extensions with C++} - contains a chapter
+    on creating QML plugins.
+    \li \l{Defining QML Types from C++} - information about registering C++ types into
+    the runtime.
+    \li \l{How to Create Qt Plugins} - information about Qt plugins
+    \endlist
+
+
+*/