diff options
| -rw-r--r-- | src/qml/doc/src/cppclasses/component.qdoc | 85 | ||||
| -rw-r--r-- | src/qml/doc/src/cppclasses/context.qdoc | 96 | ||||
| -rw-r--r-- | src/qml/doc/src/cppclasses/engine.qdoc | 62 | ||||
| -rw-r--r-- | src/qml/doc/src/cppclasses/expression.qdoc | 36 | ||||
| -rw-r--r-- | src/qml/doc/src/cppclasses/topic.qdoc | 88 | ||||
| -rw-r--r-- | src/qml/doc/src/cppclasses/valuesource.qdoc | 36 | ||||
| -rw-r--r-- | src/qml/doc/src/qtqml.qdoc | 11 | ||||
| -rw-r--r-- | src/quick/doc/src/appdevguide/applicationdevelopers.qdoc | 3 |
8 files changed, 64 insertions, 353 deletions
diff --git a/src/qml/doc/src/cppclasses/component.qdoc b/src/qml/doc/src/cppclasses/component.qdoc deleted file mode 100644 index 8eb22283b4..0000000000 --- a/src/qml/doc/src/cppclasses/component.qdoc +++ /dev/null @@ -1,85 +0,0 @@ -/**************************************************************************** -** -** 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-cppclasses-component.html -\title Qt QML Module C++ Classes - QQmlComponent -\brief Description of QQmlComponent - - \section2 Loading QML Components from C++ - - A QML document can be loaded with QQmlComponent or QQuickView. - QQmlComponent loads a QML component as a C++ QObject; - QQuickView also does this, but additionally loads the QML component - directly into a QQuickWindow which displays visual QML object types - provided by Qt Quick, or object types derived from those. - It is convenient for loading a displayable - QML component as a root QWindow. - - For example, suppose there is a \c MyItem.qml file that looks like this: - - \snippet qml/qtbinding/loading/MyItem.qml start - \snippet qml/qtbinding/loading/MyItem.qml end - - This QML document can be loaded with QQmlComponent or - QQuickView with the following C++ code. Using a QQmlComponent - requires calling QQmlComponent::create() to create a new instance of - the component, while a QQuickView automatically creates an instance of - the component, which is accessible via QQuickView::rootObject(): - - \table - \row - \li - \snippet qml/qtbinding/loading/main.cpp QQmlComponent-a - \dots 0 - \snippet qml/qtbinding/loading/main.cpp QQmlComponent-b - \li - \snippet qml/qtbinding/loading/main.cpp QQuickView - \endtable - - This \c object is the instance of the \c MyItem.qml component that has been - created. You can now modify the item's properties using - QObject::setProperty() or QQmlProperty: - - \snippet qml/qtbinding/loading/main.cpp properties - - Alternatively, you can cast the object to its actual type and call functions - with compile-time safety. In this case the base object of \c MyItem.qml is - an \l Item, which is defined by the QQuickItem class: - - \snippet qml/qtbinding/loading/main.cpp cast - - You can also connect to any signals or call functions defined in the - component using QMetaObject::invokeMethod() and QObject::connect(). See \l - {Interacting with Objects defined in QML from C++} for further details. - - - - - - - -*/ diff --git a/src/qml/doc/src/cppclasses/context.qdoc b/src/qml/doc/src/cppclasses/context.qdoc deleted file mode 100644 index 0745da3737..0000000000 --- a/src/qml/doc/src/cppclasses/context.qdoc +++ /dev/null @@ -1,96 +0,0 @@ -/**************************************************************************** -** -** 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-cppclasses-context.html -\title Qt QML Module C++ Classes - QQmlContext -\brief Description of QQmlContext - - - - - \section2 Embedding C++ Objects into QML Components - - When loading a QML scene into a C++ application, it can be useful to - directly embed C++ data into the QML object. QQmlContext enables - this by exposing data to the context of a QML component, allowing data to be - injected from C++ into QML. - - For example, here is a QML item that refers to a \c currentDateTime value - that does not exist in the current scope: - - \snippet qml/qtbinding/context/MyItem.qml 0 - - This \c currentDateTime value can be set directly by the C++ application - that loads the QML component, using - QQmlContext::setContextProperty(): - - \snippet qml/qtbinding/context/main.cpp 0 - - Context properties can hold either QVariant or QObject* values. This means - custom C++ objects can also be injected using this approach, and these - objects can be modified and read directly in QML. Here, we modify the above - example to embed a QObject instance instead of a QDateTime value, and the - QML code invokes a method on the object instance: - - \table - \row - \li - \snippet qml/qtbinding/context-advanced/applicationdata.h 0 - \codeline - \snippet qml/qtbinding/context-advanced/main.cpp 0 - \li - \snippet qml/qtbinding/context-advanced/MyItem.qml 0 - \endtable - - (Note that date/time values returned from C++ to QML can be formatted through - \l{QML:Qt::formatDateTime}{Qt.formatDateTime()} and associated functions.) - - If the QML item needs to receive signals from the context property, it can - connect to them using the \l Connections element. For example, if \c - ApplicationData has a signal named \c dataChanged(), this signal can be - connected to using an \c onDataChanged handler within a \l Connections - object: - - \snippet qml/qtbinding/context-advanced/connections.qml 0 - - Context properties can be useful for using C++ based data models in a QML view. See the - \l {quick/modelviews/stringlistmodel}{String ListModel}, - \l {quick/modelviews/objectlistmodel}{Object ListModel} and - \l {quick/modelviews/abstractitemmodel}{AbstractItemModel} models for - respective examples on using QStringListModel, QObjectList-based models and QAbstractItemModel - in QML views. - - Also see the QQmlContext documentation for more information. - - - - - - - - -*/ diff --git a/src/qml/doc/src/cppclasses/engine.qdoc b/src/qml/doc/src/cppclasses/engine.qdoc deleted file mode 100644 index 7bb40f7b64..0000000000 --- a/src/qml/doc/src/cppclasses/engine.qdoc +++ /dev/null @@ -1,62 +0,0 @@ -/**************************************************************************** -** -** 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-cppclasses-engine.html -\title Qt QML Module C++ Classes - QQmlEngine -\brief Description of QQmlEngine - - -The QML engine runs and executes QML -applications. The engine loads, instantiates, and executes the QML context as -specified in QML files, plugins, or applications. - - - A QQmlEngine allows the configuration of global settings that - apply to all of its QML component instances: for example, the - QNetworkAccessManager to be used for network communications, and the - file path to be used for persistent storage. - - QQmlComponent is used to load QML documents. Each - QQmlComponent instance represents a single document. A component - can be created from the URL or file path of a QML document, or the raw - QML code of the document. Component instances are instatiated through - the QQmlComponent::create() method, like this: - - \code - QQmlEngine engine; - QQmlComponent component(&engine, QUrl::fromLocalFile("MyRectangle.qml")); - QObject *rectangleInstance = component.create(); - - // ... - delete rectangleInstance; - \endcode - - QML documents can also be loaded using QQuickView. - - - -*/ diff --git a/src/qml/doc/src/cppclasses/expression.qdoc b/src/qml/doc/src/cppclasses/expression.qdoc deleted file mode 100644 index 76db1cebf1..0000000000 --- a/src/qml/doc/src/cppclasses/expression.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** 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-cppclasses-expression.html -\title Qt QML Module C++ Classes - QQmlExpression -\brief Description of QQmlExpression - -QQmlExpression provides a C++ interface to evaluate JavaScript expressions -within a particular QML context. - -*/ diff --git a/src/qml/doc/src/cppclasses/topic.qdoc b/src/qml/doc/src/cppclasses/topic.qdoc index b552a9c50a..04036d6db3 100644 --- a/src/qml/doc/src/cppclasses/topic.qdoc +++ b/src/qml/doc/src/cppclasses/topic.qdoc @@ -26,35 +26,52 @@ ****************************************************************************/ /*! \page qtqml-cppclasses-topic.html -\title C++ Classes Provided by the Qt QML Module +\title Important C++ Classes Provided By The Qt QML Module \brief Overview of the C++ classes provided by the Qt QML module The Qt QML module provides C++ classes which implement the QML framework. Clients can use these classes to interact with the QML run-time (for example, by injecting data or invoking methods on objects), and to instantiate a -hierarchy of objects from a QML document. +hierarchy of objects from a QML document. The Qt QML module provides more +C++ API than just the classes listed here, however the classes listed here +provide the foundations of the QML runtime and the core concepts of QML. -\section1 The QQmlEngine Class +\section1 QML Runtime + +A typical QML application with a C++ entry-point will instantiate a QQmlEngine +and then use a QQmlComponent to load a QML document. The engine provides a +default QQmlContext which will be the top-level evaluation context used for +evaluating functions and expressions defined in the QML document. +The object hierarchy defined in the QML document will be instantiated by +calling the \l{QQmlComponent::create()}{create()} function of the QQmlComponent +instance, assuming that no errors were encountered during document loading. + +The client may wish to modify the QQmlContext provided by the engine, by +injecting properties or objects into the context. They can call the +\l{QQmlEngine::rootContext()} function to access the top-level context. + +After instantiating the object, the client will usually pass control to the +application event loop so that user input events (like mouse-clicks) can be +delivered and handled by the application. + +\note The Qt Quick module provides a convenience class, QQuickView, which +provides a QML runtime and visual window for displaying a QML application. + +\section2 The QQmlEngine Class The QQmlEngine class provides an engine which can manage a hierarchy of objects which is defined in a QML document. It provides a root QML context within which expressions are evaluated, and ensures that properties of objects are updated correctly when required. -See \l{qtqml-cppclasses-engine.html}{Qt QML Module C++ Classes - QQmlEngine} -for in-depth information about QQmlEngine. +A QQmlEngine allows the configuration of global settings that apply to all of +the objects it manages; for example, the QNetworkAccessManager to be used for +network communications, and the file path to be used for persistent storage. -\section1 The QQmlComponent Class +See the \l{QQmlEngine} class documentation for in-depth information about what +the QQmlEngine class provides, and how it can be used in an application. -The QQmlComponent class is used to load a QML document. It requires a -QQmlEngine in order to instantiate the hierarchy of objects defined in the QML -document. - -See -\l{qtqml-cppclasses-component.html}{Qt QML Module C++ Classes - QQmlComponent} -for in-depth information about QQmlComponent. - -\section1 The QQmlContext Class +\section2 The QQmlContext Class The QQmlContext class provides a context for object instantiation and expression evaluation. All objects are instantiated in a particular context, @@ -62,10 +79,30 @@ and all of the expressions which are evaluated while an application is running are evaluated within a particular context. This context defines how symbols are resolved, and thus which values the expression operates on. -See \l{qtqml-cppclasses-context.html}{Qt QML Module C++ Classes - QQmlContext} -for in-depth information about QQmlContext. +See the \l{QQmlContext} class documentation for in-depth information about +how to modify the evaluation context of an object by adding or removing +properties of a QQmlContext, and how to access the context for an object. + +\section1 Dynamic Object Instantiation and Expression Evaluation -\section1 The QQmlExpression Class +Dynamic object instantiation and dynamic expression evaluation are both core +concepts in QML. QML documents define object types which can be instantiated +at run-time using a QQmlComponent. An instance of the QQmlComponent class can +be created in C++ directly, or via the \l{QML:Qt::createComponent()} +{Qt.createComponent()} function in imperative QML code. Arbitrary expressions +can be calculated in C++ via the QQmlExpression class, and such expressions +can interact directly the QML context. + +\section2 The QQmlComponent Class + +The QQmlComponent class can be used to load a QML document. It requires a +QQmlEngine in order to instantiate the hierarchy of objects defined in the QML +document. + +See the \l{QQmlComponent} class documentation for in-depth information about +how to use QQmlComponent. + +\section2 The QQmlExpression Class The QQmlExpression class provides a way for clients to evaluate JavaScript expressions from C++, using a particular QML evaluation context. This allows @@ -73,18 +110,7 @@ clients to access QML objects by id, for example. The result of evaluation is returned as a QVariant, and the conversion rules are defined by the QML engine. -See \l{qtqml-cppclasses-expression.html} -{Qt QML Module C++ Classes - QQmlExpression} for in depth information about -QQmlExpression. - -\section1 The QQmlPropertyValueSource Class - -The QQmlPropertyValueSource class is an abstract class which may be inherited -to provide unique \l{qtqml-typesystem-topic.html#property-modifier-types} -{property value sources}. - -See \l{qtqml-cppclasses-valuesource.html} -{Qt QML Module C++ Classes - QQmlPropertyValueSource} for in depth information -about QQmlPropertyValueSource. +See the \l{QQmlExpression} class documentation for in depth information about +how to use QQmlExpression in an application. */ diff --git a/src/qml/doc/src/cppclasses/valuesource.qdoc b/src/qml/doc/src/cppclasses/valuesource.qdoc deleted file mode 100644 index 92c8c3acd1..0000000000 --- a/src/qml/doc/src/cppclasses/valuesource.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** 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-cppclasses-valuesource.html -\title Qt QML Module C++ Classes - QQmlPropertyValueSource -\brief Description of QQmlPropertyValueSource - -QQmlPropertyValueSource may be inherited by client-defined classes to provide -a custom property value source kind of property value modifier. - -*/ diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc index be4232eab1..6d655a3497 100644 --- a/src/qml/doc/src/qtqml.qdoc +++ b/src/qml/doc/src/qtqml.qdoc @@ -70,13 +70,12 @@ types, animation classes, and canvas integration) for the QML language. \section1 Qt QML Module Documentation \list - \li \l{qtqml-cppclasses-topic.html}{C++ Classes Provided by the Qt QML Module} + \li \l{qtqml-cppclasses-topic.html}{Important C++ Classes} \list - \li \l{qtqml-cppclasses-engine.html}{QQmlEngine} - \li \l{qtqml-cppclasses-context.html}{QQmlContext} - \li \l{qtqml-cppclasses-component.html}{QQmlComponent} - \li \l{qtqml-cppclasses-expression.html}{QQmlExpression} - \li \l{qtqml-cppclasses-valuesource.html}{QQmlPropertyValueSource} + \li \l{QQmlEngine} + \li \l{QQmlContext} + \li \l{QQmlComponent} + \li \l{QQmlExpression} \endlist \li \l{qtqml-typesystem-topic.html}{The QML Type System} diff --git a/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc b/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc index 606cffe694..709e2cd5a7 100644 --- a/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc +++ b/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc @@ -96,7 +96,8 @@ Qt Quick.} \li \l{qtquick-quickstart-essentials.html}{QML Essentials} \list \li \l{qtquick-quickstart-essentials.html#handling-user-input}{Handling User Input} - \li \l{qtquick-quickstart-essentials.html#property-bindings-and-animations}{Property Bindings and Animations} + \li \l{qtquick-quickstart-essentials.html#property-bindings}{Property Bindings} + \li \l{qtquick-quickstart-essentials.html#animations}{Animations} \li \l{qtquick-quickstart-essentials.html#defining-custom-qml-types-for-re-use}{Defining Custom QML Types for Re-use} \endlist \endlist |