diff options
Diffstat (limited to 'src/qml/doc')
46 files changed, 561 insertions, 552 deletions
diff --git a/src/qml/doc/qtqml.qdocconf b/src/qml/doc/qtqml.qdocconf index 4ce44ba46e..2198428a38 100644 --- a/src/qml/doc/qtqml.qdocconf +++ b/src/qml/doc/qtqml.qdocconf @@ -18,7 +18,7 @@ qhp.QtQml.indexRoot = qhp.QtQml.filterAttributes = qtqml $QT_VERSION qtrefdoc qhp.QtQml.customFilters.Qt.name = QtQml $QT_VERSION qhp.QtQml.customFilters.Qt.filterAttributes = qtqml $QT_VERSION -qhp.QtQml.subprojects = classes examples +qhp.QtQml.subprojects = qmltypes classes examples qhp.QtQml.subprojects.classes.title = C++ Classes qhp.QtQml.subprojects.classes.indexTitle = Qt QML C++ Classes qhp.QtQml.subprojects.classes.selectors = class fake:headerfile @@ -26,15 +26,21 @@ qhp.QtQml.subprojects.classes.sortPages = true qhp.QtQml.subprojects.examples.title = Examples qhp.QtQml.subprojects.examples.indexTitle = Qt Quick Code Samples qhp.QtQml.subprojects.examples.selectors = fake:example +qhp.QtQml.subprojects.qmltypes.title = QML Types +qhp.QtQml.subprojects.qmltypes.indexTitle = Qt QML QML Types +qhp.QtQml.subprojects.qmltypes.selectors = fake:qmlclass +qhp.QtQml.subprojects.qmltypes.sortPages = true tagfile = ../../../doc/qtqml/qtqml.tags -depends += qtcore qtxmlpatterns qtgui qtquick +depends += qtcore qtxmlpatterns qtgui qtquick qtdoc -headerdirs += .. +headerdirs += .. \ + ../../imports/models -sourcedirs += .. +sourcedirs += .. \ + ../../imports/models exampledirs += ../../../examples/qml \ ../ \ diff --git a/src/qml/doc/snippets/delegatemodel/visualdatagroup.qml b/src/qml/doc/snippets/delegatemodel/visualdatagroup.qml new file mode 100644 index 0000000000..4254b50e63 --- /dev/null +++ b/src/qml/doc/snippets/delegatemodel/visualdatagroup.qml @@ -0,0 +1,81 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +import QtQuick 2.0 + +Rectangle { + width: 200; height: 100 + + VisualDataModel { + id: visualModel + model: ListModel { + ListElement { name: "Apple" } + ListElement { name: "Orange" } + } + + groups: [ + VisualDataGroup { name: "selected" } + ] + + delegate: Rectangle { + id: item + height: 25 + width: 200 + Text { + text: { + var text = "Name: " + name + if (item.VisualDataModel.inSelected) + text += " (" + item.VisualDataModel.selectedIndex + ")" + return text; + } + } + MouseArea { + anchors.fill: parent + onClicked: item.VisualDataModel.inSelected = !item.VisualDataModel.inSelected + } + } + } + + ListView { + anchors.fill: parent + model: visualModel + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/folderlistmodel.qml b/src/qml/doc/snippets/delegatemodel/visualdatamodel.qml index b43949c487..0513c5b5f2 100644 --- a/src/qml/doc/snippets/qml/folderlistmodel.qml +++ b/src/qml/doc/snippets/delegatemodel/visualdatamodel.qml @@ -37,25 +37,28 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - //![0] import QtQuick 2.0 -import Qt.labs.folderlistmodel 1.0 -ListView { - width: 200; height: 400 +Rectangle { + width: 200; height: 100 - FolderListModel { - id: folderModel - nameFilters: ["*.qml"] + VisualDataModel { + id: visualModel + model: ListModel { + ListElement { name: "Apple" } + ListElement { name: "Orange" } + } + delegate: Rectangle { + height: 25 + width: 100 + Text { text: "Name: " + name} + } } - Component { - id: fileDelegate - Text { text: fileName } + ListView { + anchors.fill: parent + model: visualModel } - - model: folderModel - delegate: fileDelegate } //![0] diff --git a/src/qml/doc/snippets/qml/qtbinding/resources/main.cpp b/src/qml/doc/snippets/delegatemodel/visualdatamodel_rootindex/main.cpp index 844c850366..da1086146c 100644 --- a/src/qml/doc/snippets/qml/qtbinding/resources/main.cpp +++ b/src/qml/doc/snippets/delegatemodel/visualdatamodel_rootindex/main.cpp @@ -3,7 +3,7 @@ ** 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. +** This file is part of the QtQml module of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:BSD$ ** You may use this file under the terms of the BSD license as follows: @@ -37,18 +37,23 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - -#include <QApplication> #include <QQuickView> #include <QQmlContext> +#include <QApplication> +#include <QDirModel> + //![0] -int main(int argc, char *argv[]) +int main(int argc, char ** argv) { QApplication app(argc, argv); QQuickView view; - view.setSource(QUrl("qrc:/main.qml")); + + QDirModel model; + view.rootContext()->setContextProperty("dirModel", &model); + + view.setSource(QUrl::fromLocalFile("view.qml")); view.show(); return app.exec(); diff --git a/src/qml/doc/snippets/qml/xmlrole.qml b/src/qml/doc/snippets/delegatemodel/visualdatamodel_rootindex/view.qml index 0f75135da2..1e8cfade96 100644 --- a/src/qml/doc/snippets/qml/xmlrole.qml +++ b/src/qml/doc/snippets/delegatemodel/visualdatamodel_rootindex/view.qml @@ -37,45 +37,29 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - -import QtQuick 2.0 -import QtQuick.XmlListModel 2.0 - -Rectangle { - width: 300; height: 200 - //![0] -XmlListModel { - id: model -//![0] - source: "xmlrole.xml" - -//![1] - // XmlRole queries will be made on <book> elements - query: "/catalogue/book" - - // query the book title - XmlRole { name: "title"; query: "title/string()" } +import QtQuick 2.0 - // query the book's year - XmlRole { name: "year"; query: "year/number()" } +ListView { + id: view + width: 300 + height: 400 - // query the book's type (the '@' indicates 'type' is an attribute, not an element) - XmlRole { name: "type"; query: "@type/string()" } + model: VisualDataModel { + model: dirModel - // query the book's first listed author (note in XPath the first index is 1, not 0) - XmlRole { name: "first_author"; query: "author[1]/string()" } -} -//![1] + delegate: Rectangle { + width: 200; height: 25 + Text { text: filePath } -ListView { - width: 300; height: 200 - model: model - delegate: Column { - Text { text: title + " (" + type + ")"; font.bold: true } - Text { text: first_author } - Text { text: year } + MouseArea { + anchors.fill: parent + onClicked: { + if (model.hasModelChildren) + view.model.rootIndex = view.model.modelIndex(index) + } + } + } } } - -} +//![0] diff --git a/src/qml/doc/snippets/qml/colors.qml b/src/qml/doc/snippets/qml/colors.qml deleted file mode 100644 index 2885f13c81..0000000000 --- a/src/qml/doc/snippets/qml/colors.qml +++ /dev/null @@ -1,125 +0,0 @@ -/**************************************************************************** -** -** 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names -** of its contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 2.0 - -Rectangle { - width: 160; height: 250 - - Image { - width: 160; height: 200 - source: "pics/checker.svg" - fillMode: Image.Tile - - //! [colors] - Rectangle { - color: "steelblue" - width: 40; height: 40 - } - Rectangle { - color: "transparent" - y: 40; width: 40; height: 40 - } - Rectangle { - color: "#FF0000" - y: 80; width: 40; height: 40 - } - Rectangle { - color: "#800000FF" - y: 120; width: 40; height: 40 - } - Rectangle { - color: "#00000000" // ARGB fully transparent - y: 160 - width: 40; height: 40 - } - //! [colors] - - Rectangle { - x: 40 - width: 120; height: 200 - - Text { - font.pixelSize: 16 - text: "steelblue" - x: 10; height: 40 - verticalAlignment: Text.AlignVCenter - } - Text { - font.pixelSize: 16 - text: "transparent" - x: 10; y: 40; height: 40 - verticalAlignment: Text.AlignVCenter - } - Text { - font.pixelSize: 16 - text: "FF0000" - x: 10; y: 80; height: 40 - verticalAlignment: Text.AlignVCenter - } - Text { - font.pixelSize: 16 - text: "800000FF" - x: 10; y: 120; height: 40 - verticalAlignment: Text.AlignVCenter - } - Text { - font.pixelSize: 16 - text: "00000000" - x: 10; y: 160; height: 40 - verticalAlignment: Text.AlignVCenter - } - } - } - - Image { - y: 210 - width: 40; height: 40 - source: "pics/checker.svg" - fillMode: Image.Tile - } - - Text { - font.pixelSize: 16 - text: "(background)" - x: 50; y: 210; height: 40 - verticalAlignment: Text.AlignVCenter - } -} diff --git a/src/qml/doc/snippets/qml/imports/merged-named-imports.qml b/src/qml/doc/snippets/qml/imports/merged-named-imports.qml index c95d9e66eb..65e2bfd4ce 100644 --- a/src/qml/doc/snippets/qml/imports/merged-named-imports.qml +++ b/src/qml/doc/snippets/qml/imports/merged-named-imports.qml @@ -39,9 +39,16 @@ ****************************************************************************/ //! [imports] -import QtQuick 2.0 as Nokia -import Ovi 1.0 as Nokia -//! [imports] +import QtQuick 2.0 as Project +import QtMultimedia 5.0 as Project + +Project.Rectangle { + width: 100; height: 50 -Item { + Project.Audio { + source: "music.wav" + autoPlay: true + } } +//! [imports] + diff --git a/src/qml/doc/snippets/qml/qtbinding/resources/main.qml b/src/qml/doc/snippets/qml/qtbinding/resources/example.qdoc index 410b3f68d1..c3b85ce15a 100644 --- a/src/qml/doc/snippets/qml/qtbinding/resources/main.qml +++ b/src/qml/doc/snippets/qml/qtbinding/resources/example.qdoc @@ -39,8 +39,13 @@ ****************************************************************************/ //![0] -// main.qml -import QtQuick 2.0 +<!DOCTYPE RCC> +<RCC version="1.0"> -Image { source: "images/background.png" } +<qresource prefix="/"> + <file>main.qml</file> + <file>images/background.png</file> +</qresource> + +</RCC> //![0] diff --git a/src/qml/doc/snippets/qml/qtbinding/resources/example.qrc b/src/qml/doc/snippets/qml/qtbinding/resources/example.qrc deleted file mode 100644 index 5e4941512b..0000000000 --- a/src/qml/doc/snippets/qml/qtbinding/resources/example.qrc +++ /dev/null @@ -1,10 +0,0 @@ -<!DOCTYPE RCC> -<RCC version="1.0"> - -<qresource prefix="/"> - <file>main.qml</file> - <file>images/background.png</file> -</qresource> - -</RCC> - diff --git a/src/qml/doc/snippets/qml/qtbinding/resources/resources.pro b/src/qml/doc/snippets/qml/qtbinding/resources/resources.pro deleted file mode 100644 index 5aee288a6e..0000000000 --- a/src/qml/doc/snippets/qml/qtbinding/resources/resources.pro +++ /dev/null @@ -1,4 +0,0 @@ -QT += qml - -SOURCES += main.cpp -RESOURCES += example.qrc diff --git a/src/qml/doc/src/cppclasses/topic.qdoc b/src/qml/doc/src/cppclasses/topic.qdoc index 8b97048c03..7c21793cfd 100644 --- a/src/qml/doc/src/cppclasses/topic.qdoc +++ b/src/qml/doc/src/cppclasses/topic.qdoc @@ -29,7 +29,7 @@ \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. +The \l{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. The Qt QML module provides more @@ -88,7 +88,7 @@ properties of a QQmlContext, and how to access the context for an object. 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()} +be created in C++ directly, or via the \l{QtQml2::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. @@ -113,4 +113,20 @@ engine. See the \l{QQmlExpression} class documentation for in depth information about how to use QQmlExpression in an application. +\section1 Usage of the Classes within QML Applications + +These pages describe how to create QML applications which interact with the +C++ classes: + +\list +\li \l{qtqml-cppintegration-topic.html}{Integrating QML and C++} + \list + \li \l{qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ Classes to QML} + \li \l{qtqml-cppintegration-definetypes.html}{Defining QML Types from C++} + \li \l{qtqml-cppintegration-contextproperties.html}{Embedding C++ Objects into QML with Context Properties} + \li \l{qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++} + \li \l{qtqml-cppintegration-data.html}{Data Type Conversion Between QML and C++} + \endlist +\endlist + */ diff --git a/src/qml/doc/src/cppintegration/contextproperties.qdoc b/src/qml/doc/src/cppintegration/contextproperties.qdoc index aaac43e470..1c2bced738 100644 --- a/src/qml/doc/src/cppintegration/contextproperties.qdoc +++ b/src/qml/doc/src/cppintegration/contextproperties.qdoc @@ -74,7 +74,7 @@ QML code invokes a method on the object instance: \endtable (Note that date/time values returned from C++ to QML can be formatted through -\l{QML:Qt::formatDateTime}{Qt.formatDateTime()} and associated functions.) +\l{QtQml2::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 type. For example, if \c ApplicationData has a signal named \c diff --git a/src/qml/doc/src/cppintegration/data.qdoc b/src/qml/doc/src/cppintegration/data.qdoc index ba8ad47bab..74a93436f5 100644 --- a/src/qml/doc/src/cppintegration/data.qdoc +++ b/src/qml/doc/src/cppintegration/data.qdoc @@ -119,12 +119,12 @@ when passed from C++ to QML and vice-versa: \li \l enumeration \endtable -(Note that classes provided by the QtGui module, such as QColor, QFont, -QQuaternion and QMatrix4x4, are only available from QML when the \l QtQuick -module is imported.) +\note Classes provided by the \l {Qt GUI} module, such as QColor, QFont, +QQuaternion and QMatrix4x4, are only available from QML when the \l {Qt Quick} +module is included. As a convenience, many of these types can be specified in QML by string values, -or by a related method provided by the \l {QML:Qt} object. For example, the \l +or by a related method provided by the \l {QtQml2::Qt} object. For example, the \l {Image::sourceSize} property is of type \l size (which automatically translates to the QSize type) and can be specified by a string value formatted as "width\c{x}height", or by the Qt.size() function: diff --git a/src/qml/doc/src/cppintegration/definetypes.qdoc b/src/qml/doc/src/cppintegration/definetypes.qdoc index be5f26a865..995fb1bce8 100644 --- a/src/qml/doc/src/cppintegration/definetypes.qdoc +++ b/src/qml/doc/src/cppintegration/definetypes.qdoc @@ -40,7 +40,7 @@ as an instantiable \l{qtqml-typesystem-objecttypes.html}{QML object type} from QML, or enabling a singleton instance of the class to be imported and used from QML. -Additionally, the QtQml module provides mechanisms for implementing QML-specific +Additionally, the \l {Qt QML} module provides mechanisms for implementing QML-specific features such as \e{attached properties} and \e{default properties} in C++. (Note that a number of the important concepts covered in this document are @@ -133,7 +133,7 @@ not be instantiable should not be instantiable from QML \endlist -The QtQml module provides several methods for registering non-instantiable +The \l {Qt QML} module provides several methods for registering non-instantiable types: \list @@ -291,7 +291,7 @@ qmlRegisterRevision<BaseType,1>("MyTypes", 1, 1); \endcode This is useful when deriving from base classes provided by other authors, -e.g. when extending classes from the QtQuick library. +e.g. when extending classes from the Qt Quick module. \section1 Defining QML-Specific Types and Attributes @@ -675,19 +675,19 @@ to be declared for an item without explicitly assigning them to the \l{Item::}{children} property.) -\section2 Defining Visual Items with the QtQuick Module +\section2 Defining Visual Items with the Qt Quick Module -When building user interfaces with the QtQuick module, all QML objects that are +When building user interfaces with the \l {Qt Quick} module, all QML objects that are to be visually rendered must derive from the \l Item type, as it is the base -type for all visual objects in the QtQuick module. This \l Item type is -implemented by the QQuickItem C++ class, which is provided as part of the -QtQuick C++ module. Therefore, this class should be subclassed when it is +type for all visual objects in \l {Qt Quick}. This \l Item type is +implemented by the QQuickItem C++ class, which is provided by the +\l {Qt Quick} module. Therefore, this class should be subclassed when it is necessary to implement a visual type in C++ that can be integrated into a QML-based user interface. See the QQuickItem documentation for more information. Additionally, the \l{Writing QML Extensions with C++} tutorial demonstrates how a QQuickItem-based -visual item can be implemented in C++ and integrated into a QtQuick-based user +visual item can be implemented in C++ and integrated into a Qt Quick-based user interface. @@ -699,7 +699,7 @@ its properties have been set. For example, this may be the case if the initialization is costly, or if the initialization should not be performed until all property values have been initialized. -The QtQml module provides the QQmlParserStatus to be subclass for these +The \l {Qt QML} module provides the QQmlParserStatus to be subclass for these purposes. It defines a number of virtual methods that are invoked invoked at various stages during component instantiation. To receive these notifications, a C++ class should inherit QQmlParserStatus and also notify the Qt meta system diff --git a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc index 3253752e47..d0fb03a03c 100644 --- a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc +++ b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc @@ -30,7 +30,7 @@ \title Writing QML Extensions with C++ \brief tutorial about extending QML with Qt C++ -The QtQml C++ module provides a set of APIs for extending QML through +The \l {Qt QML} module provides a set of APIs for extending QML through C++ extensions. You can write extensions to add your own QML types, extend existing Qt types, or call C/C++ functions that are not accessible from ordinary QML code. @@ -39,17 +39,17 @@ core QML features, including properties, signals and bindings. It also shows how extensions can be deployed through plugins. You can find the source code for this tutorial in \c Qt's -examples/quick/tutorials/extending directory. +examples/qml/tutorials/extending directory. Tutorial chapters: \list 1 -\li \l{quick/tutorials/extending/chapter1-basics}{Creating a New Type} -\li \l{quick/tutorials/extending/chapter2-methods}{Connecting to C++ Methods and Signals} -\li \l{quick/tutorials/extending/chapter3-bindings}{Property Binding} -\li \l{quick/tutorials/extending/chapter4-customPropertyTypes}{Using Custom Property Types} -\li \l{quick/tutorials/extending/chapter5-listproperties}{Using List Property Types} -\li \l{quick/tutorials/extending/chapter6-plugins}{Writing an Extension Plugin} +\li \l{tutorials/extending/chapter1-basics}{Creating a New Type} +\li \l{tutorials/extending/chapter2-methods}{Connecting to C++ Methods and Signals} +\li \l{tutorials/extending/chapter3-bindings}{Property Binding} +\li \l{tutorials/extending/chapter4-customPropertyTypes}{Using Custom Property Types} +\li \l{tutorials/extending/chapter5-listproperties}{Using List Property Types} +\li \l{tutorials/extending/chapter6-plugins}{Writing an Extension Plugin} \li \l{qml-extending-tutorial7.html}{In Summary} \endlist @@ -104,7 +104,7 @@ this new class must: Here is our \c PieChart class, defined in \c piechart.h: -\snippet quick/tutorials/extending/chapter1-basics/piechart.h 0 +\snippet tutorials/extending/chapter1-basics/piechart.h 0 The class inherits from QQuickPaintedItem because we want to override QQuickPaintedItem::paint() in perform drawing operations with the QPainter API. @@ -120,15 +120,15 @@ simply sets and returns the \c m_name and \c m_color values as appropriate, and implements \c paint() to draw a simple pie chart. It also turns off the QGraphicsItem::ItemHasNoContents flag to enable painting: -\snippet quick/tutorials/extending/chapter1-basics/piechart.cpp 0 +\snippet tutorials/extending/chapter1-basics/piechart.cpp 0 \dots 0 -\snippet quick/tutorials/extending/chapter1-basics/piechart.cpp 1 +\snippet tutorials/extending/chapter1-basics/piechart.cpp 1 Now that we have defined the \c PieChart type, we will use it from QML. The \c app.qml file creates a \c PieChart item and display the pie chart's details using a standard QML \l Text item: -\snippet quick/tutorials/extending/chapter1-basics/app.qml 0 +\snippet tutorials/extending/chapter1-basics/app.qml 0 Notice that although the color is specified as a string in QML, it is automatically converted to a QColor object for the PieChart \c color property. Automatic conversions are @@ -142,20 +142,20 @@ you don't register the type, \c app.qml won't be able to create a \c PieChart. Here is the application \c main.cpp: -\snippet quick/tutorials/extending/chapter1-basics/main.cpp 0 +\snippet tutorials/extending/chapter1-basics/main.cpp 0 This call to qmlRegisterType() registers the \c PieChart type as a type called "PieChart", in a type namespace called "Charts", with a version of 1.0. Lastly, we write a \c .pro project file that includes the files and the \c declarative library: -\quotefile quick/tutorials/extending/chapter1-basics/chapter1-basics.pro +\quotefile tutorials/extending/chapter1-basics/chapter1-basics.pro Now we can build and run the application: \image extending-tutorial-chapter1.png -Try it yourself with the code in Qt's \c examples/quick/tutorials/extending/chapter1-basics directory. +Try it yourself with the code in Qt's \c examples/qml/tutorials/extending/chapter1-basics directory. */ @@ -168,20 +168,20 @@ Suppose we want \c PieChart to have a "clearChart()" method that erases the chart and then emits a "chartCleared" signal. Our \c app.qml would be able to call \c clearChart() and receive \c chartCleared() signals like this: -\snippet quick/tutorials/extending/chapter2-methods/app.qml 0 +\snippet tutorials/extending/chapter2-methods/app.qml 0 \image extending-tutorial-chapter2.png To do this, we add a \c clearChart() method and a \c chartCleared() signal to our C++ class: -\snippet quick/tutorials/extending/chapter2-methods/piechart.h 0 +\snippet tutorials/extending/chapter2-methods/piechart.h 0 \dots -\snippet quick/tutorials/extending/chapter2-methods/piechart.h 1 +\snippet tutorials/extending/chapter2-methods/piechart.h 1 \dots -\snippet quick/tutorials/extending/chapter2-methods/piechart.h 2 +\snippet tutorials/extending/chapter2-methods/piechart.h 2 \dots -\snippet quick/tutorials/extending/chapter2-methods/piechart.h 3 +\snippet tutorials/extending/chapter2-methods/piechart.h 3 The use of Q_INVOKABLE makes the \c clearChart() method available to the Qt Meta-Object system, and in turn, to QML. Note that it could have @@ -191,7 +191,7 @@ slots are also callable from QML. Both of these approaches are valid. The \c clearChart() method simply changes the color to Qt::transparent, repaints the chart, then emits the \c chartCleared() signal: -\snippet quick/tutorials/extending/chapter2-methods/piechart.cpp 0 +\snippet tutorials/extending/chapter2-methods/piechart.cpp 0 Now when we run the application and click the window, the pie chart disappears, and the application outputs: @@ -200,7 +200,7 @@ disappears, and the application outputs: The chart has been cleared \endcode -Try out the example yourself with the updated code in Qt's \c examples/quick/tutorials/extending/chapter2-methods directory. +Try out the example yourself with the updated code in Qt's \c examples/qml/tutorials/extending/chapter2-methods directory. */ @@ -216,7 +216,7 @@ other types' values when property values are changed. Let's enable property bindings for the \c color property. That means if we have code like this: -\snippet quick/tutorials/extending/chapter3-bindings/app.qml 0 +\snippet tutorials/extending/chapter3-bindings/app.qml 0 \image extending-tutorial-chapter3.png @@ -231,17 +231,17 @@ It's easy to enable property binding for the \c color property. We add a \l{Qt's Property System}{NOTIFY} feature to its Q_PROPERTY() declaration to indicate that a "colorChanged" signal is emitted whenever the value changes. -\snippet quick/tutorials/extending/chapter3-bindings/piechart.h 0 +\snippet tutorials/extending/chapter3-bindings/piechart.h 0 \dots -\snippet quick/tutorials/extending/chapter3-bindings/piechart.h 1 +\snippet tutorials/extending/chapter3-bindings/piechart.h 1 \dots -\snippet quick/tutorials/extending/chapter3-bindings/piechart.h 2 +\snippet tutorials/extending/chapter3-bindings/piechart.h 2 \dots -\snippet quick/tutorials/extending/chapter3-bindings/piechart.h 3 +\snippet tutorials/extending/chapter3-bindings/piechart.h 3 Then, we emit this signal in \c setPieSlice(): -\snippet quick/tutorials/extending/chapter3-bindings/piechart.cpp 0 +\snippet tutorials/extending/chapter3-bindings/piechart.cpp 0 It's important for \c setColor() to check that the color value has actually changed before emitting \c colorChanged(). This ensures the signal is not emitted unnecessarily and @@ -299,43 +299,43 @@ For example, let's replace the use of the \c property with a type called "PieSlice" that has a \c color property. Instead of assigning a color, we assign an \c PieSlice value which itself contains a \c color: -\snippet quick/tutorials/extending/chapter4-customPropertyTypes/app.qml 0 +\snippet tutorials/extending/chapter4-customPropertyTypes/app.qml 0 Like \c PieChart, this new \c PieSlice type inherits from QQuickPaintedItem and declares its properties with Q_PROPERTY(): -\snippet quick/tutorials/extending/chapter4-customPropertyTypes/pieslice.h 0 +\snippet tutorials/extending/chapter4-customPropertyTypes/pieslice.h 0 To use it in \c PieChart, we modify the \c color property declaration and associated method signatures: -\snippet quick/tutorials/extending/chapter4-customPropertyTypes/piechart.h 0 +\snippet tutorials/extending/chapter4-customPropertyTypes/piechart.h 0 \dots -\snippet quick/tutorials/extending/chapter4-customPropertyTypes/piechart.h 1 +\snippet tutorials/extending/chapter4-customPropertyTypes/piechart.h 1 \dots -\snippet quick/tutorials/extending/chapter4-customPropertyTypes/piechart.h 2 +\snippet tutorials/extending/chapter4-customPropertyTypes/piechart.h 2 \dots -\snippet quick/tutorials/extending/chapter4-customPropertyTypes/piechart.h 3 +\snippet tutorials/extending/chapter4-customPropertyTypes/piechart.h 3 There is one thing to be aware of when implementing \c setPieSlice(). The \c PieSlice is a visual item, so it must be set as a child of the \c PieChart using QQuickItem::setParentItem() so that the \c PieChart knows to paint this child item when its contents are drawn: -\snippet quick/tutorials/extending/chapter4-customPropertyTypes/piechart.cpp 0 +\snippet tutorials/extending/chapter4-customPropertyTypes/piechart.cpp 0 Like the \c PieChart type, the \c PieSlice type has to be registered using qmlRegisterType() to be used from QML. As with \c PieChart, we'll add the type to the "Charts" type namespace, version 1.0: -\snippet quick/tutorials/extending/chapter4-customPropertyTypes/main.cpp 0 +\snippet tutorials/extending/chapter4-customPropertyTypes/main.cpp 0 \dots -\snippet quick/tutorials/extending/chapter4-customPropertyTypes/main.cpp 1 +\snippet tutorials/extending/chapter4-customPropertyTypes/main.cpp 1 \dots -\snippet quick/tutorials/extending/chapter4-customPropertyTypes/main.cpp 2 +\snippet tutorials/extending/chapter4-customPropertyTypes/main.cpp 2 -Try it out with the code in Qt's \c examples/quick/tutorials/extending/chapter4-customPropertyTypes directory. +Try it out with the code in Qt's \c examples/qml/tutorials/extending/chapter4-customPropertyTypes directory. */ @@ -349,7 +349,7 @@ Right now, a \c PieChart can only have one \c PieSlice. Ideally a chart would have multiple slices, with different colors and sizes. To do this, we could have a \c slices property that accepts a list of \c PieSlice items: -\snippet quick/tutorials/extending/chapter5-listproperties/app.qml 0 +\snippet tutorials/extending/chapter5-listproperties/app.qml 0 \image extending-tutorial-chapter5.png @@ -360,11 +360,11 @@ function with a \c slices() function that returns a list of slices, and add an internal \c append_slice() function (discussed below). We also use a QList to store the internal list of slices as \c m_slices: -\snippet quick/tutorials/extending/chapter5-listproperties/piechart.h 0 +\snippet tutorials/extending/chapter5-listproperties/piechart.h 0 \dots -\snippet quick/tutorials/extending/chapter5-listproperties/piechart.h 1 +\snippet tutorials/extending/chapter5-listproperties/piechart.h 1 \dots -\snippet quick/tutorials/extending/chapter5-listproperties/piechart.h 2 +\snippet tutorials/extending/chapter5-listproperties/piechart.h 2 Although the \c slices property does not have an associated \c WRITE function, it is still modifiable because of the way QQmlListProperty works. @@ -373,7 +373,7 @@ return a QQmlListProperty value and indicate that the internal \c PieChart::append_slice() function is to be called whenever a request is made from QML to add items to the list: -\snippet quick/tutorials/extending/chapter5-listproperties/piechart.cpp 0 +\snippet tutorials/extending/chapter5-listproperties/piechart.cpp 0 The \c append_slice() function simply sets the parent item as before, and adds the new item to the \c m_slices list. As you can see, the append function for a @@ -384,7 +384,7 @@ The \c PieSlice class has also been modified to include \c fromAngle and \c angl properties and to draw the slice according to these values. This is a straightforward modification if you have read the previous pages in this tutorial, so the code is not shown here. -The complete code can be seen in the updated \c examples/quick/tutorials/extending/chapter5-listproperties directory. +The complete code can be seen in the updated \c examples/qml/tutorials/extending/chapter5-listproperties directory. */ @@ -407,22 +407,22 @@ and registers our QML types in the inherited \l{QQmlExtensionPlugin::}{registerT Here is the \c ChartsPlugin definition in \c chartsplugin.h: -\snippet quick/tutorials/extending/chapter6-plugins/chartsplugin.h 0 +\snippet tutorials/extending/chapter6-plugins/chartsplugin.h 0 And its implementation in \c chartsplugin.cpp: -\snippet quick/tutorials/extending/chapter6-plugins/chartsplugin.cpp 0 +\snippet tutorials/extending/chapter6-plugins/chartsplugin.cpp 0 Then, we write a \c .pro project file that defines the project as a plugin library and specifies with DESTDIR that library files should be built into a "lib" subdirectory: -\quotefile quick/tutorials/extending/chapter6-plugins/chapter6-plugins.pro +\quotefile tutorials/extending/chapter6-plugins/chapter6-plugins.pro Finally, we add a \l{qtqml-modules-qmldir.html}{qmldir} file that is parsed by the QML engine. In this file, we specify that a plugin named "chapter6-plugin" (the name of the example project) can be found in the "lib" subdirectory: -\quotefile quick/tutorials/extending/chapter6-plugins/Charts/qmldir +\quotefile tutorials/extending/chapter6-plugins/Charts/qmldir Now we have a plugin, and instead of having a main.cpp and an executable, we can build the project and then load the QML file using the \l{Prototyping with qmlscene}{qmlscene tool}, diff --git a/src/qml/doc/src/cppintegration/topic.qdoc b/src/qml/doc/src/cppintegration/topic.qdoc index 48f430c919..4d12ab9d08 100644 --- a/src/qml/doc/src/cppintegration/topic.qdoc +++ b/src/qml/doc/src/cppintegration/topic.qdoc @@ -29,7 +29,7 @@ \title Integrating QML and C++ \brief Description of how to integrate QML and C++ code -QML is designed to be easily extensible through C++ code. The classes in the QtQml C++ module +QML is designed to be easily extensible through C++ code. The classes in the \l {Qt QML} module enables QML objects to be loaded and manipulated from C++, and the nature of QML engine's integration with Qt's \l{Meta Object System}{meta object system} enables C++ functionality to be invoked directly from QML. This allows the development of hybrid applications which are implemented @@ -43,7 +43,7 @@ with QML and JavaScript within \l{qtqml-documents-topic.html}{QML documents}, an C++ \li Use and invoke some C++ functionality from QML (for example, to invoke your application logic, use a data model implemented in C++, or call some functions in a third-party C++ library) -\li Access functionality in the QtQml or QtQuick C++ API (for example, to dynamically generate +\li Access functionality in the \l {Qt QML} or \l {Qt Quick} C++ API (for example, to dynamically generate images using QQuickImageProvider) \li Implement your own \l{qtqml-typesystem-objecttypes.html}{QML object types} from C++ \unicode{0x2014} whether for use within your own specific application, or for distribution to others @@ -71,7 +71,7 @@ methods and signals to be accessed from QML These are the most common methods of accessing C++ functionality from QML code; for more options and details, see the main documentation pages that are described in the sections further below. -Additionally, aside from the ability to access C++ functionality from QML, the Qt QML module also +Additionally, aside from the ability to access C++ functionality from QML, the \l {Qt QML} module also provides ways to do the reverse and manipulate QML objects from C++ code. See \l{qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++} for more details. @@ -104,7 +104,7 @@ registered for other purposes: for example, it could be registered as a \e {Sing single class instance to be imported by QML code, or it could be registered to enable the enumeration values of a non-instantiable class to be accessible from QML. -Additionally, the QtQml module provides mechanisms to define QML types that integrate with QML +Additionally, the \l {Qt QML} module provides mechanisms to define QML types that integrate with QML concepts like attached properties and default properties. For more information on registering and creating custom QML types from C++, see the \l @@ -115,7 +115,7 @@ For more information on registering and creating custom QML types from C++, see C++ objects and values can be embedded directly into the context (or \e scope) of loaded QML objects using \e {context properties} and \e {context objects}. This is achieved through the QQmlContext -class provided by the QtQml module, which exposes data to the context of a QML component, allowing +class provided by the \l {Qt QML} module, which exposes data to the context of a QML component, allowing data to be injected from C++ into QML. See \l{qtqml-cppintegration-contextproperties.html}{Embedding C++ Objects into QML with Context diff --git a/src/qml/doc/src/javascript/date.qdoc b/src/qml/doc/src/javascript/date.qdoc index 9f696930d2..7da24d4092 100644 --- a/src/qml/doc/src/javascript/date.qdoc +++ b/src/qml/doc/src/javascript/date.qdoc @@ -27,7 +27,7 @@ /*! \qmltype Date - \inqmlmodule QtQuick 2 + \inqmlmodule QtQml 2 \brief Provides date functions The QML Date object extends the JS Date object with @@ -223,4 +223,3 @@ } \endcode */ - diff --git a/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc b/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc index 09faa61672..e54404d2fd 100644 --- a/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc +++ b/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc @@ -35,15 +35,15 @@ useful to delay instantiation of objects until necessary, thereby improving application startup time. It also allows visual objects to be dynamically created and added to the scene in reaction to user input or other events. -See the \l {declarative/toys/dynamicscene}{Dynamic Scene example} for a +See the \l {QML Example - Dynamic Scene}{Dynamic Scene example} for a demonstration of the concepts discussed on this page. \section1 Creating Objects Dynamically There are two ways to create objects dynamically from JavaScript. You can -either call \l {QML:Qt::createComponent()}{Qt.createComponent()} to -dynamically create a \l Component object, or use \l{QML:Qt::createQmlObject()} +either call \l {QtQml2::Qt::createComponent()}{Qt.createComponent()} to +dynamically create a \l Component object, or use \l{QtQml2::Qt::createQmlObject()} {Qt.createQmlObject()} to create an object from a string of QML. Creating a component is better if you have an existing component defined in a QML document and you want to dynamically create instances of that component. Otherwise, @@ -54,7 +54,7 @@ generated at runtime. \section2 Creating a Component Dynamically To dynamically load a component defined in a QML file, call the -\l {QML:Qt::createComponent()}{Qt.createComponent()} function in the +\l {QtQml2::Qt::createComponent()}{Qt.createComponent()} function in the \l {QmlGlobalQtObject}{Qt object}. This function takes the URL of the QML file as its only argument and creates a \l Component object from this URL. @@ -66,7 +66,7 @@ can take one or two arguments: \li The first is the parent for the new object. The parent can be a graphical object (i.e. of the \l Item type) or non-graphical object (i.e. of the \l QtObject or C++ QObject type). Only graphical objects with graphical - parent objects will be rendered to the QtQuick visual canvas. If you wish + parent objects will be rendered to the \l {Qt Quick} visual canvas. If you wish to set the parent later you can safely pass \c null to this function. \li The second is optional and is a map of property-value pairs that define initial any property values for the object. Property values specified by @@ -109,11 +109,11 @@ the \c finishCreation() function and call \l {Component::createObject()} Notice in both instances, \l {Component::createObject()}{createObject()} is called with \c appWindow passed as the parent argument, since the dynamically -created object is a visual (QtQuick) object. The created object will become a +created object is a visual (Qt Quick) object. The created object will become a child of the \c appWindow object in \c main.qml, and appear in the scene. When using files with relative paths, the path should -be relative to the file where \l {QML:Qt::createComponent()} +be relative to the file where \l {QtQml2::Qt::createComponent()} {Qt.createComponent()} is executed. To connect signals to (or receive signals from) dynamically created objects, @@ -127,7 +127,7 @@ It is also possible to instantiate components without blocking via the \section2 Creating an Object from a String of QML If the QML is not defined until runtime, you can create a QML object from -a string of QML using the \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} +a string of QML using the \l{QtQml2::Qt::createQmlObject()}{Qt.createQmlObject()} function, as in the following example: \snippet qml/createQmlObject.qml 0 @@ -153,9 +153,9 @@ first, the bindings in the dynamic object will no longer work. The actual creation context depends on how an object is created: \list -\li If \l {QML:Qt::createComponent()}{Qt.createComponent()} is used, the +\li If \l {QtQml2::Qt::createComponent()}{Qt.createComponent()} is used, the creation context is the QQmlContext in which this method is called -\li If \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} is called, the +\li If \l{QtQml2::Qt::createQmlObject()}{Qt.createQmlObject()} is called, the creation context is the context of the parent object passed to this method \li If a \c {Component{}} object is defined and \l {Component::createObject()} {createObject()} or \l {Component::incubateObject()}{incubateObject()} is @@ -221,7 +221,7 @@ Item { This would result in an error, since objects can only be dynamically destroyed if they were dynamically created. -Objects created with \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} +Objects created with \l{QtQml2::Qt::createQmlObject()}{Qt.createQmlObject()} can similarly be destroyed using \c destroy(): \snippet qml/createQmlObject.qml 0 diff --git a/src/qml/doc/src/javascript/hostenvironment.qdoc b/src/qml/doc/src/javascript/hostenvironment.qdoc index a63ef617c0..3bd64ac115 100644 --- a/src/qml/doc/src/javascript/hostenvironment.qdoc +++ b/src/qml/doc/src/javascript/hostenvironment.qdoc @@ -166,6 +166,15 @@ Item { } \endqml +\li The \c with statement is deprecated. Using the \c with statement will issue a warning +at loading time and we plan on removing support for it in Qt 5.2. It is generally considered +a language feature that is not recommended for use due reducing the readability of code and disabling +many optimizations in the engine. It is also forbidden in ECMAScript 5 strict mode. + +\li JavaScript binding expressions are executed in non-strict mode. However we +plan on changing the default for bindings in Qt 5.2 to execute always in +ECMAScript 5 strict mode. + \endlist diff --git a/src/qml/doc/src/javascript/imports.qdoc b/src/qml/doc/src/javascript/imports.qdoc index 800091689c..809b74ed52 100644 --- a/src/qml/doc/src/javascript/imports.qdoc +++ b/src/qml/doc/src/javascript/imports.qdoc @@ -71,13 +71,13 @@ parameters and return values when calling such functions from QML. \section1 Imports Within JavaScript Resources -In QtQuick 2.0, support has been added to allow JavaScript resources to import +In \c {QtQuick 2.0}, support has been added to allow JavaScript resources to import other JavaScript resources and also QML type namespaces using a variation of the standard QML import syntax (where all of the previously described rules and qualifications apply). Due to the ability of a JavaScript resource to import another script or QML -module in this fashion in QtQuick 2.0, some extra semantics are defined: +module in this fashion in \c {QtQuick 2.0}, some extra semantics are defined: \list \li a script with imports will not inherit imports from the QML document which imported it (so accessing Component.errorString will fail, for example) \li a script without imports will inherit imports from the QML document which imported it (so accessing Component.errorString will succeed, for example) @@ -125,14 +125,14 @@ When a JavaScript file is imported, it must be imported with a qualifier. The functions in that file are then accessible from the importing script via the qualifier (that is, as \tt{Qualifier.functionName(params)}). Sometimes it is desirable to have the functions made available in the importing context without -needing to qualify them, and in this circumstance the \l{QML:Qt::include()} +needing to qualify them, and in this circumstance the \l{QtQml2::Qt::include()} {Qt.include()} function may be used to include one JavaScript file from another. This copies all functions from the other file into the current file's namespace, but ignores all pragmas and imports defined in that file. For example, the QML code below left calls \c showCalculations() in \c script.js, which in turn can call \c factorial() in \c factorial.js, as it has included -\c factorial.js using \l {QML:Qt::include()}{Qt.include()}. +\c factorial.js using \l {QtQml2::Qt::include()}{Qt.include()}. \table \row @@ -142,7 +142,7 @@ which in turn can call \c factorial() in \c factorial.js, as it has included \li \snippet qml/integrating-javascript/includejs/factorial.js 0 \endtable -Notice that calling \l {QML:Qt::include()}{Qt.include()} copies all functions +Notice that calling \l {QtQml2::Qt::include()}{Qt.include()} copies all functions from \c factorial.js into the \c MyScript namespace, which means the QML component can also access \c factorial() directly as \c MyScript.factorial(). diff --git a/src/qml/doc/src/javascript/number.qdoc b/src/qml/doc/src/javascript/number.qdoc index 1e7894f3d1..20fe40c86f 100644 --- a/src/qml/doc/src/javascript/number.qdoc +++ b/src/qml/doc/src/javascript/number.qdoc @@ -27,7 +27,7 @@ /*! \qmltype Number - \inqmlmodule QtQuick 2 + \inqmlmodule QtQml 2 \brief The Number object provides represents a number value The QML Number object extends the JS Number object with @@ -102,4 +102,3 @@ d = Number.fromLocaleString(german, "1.234") // d == 1234.0 \endcode */ - diff --git a/src/qml/doc/src/javascript/string.qdoc b/src/qml/doc/src/javascript/string.qdoc index cc3004d93f..ab7d7a4ebe 100644 --- a/src/qml/doc/src/javascript/string.qdoc +++ b/src/qml/doc/src/javascript/string.qdoc @@ -27,7 +27,7 @@ /*! \qmltype String - \inqmlmodule QtQuick 2 + \inqmlmodule QtQml 2 \brief The String object represents a string value The QML String object extends the JS String object with @@ -48,4 +48,3 @@ console.log(message.arg(count)) \endcode */ - diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc index 4a4de0531c..386f9f49df 100644 --- a/src/qml/doc/src/qmlfunctions.qdoc +++ b/src/qml/doc/src/qmlfunctions.qdoc @@ -47,6 +47,20 @@ #include <QtQml> to use this macro. */ +/*! + \fn void qmlClearTypeRegistrations() + \relates QQmlEngine + + Clears all stored type registrations, such as those produced with \l qmlRegisterType. + + Do not call this function while a QQmlEngine exists or behavior will be undefined. + Any existing QQmlEngines must be deleted before calling this function. This function + only affects the application global cache. Delete the QQmlEngine to clear all cached + data relating to that engine. + + #include <QtQml> to use this method. +*/ + /*! \fn int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) @@ -222,7 +236,7 @@ Usage: \code - // first, define the singleton type provider function (callback). + // First, define the singleton type provider function (callback). static QJSValue *example_qjsvalue_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine) { Q_UNUSED(engine) @@ -233,7 +247,8 @@ return example; } - // second, register the singleton type provider with QML by calling this function in an initialization function. + // Second, register the singleton type provider with QML by calling this function in an initialization function. + #include <QtQml> ... qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", example_qjsvalue_singletontype_provider); ... @@ -299,7 +314,7 @@ Usage: \code - // first, define your QObject which provides the functionality. + // First, define your QObject which provides the functionality. class SingletonTypeExample : public QObject { Q_OBJECT @@ -325,7 +340,7 @@ int m_someProperty; }; - // second, define the singleton type provider function (callback). + // Second, define the singleton type provider function (callback). static QObject *example_qobject_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine) { Q_UNUSED(engine) @@ -335,7 +350,8 @@ return example; } - // third, register the singleton type provider with QML by calling this function in an initialization function. + // Third, register the singleton type provider with QML by calling this function in an initialization function. + #include <QtQml> ... qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", example_qobject_singletontype_provider); ... @@ -390,7 +406,7 @@ url must be an absolute URL, i.e. url.isRelative() == false. Normally QML files can be loaded as types directly from other QML files, or using a qmldir file. This function allows - registration of files to types from a C++ module, such as when the type mapping needs to be procedurally determined at startup. + registration of files to types from C++ code, such as when the type mapping needs to be procedurally determined at startup. #include <QtQml> to use this function. diff --git a/src/qml/doc/src/documents/definetypes.qdoc b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc index b9df6a4381..4e1d4a2c86 100644 --- a/src/qml/doc/src/documents/definetypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc @@ -29,7 +29,7 @@ \title Defining Object Types through QML Documents \brief Description of how a QML document is a reusable type definition -One of the core features of QML is that it enables QML object types to be easily defined in a lightweight manner through QML documents to suit the needs of individual QML applications. The standard QtQuick module provides various types like \l Rectangle, \l Text and \l Image for building a QML application; beyond these, you can easily define your own QML types to be reused within your application. This ability to create your own types forms the building blocks of any QML application. +One of the core features of QML is that it enables QML object types to be easily defined in a lightweight manner through QML documents to suit the needs of individual QML applications. The standard \l {Qt Quick} module provides various types like \l Rectangle, \l Text and \l Image for building a QML application; beyond these, you can easily define your own QML types to be reused within your application. This ability to create your own types forms the building blocks of any QML application. \section1 Defining an Object Type with a QML File diff --git a/src/qml/doc/src/documents/networktransparency.qdoc b/src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc index ea46b3381e..ea46b3381e 100644 --- a/src/qml/doc/src/documents/networktransparency.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc diff --git a/src/qml/doc/src/documents/scope.qdoc b/src/qml/doc/src/qmllanguageref/documents/scope.qdoc index 9da77a4905..9da77a4905 100644 --- a/src/qml/doc/src/documents/scope.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/scope.qdoc diff --git a/src/qml/doc/src/documents/structure.qdoc b/src/qml/doc/src/qmllanguageref/documents/structure.qdoc index c8176f7e0f..c8176f7e0f 100644 --- a/src/qml/doc/src/documents/structure.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/structure.qdoc diff --git a/src/qml/doc/src/documents/topic.qdoc b/src/qml/doc/src/qmllanguageref/documents/topic.qdoc index f8a402476c..aed89f6423 100644 --- a/src/qml/doc/src/documents/topic.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/topic.qdoc @@ -91,13 +91,13 @@ separation between UI definition and logic implementation. In the following example, the client developer defines a \c Button type with a document in a file: -\snippet ../src/quick/doc/snippets/qml/qml-extending-types/components/Button.qml 0 +\snippet ../quick/doc/snippets/qml/qml-extending-types/components/Button.qml 0 The \c Button type can then be used in an application: \table \row -\li \snippet ../src/quick/doc/snippets/qml/qml-extending-types/components/application.qml 0 +\li \snippet ../quick/doc/snippets/qml/qml-extending-types/components/application.qml 0 \li \image button-types.png \endtable diff --git a/src/qml/doc/src/modules/cppplugins.qdoc b/src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc index af2a36c903..7ac1d400eb 100644 --- a/src/qml/doc/src/modules/cppplugins.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc @@ -68,7 +68,7 @@ as a new QML type. It provides the current time through \c hour and \c minute properties. - \snippet qml/plugins/plugin.cpp 0 + \snippet plugins/plugin.cpp 0 \dots To make this type available, we create a plugin class named \c QExampleQmlPlugin @@ -78,7 +78,7 @@ definition to register the plugin with the Qt meta object system using a unique identifier for the plugin. - \snippet qml/plugins/plugin.cpp 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 @@ -111,13 +111,13 @@ 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 qml/plugins/imports/TimeExample/qmldir + \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 qml/plugins/plugins.qml 0 + \snippet plugins/plugins.qml 0 The full source code is available in the \l {qml/plugins}{plugins example}. diff --git a/src/qml/doc/src/modules/identifiedmodules.qdoc b/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc index 34d4b864a8..34d4b864a8 100644 --- a/src/qml/doc/src/modules/identifiedmodules.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc diff --git a/src/qml/doc/src/modules/legacymodules.qdoc b/src/qml/doc/src/qmllanguageref/modules/legacymodules.qdoc index 26981334b7..26981334b7 100644 --- a/src/qml/doc/src/modules/legacymodules.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/legacymodules.qdoc diff --git a/src/qml/doc/src/modules/qmldir.qdoc b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc index de3698c533..57d54e27e0 100644 --- a/src/qml/doc/src/modules/qmldir.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc @@ -223,6 +223,11 @@ cannot be used if an earlier version is imported. If the client had imported version 1.0 of the module, they can use the \c MyButton type but \b not the \c MyWindow type. +A version cannot be imported if no types have been explicitly exported for that +version. If a module provides a \c MyButton type in version 1.0 and a +\c MyWindow type in version 1.1, you cannot import version 1.2 or version 2.0 of +that module. + A type can be defined by different files in different versions. In this case, the most closely matching version will be used when imported by clients. For example, if a module had specified the following types via its \c qmldir @@ -363,7 +368,7 @@ Module { // The name of the type containing attached properties // and methods. - attachedType: "QDeclarativeAnimationAttached" + attachedType: "QQuickAnimationAttached" // The list of exports determines how a type can be imported. // Each string has the format "URI/Name version" and matches the diff --git a/src/qml/doc/src/modules/topic.qdoc b/src/qml/doc/src/qmllanguageref/modules/topic.qdoc index 597e7b7ca3..597e7b7ca3 100644 --- a/src/qml/doc/src/modules/topic.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/topic.qdoc diff --git a/src/qml/doc/src/qmllanguageref/qmlreference.qdoc b/src/qml/doc/src/qmllanguageref/qmlreference.qdoc new file mode 100644 index 0000000000..0bc8f90238 --- /dev/null +++ b/src/qml/doc/src/qmllanguageref/qmlreference.qdoc @@ -0,0 +1,113 @@ +/**************************************************************************** +** +** 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 qmlreference.html +\title The QML Reference +\brief A declarative language for application development + +QML is a declarative language for creating highly dynamic applications. With +QML, application building blocks such as UI components are \e declared and +various properties set to define the application behavior. When coupled with +JavaScript, application behavior becomes scriptable. In addition, QML heavily +uses Qt, which allows types and other Qt features to be accessible directly from +QML applications. + +This reference guide describes the features of the QML language. Many of the +QML types in the guide originate from the \l{Qt QML} or \l{Qt Quick} +modules. + +\list + \li \l{qtqml-syntax-basics.html}{QML Syntax Basics} + \list + \li \l{qtqml-syntax-imports.html}{Import Statements} + \li \l{qtqml-syntax-basics.html#object-declarations}{Object Declarations} + \list + \li \l{qtqml-syntax-basics.html#child-objects}{Child Objects} + \endlist + \li \l{qtqml-syntax-basics.html#comments}{Comments} + \endlist + + \li \l{qtqml-syntax-objectattributes.html}{QML Object Attributes} + \list + \li \l{qtqml-syntax-objectattributes.html#the-id-attribute}{The \e id Attribute} + \li \l{qtqml-syntax-objectattributes.html#property-attributes}{Property Attributes} + \li \l{qtqml-syntax-objectattributes.html#signal-attributes}{Signal Attributes} + \li \l{qtqml-syntax-objectattributes.html#method-attributes}{Method Attributes} + \li \l{qtqml-syntax-objectattributes.html#attached-properties-and-attached-signal-handlers}{Attached Properties and Attached Signal Handlers} + \endlist + + \li \l{qtqml-syntax-propertybinding.html}{Property Binding} + + \li \l{qtqml-syntax-signals.html}{Signal and Handler Event System} + + \li \l{qtqml-javascript-topic.html}{Integrating QML and JavaScript} + \list + \li \l{qtqml-javascript-expressions.html}{Using JavaScript Expressions with QML} + \li \l{qtqml-javascript-dynamicobjectcreation.html}{Dynamic QML Object Creation from JavaScript} + \li \l{qtqml-javascript-resources.html}{Defining JavaScript Resources In QML} + \li \l{qtqml-javascript-imports.html}{Importing JavaScript Resources In QML} + \li \l{qtqml-javascript-hostenvironment.html}{JavaScript Host Environment} + \endlist + + \li \l{qtqml-typesystem-topic.html}{The QML Type System} + \list + \li \l{qtqml-typesystem-basictypes.html}{Basic Types} + \li \l{qtqml-typesystem-topic.html#javascript-types}{JavaScript Types} + \li \l{qtqml-typesystem-objecttypes.html}{QML Object Types} + \list + \li \l{qtqml-documents-definetypes.html}{Defining Object Types from QML} + \li \l{qtqml-cppintegration-definetypes.html}{Defining Object Types from C++} + \endlist + \endlist + + \li \l{qtqml-modules-topic.html}{QML Modules} + \list + \li \l{qtqml-modules-qmldir.html}{Specifying A QML Module} + \li \l{qtqml-modules-topic.html#supported-qml-module-types}{Supported QML Module Types} + \list + \li \l{qtqml-modules-identifiedmodules.html}{Identified Modules} + \li \l{qtqml-modules-legacymodules.html}{Legacy Modules} + \endlist + \li \l{qtqml-modules-cppplugins.html}{Providing Types and Functionality in a C++ Plugin} + \endlist + + \li \l{qtqml-documents-topic.html}{QML Documents} + \list + \li \l{qtqml-documents-structure.html}{Structure of a QML Document} + \li \l{Syntax of the QML Language} + \li \l{qtqml-documents-definetypes.html}{Defining Object Types through QML Documents} + \list + \li \l{qtqml-documents-definetypes.html#defining-an-object-type-with-a-qml-file}{Defining an Object Type with a QML File} + \li \l{qtqml-documents-definetypes.html#accessible-attributes-of-custom-types}{Accessible Attributes of Custom Types} + \endlist + \li \l{qtqml-documents-networktransparency.html}{Resource Loading and Network Transparency} + \li \l{qtqml-documents-scope.html}{Scope and Naming Resolution} + \endlist +\endlist + +*/ diff --git a/src/qml/doc/src/syntax/basics.qdoc b/src/qml/doc/src/qmllanguageref/syntax/basics.qdoc index d20f66d80a..cdfab3cd3f 100644 --- a/src/qml/doc/src/syntax/basics.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/basics.qdoc @@ -89,9 +89,9 @@ Rectangle { } \endqml -This declares an object of type \l Rectangle, followed by a set of curly braces that encompasses the attributes defined for that object. The \l Rectangle type is a type made available by the \l QtQuick module, and the attributes defined in this case are the values of the rectangle's \c width, \c height and \c color properties. (These are properties made available by the \l Rectangle type, as described in the \l Rectangle documentation.) +This declares an object of type \l Rectangle, followed by a set of curly braces that encompasses the attributes defined for that object. The \l Rectangle type is a type made available by the \c QtQuick module, and the attributes defined in this case are the values of the rectangle's \c width, \c height and \c color properties. (These are properties made available by the \l Rectangle type, as described in the \l Rectangle documentation.) -The above object can be loaded by the engine if it is part of a \l{qtqml-documents-topic.html}{QML document}. That is, if the source code is complemented with \e import statement that imports the QtQuick module (to make the \l Rectangle type available), as below: +The above object can be loaded by the engine if it is part of a \l{qtqml-documents-topic.html}{QML document}. That is, if the source code is complemented with \e import statement that imports the \c QtQuick module (to make the \l Rectangle type available), as below: \qml import QtQuick 2.0 @@ -103,7 +103,7 @@ Rectangle { } \endqml -When placed into a \c .qml file and loaded by the QML engine, the above code creates a \l Rectangle object using the \l Rectangle type supplied by the QtQuick module: +When placed into a \c .qml file and loaded by the QML engine, the above code creates a \l Rectangle object using the \l Rectangle type supplied by the \c QtQuick module: \image qtqml-syntax-basics-object-declaration.png @@ -140,7 +140,7 @@ Rectangle { When this code is loaded by the engine, it creates an object tree with a \l Rectangle object at the root; this object has a \l Gradient child object, which in turn has two \l GradientStop children. Note, however, that this is a parent-child relationship in the context of the QML object tree, not -in the context of the visual scene. The concept of a parent-child relationship in a visual scene is provided by the \l Item type from the \l QtQuick module, which is the base type for most QML types, as most QML objects are intended to be visually rendered. For example, \l Rectangle and \l Text are both \l {Item}-based types, and below, a \l Text object has been declared as a visual child of a \l Rectangle object: +in the context of the visual scene. The concept of a parent-child relationship in a visual scene is provided by the \l Item type from the \c QtQuick module, which is the base type for most QML types, as most QML objects are intended to be visually rendered. For example, \l Rectangle and \l Text are both \l {Item}-based types, and below, a \l Text object has been declared as a visual child of a \l Rectangle object: \qml import QtQuick 2.0 diff --git a/src/qml/doc/src/syntax/directoryimports.qdoc b/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc index 7a6fb58c27..7a6fb58c27 100644 --- a/src/qml/doc/src/syntax/directoryimports.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc diff --git a/src/qml/doc/src/syntax/imports.qdoc b/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc index eda7dbf006..1496a1e5c9 100644 --- a/src/qml/doc/src/syntax/imports.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc @@ -144,7 +144,7 @@ the types should be imported into a particular document-local namespace. If a namespace is specified, then any references to the types made available by the import must be prefixed by the local namespace qualifier. -Below, the QtQuick module is imported into the namespace "CoreItems". Now, any +Below, the \c 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: @@ -178,7 +178,7 @@ CoreItems.Rectangle { width: 100; height: 100 MyModule.Text { text: "Hello from my custom text item!" } - CoreItems.Text { text: "Hello from QtQuick!" } + CoreItems.Text { text: "Hello from Qt Quick!" } } \endqml diff --git a/src/qml/doc/src/syntax/objectattributes.qdoc b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc index f336d14b14..f336d14b14 100644 --- a/src/qml/doc/src/syntax/objectattributes.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc diff --git a/src/qml/doc/src/syntax/propertybinding.qdoc b/src/qml/doc/src/qmllanguageref/syntax/propertybinding.qdoc index 6803901efd..6803901efd 100644 --- a/src/qml/doc/src/syntax/propertybinding.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/propertybinding.qdoc diff --git a/src/qml/doc/src/syntax/signals.qdoc b/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc index 6c90ddcf0a..6344d16caa 100644 --- a/src/qml/doc/src/syntax/signals.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc @@ -27,7 +27,6 @@ /*! \page qtqml-syntax-signals.html -\ingroup qml-features \title Signal and Handler Event System \brief the event sytem in QML @@ -115,7 +114,7 @@ Even though the \l MouseArea documentation does not document a signal handler na \section2 Using the Connections Type -In some cases it may be desirable to access a signal outside of the object that emits it. For these purposes, the QtQuick module provides the \l Connections type for connecting to signals of arbitrary objects. A \l Connections object can receive any signal from its specified \l {Connections::target}{target}. +In some cases it may be desirable to access a signal outside of the object that emits it. For these purposes, the \c QtQuick module provides the \l Connections type for connecting to signals of arbitrary objects. A \l Connections object can receive any signal from its specified \l {Connections::target}{target}. For example, the \c onClicked handler in the earlier example could have been received by the root \l Rectangle instead, by placing the \c onClicked handler in a \l Connections object that has its \l {Connections::target}{target} set to the \l MouseArea: @@ -294,4 +293,3 @@ output: */ - diff --git a/src/qml/doc/src/typesystem/basictypes.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc index 6f468d42bc..7d2d662e4e 100644 --- a/src/qml/doc/src/typesystem/basictypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc @@ -67,7 +67,7 @@ The basic types supported natively in the QML language are listed below: \section2 Basic Types Provided By QML Modules QML modules may extend the QML language with more basic types. -For example, the basic types provided by the QtQuick module are listed below: +For example, the basic types provided by the \c QtQuick module are listed below: \annotatedlist qtquickbasictypes Currently only QML modules which are provided by Qt may provide their @@ -241,7 +241,7 @@ property is only invoked when the property is reassigned to a different object v \brief a resource locator. The \c url type refers to a resource locator (like a file name, for example). It can be either - absolute, e.g. "http://qt.nokia.com", or relative, e.g. "pics/logo.png". A relative URL is + absolute, e.g. "http://qt-project.org", or relative, e.g. "pics/logo.png". A relative URL is resolved relative to the URL of the containing component. For example, the following assigns a valid URL to the \l {Image::source} diff --git a/src/qml/doc/src/typesystem/objecttypes.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/objecttypes.qdoc index 9209ebe68e..9209ebe68e 100644 --- a/src/qml/doc/src/typesystem/objecttypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/objecttypes.qdoc diff --git a/src/qml/doc/src/typesystem/topic.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/topic.qdoc index 76e28f7ef1..76e28f7ef1 100644 --- a/src/qml/doc/src/typesystem/topic.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/topic.qdoc diff --git a/src/qml/doc/src/qmltypereference.qdoc b/src/qml/doc/src/qmltypereference.qdoc index 799945fa37..3def3209cc 100644 --- a/src/qml/doc/src/qmltypereference.qdoc +++ b/src/qml/doc/src/qmltypereference.qdoc @@ -24,20 +24,18 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ + /*! \qmlmodule QtQml 2 \title Qt QML QML Types \ingroup qmlmodules \brief List of QML types provided by the Qt QML module -The \c QtQml module provides the definition and implementation of various +The \l{Qt QML} module provides the definition and implementation of various convenience types which can be used with the QML language, including some elementary QML types which can provide the basis for further extensions to the -QML language. - -The \c QtQml module provides the \c QtObject and \c Component object types -which may be used in QML documents. These types are non-visual and provide -building-blocks for extensions to QML. +QML language. The \l QtObject and \l Component object types are non-visual and +provide building-blocks for extensions to QML. \section1 Importing QtQml @@ -53,15 +51,20 @@ import QtQml 2.0 \endqml Most clients will never need to use the \c QtQml import, as all of the types -and functionality provided by the \c QtQml namespace are also provided by the -\c QtQuick namespace which may be imported as follows: +are also provided by the \c QtQuick namespace which may be imported as +follows: \qml import QtQuick 2.0 \endqml -See the \l{Qt Quick} module documentation for more information about the -\c QtQuick namespace and what it provides to QML application developers. +See the \l{Qt Quick} module documentation for more information about the \c +QtQuick namespace and what it provides to QML application developers. + +The QML types for creating lists and models, such as \l ListModel and \l +ListElement, are moved to a submodule, \c QtQml.Models. The \l{Qt QML Models QML +Types}{Qt QML Models} page has more information. + The documentation for the types below applies equally to the types of the same name provided by the \l{Qt Quick} module, as they are in fact identical. @@ -78,82 +81,6 @@ provided: The following \l{qtqml-typesystem-objecttypes.html}{QML object types} are provided: -\section2 QtObject - -The \c QtObject type provides a basic instantiable object which can be used in -QML applications. It is non-visual, but may have properties, methods, signals -and signal handlers. - -For example, the following QtObject has several properties, one of which has -been assigned a \l{Property Binding} -{binding}, and a \l{Signal and Handler Event System}{signal handler} for -the default change signal which exists for one of its properties: - -\code - import QtQuick 2.0 - - QtObject { - property int a: 15 - property int b: a + 22 - property int changeCount: 0 - - onAChanged: { - changeCount += 1; - } - } -\endcode - -\section2 Component - -The \c Component type provides a basic re-usable component which allows -instances of another type to be instantiated on-demand. It may be given an -\c id and it has a default property which is the object type to instantiate, -but no other properties may be added to it. - -For example, the following QtObject has two different \l Component -properties, and it uses those components to dynamically construct objects at -run-time: - -\code - import QtQuick 2.0 - - QtObject { - id: root - property bool which: true - - property Component a: Component { - id: firstComponent - QtObject { - property int answer: 42 - function activate() { - console.log("The answer is: " + answer); - } - } - } - - property Component b: Component { - id: secondComponent - QtObject { - property string message: "Hello, World!" - function activate() { - console.log(message); - } - } - } - - function activateDynamicObject() { - var o = {}; - if (which) { - which = false; - o = a.createObject(null); // no parent - } else { - which = true; - o = b.createObject(null); // no parent - } - o.activate(); - } - } -\endcode */ /*! @@ -171,7 +98,7 @@ MyDatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" } \endqml To read a date value returned from a C++ extension class, use -\l{QML:Qt::formatDate()}{Qt.formatDate()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}. +\l{QtQml2::Qt::formatDate()}{Qt.formatDate()} and \l{QtQml2::Qt::formatDateTime()}{Qt.formatDateTime()}. When integrating with C++, note that any QDate value \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically @@ -202,7 +129,7 @@ MyTimePicker { time: "14:22:15" } \endqml To read a time value returned from a C++ extension class, use -\l{QML:Qt::formatTime()}{Qt.formatTime()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}. +\l{QtQml2::Qt::formatTime()}{Qt.formatTime()} and \l{QtQml2::Qt::formatDateTime()}{Qt.formatDateTime()}. Note that when converting historical times to and from javascript that QDateTime and the JS Date object have different methods of calculating historical daylight savings time application. This can lead to variations of one hour @@ -231,7 +158,7 @@ To create a \c point value, specify it as a "x,y" string: CustomObject { myPointProperty: "0,20" } \endqml -Or use the \l{QML:Qt::point()}{Qt.point()} function: +Or use the \l{QtQml2::Qt::point()}{Qt.point()} function: \qml CustomObject { myPointProperty: Qt.point(0, 20) } @@ -269,7 +196,7 @@ To create a \c size value, specify it as a "width x height" string: Image { sourceSize: "150x50" } \endqml -Or use the \l{QML:Qt::size()}{Qt.size()} function: +Or use the \l{QtQml2::Qt::size()}{Qt.size()} function: \qml Image { sourceSize: Qt.size(150, 50) } @@ -309,7 +236,7 @@ To create a \c rect value, specify it as a "x, y, width x height" string: CustomObject { myRectProperty: "50,50,100x100" } \endqml -Or use the \l{QML:Qt::rect()}{Qt.rect()} function: +Or use the \l{QtQml2::Qt::rect()}{Qt.rect()} function: \qml CustomObject { myRectProperty: Qt.rect(50, 50, 100, 100) } @@ -322,5 +249,3 @@ is automatically converted into a QRectF value. \sa{QML Basic Types} */ - - diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc index 05a33f351a..26e4867bbc 100644 --- a/src/qml/doc/src/qtqml.qdoc +++ b/src/qml/doc/src/qtqml.qdoc @@ -30,159 +30,116 @@ \title Qt QML \brief The Qt QML module defines and implements the QML language -\section1 Overview of the Qt QML Module - -The Qt QML module provides a framework for developing applications and -libraries with the QML language. It defines and implements the language -and engine infrastructure, and provides an API to enable application +The Qt QML module provides a framework for developing applications and libraries +with the \l{QML Application Developer Resources}{QML language}. It defines and implements the +language and engine infrastructure, and provides an API to enable application developers to extend the QML language with custom types and integrate QML code -with JavaScript and C++. - -The Qt QML module provides both the \c QtQml QML module, which supplies -\l{Qt QML QML Types}{a set of core QML types} for creating QML -applications, and the \c QtQml C++ module, which supplies \l{Qt QML C++ Classes}{a set of C++ -APIs} for extending QML applications with custom types and integrating C++ -implementations with QML applications. +with JavaScript and C++. The Qt QML module provides both a \l{Qt QML QML Types} +{QML API} and a \l{Qt QML C++ Classes}{C++ API}. -Note that the Qt QML module provides only the language and infrastructure -for the QML, and does not provide a visual canvas or rendering engine for -creating user interfaces. These are provided instead by the -\l{Qt Quick} module, which provides many visual components, -model/view support, an animation framework and much more for building user -interfaces with QML. +Note that while the Qt QML module provides the language and infrastructure +for QML applications, the \l{Qt Quick} module provides many visual components, +model-view support, an animation framework, and much more for building user +interfaces. For those new to QML and Qt Quick, please see \l{qtquick-applicationdevelopers.html}{QML Application Developer Resources} for an introduction to writing QML applications. +\section1 Getting Started -\section1 Qt QML Module Documentation +To include the definitions of the module's classes, use the +following directive: -\list - \li \l{qtqml-cppclasses-topic.html}{Important C++ Classes} - \list - \li \l{QQmlEngine} - \li \l{QQmlContext} - \li \l{QQmlComponent} - \li \l{QQmlExpression} - \endlist - - \li \l{qtqml-typesystem-topic.html}{The QML Type System} - \list - \li \l{qtqml-typesystem-basictypes.html}{Basic Types} - \li \l{qtqml-typesystem-topic.html#javascript-types}{JavaScript Types} - \li \l{qtqml-typesystem-objecttypes.html}{QML Object Types} - \list - \li \l{qtqml-documents-definetypes.html}{Defining Object Types from QML} - \li \l{qtqml-cppintegration-definetypes.html}{Defining Object Types from C++} - \endlist - \endlist - - \li \l{qtqml-modules-topic.html}{QML Modules} - \list - \li \l{qtqml-modules-qmldir.html}{Specifying A QML Module} - \li \l{qtqml-modules-topic.html#supported-qml-module-types}{Supported QML Module Types} - \list - \li \l{qtqml-modules-identifiedmodules.html}{Identified Modules} - \li \l{qtqml-modules-legacymodules.html}{Legacy Modules} - \endlist - \li \l{qtqml-modules-cppplugins.html}{Providing Types and Functionality in a C++ Plugin} - \endlist - - \li \l{qtqml-documents-topic.html}{QML Documents} - \list - \li \l{qtqml-documents-structure.html}{Structure of a QML Document} - \li \l{Syntax of the QML Language} - \li \l{qtqml-documents-definetypes.html}{Defining Object Types through QML Documents} - \list - \li \l{qtqml-documents-definetypes.html#defining-an-object-type-with-a-qml-file}{Defining an Object Type with a QML File} - \li \l{qtqml-documents-definetypes.html#accessible-attributes-of-custom-types}{Accessible Attributes of Custom Types} - \endlist - \li \l{qtqml-documents-networktransparency.html}{Resource Loading and Network Transparency} - \li \l{qtqml-documents-scope.html}{Scope and Naming Resolution} - \endlist - - \li \l{qtqml-typereference-topic.html}{QML Types Provided by the Qt QML Module} - \list - \li \l{qtqml-typereference-topic.html#importing-qtqml}{Importing \c QtQml} - \li \l{qtqml-typereference-topic.html#basic-types}{Basic Types} - \li \l{qtqml-typereference-topic.html#object-types}{Object Types} - \list - \li \l{qtqml-typereference-topic.html#qtobject}{QtObject} - \li \l{qtqml-typereference-topic.html#component}{Component} - \endlist - \endlist - - \li \l{qtqml-javascript-topic.html}{Integrating QML and JavaScript} - \list - \li \l{qtqml-javascript-expressions.html}{Using JavaScript Expressions with QML} - \li \l{qtqml-javascript-dynamicobjectcreation.html}{Dynamic QML Object Creation from JavaScript} - \li \l{qtqml-javascript-resources.html}{Defining JavaScript Resources In QML} - \li \l{qtqml-javascript-imports.html}{Importing JavaScript Resources In QML} - \li \l{qtqml-javascript-hostenvironment.html}{JavaScript Host Environment} - \list - \li \l{qtqml-javascript-hostenvironment.html#common-base}{Common Base} - \li \l{qtqml-javascript-hostenvironment.html#qml-global-object}{QML Global Object} - \li \l{qtqml-javascript-hostenvironment.html#javascript-objects-and-functions}{JavaScript Objects and Functions} - \li \l{qtqml-javascript-hostenvironment.html#javascript-environment-restrictions}{JavaScript Environment Restrictions} - \endlist - \endlist - - \li \l{qtqml-cppintegration-topic.html}{Integrating QML and C++} - \list - \li \l{qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ Classes to QML} - \li \l{qtqml-cppintegration-definetypes.html}{Defining QML Types from C++} - \li \l{qtqml-cppintegration-contextproperties.html}{Embedding C++ Objects into QML with Context Properties} - \li \l{qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++} - \li \l{qtqml-cppintegration-data.html}{Data Type Conversion Between QML and C++} - \endlist +\code +#include <QtQml> +\endcode + +The QML types in Qt QML are available through the \c QtQML import. To use the +types, add the following import statement to your .qml file: +\code +import QtQml 2.0 +\endcode + + +To link against the module, add this line to your \l qmake \c +.pro file: +\code +QT += qml +\endcode + +\section1 QML and QML Types + +The Qt QML module contains the QML framework and important QML types used in +applications. The constructs of QML are described in the \l{The QML Reference}. + +In addition to the \l{QML Basic Types}, the module comes with +various QML object types: +\list +\li \l Component +\li \l QtObject +\li \l Binding +\li \l Connections +\li \l Timer \endlist +\section2 Lists and Models -\section1 Syntax of the QML Language +New in Qt 5.1, the model types are moved to a submodule, \c QtQml.Models. The +\l{Qt QML Models QML Types}{Qt QML Models} page has more information. \list - \li \l{qtqml-syntax-basics.html}{QML Syntax Basics} - \list - \li \l{qtqml-syntax-imports.html}{Import Statements} - \li \l{qtqml-syntax-basics.html#object-declarations}{Object Declarations} - \list - \li \l{qtqml-syntax-basics.html#child-objects}{Child Objects} - \endlist - \li \l{qtqml-syntax-basics.html#comments}{Comments} - \endlist - - \li \l{qtqml-syntax-objectattributes.html}{QML Object Attributes} - \list - \li \l{qtqml-syntax-objectattributes.html#the-id-attribute}{The \e id Attribute} - \li \l{qtqml-syntax-objectattributes.html#property-attributes}{Property Attributes} - \li \l{qtqml-syntax-objectattributes.html#signal-attributes}{Signal Attributes} - \li \l{qtqml-syntax-objectattributes.html#method-attributes}{Method Attributes} - \li \l{qtqml-syntax-objectattributes.html#attached-properties-and-attached-signal-handlers}{Attached Properties and Attached Signal Handlers} - \endlist - - \li \l{qtqml-syntax-propertybinding.html}{Property Binding} - \li \l{qtqml-syntax-signals.html}{Signal and Handler Event System} +\li \l DelegateModel +\li \l DelegateModelGroup +\li \l ListElement +\li \l ListModel +\li \l ObjectModel \endlist -\section1 Reference Documentation +\section1 JavaScript Environment for QML Applications + +JavaScript expressions allow QML code to contain application logic. Qt QML +provides the framework for running JavaScript expressions in QML and from C++. + +These sections are from \l{The QML Reference}. +\l{qtqml-javascript-topic.html}{Integrating QML and JavaScript} + \list + \li \l{qtqml-javascript-expressions.html}{Using JavaScript Expressions with QML} + \li \l{qtqml-javascript-dynamicobjectcreation.html}{Dynamic QML Object Creation from JavaScript} + \li \l{qtqml-javascript-resources.html}{Defining JavaScript Resources In QML} + \li \l{qtqml-javascript-imports.html}{Importing JavaScript Resources In QML} + \li \l{qtqml-javascript-hostenvironment.html}{JavaScript Host Environment} + \endlist + +\section1 Integrating QML with C++ Applications + +The module also provides the framework for running QML applications. +The QML framework allows QML code to contain JavaScript expressions and for +the QML code to interact with C++ code. -Additional Qt QML information: \list -\li \l{Qt QML C++ Classes} - the C++ API provided by the - Qt QML module -\li \l{Qt QML Release Notes} - list of changes and - additions in the Qt QML module +\li \l{Important C++ Classes Provided By The Qt QML Module} +\li \l{Integrating QML and C++} \endlist +\section1 Guides and Other Information + Further information for writing QML applications: \list +\li \l{The QML Reference} \li \l{QML Application Developer Resources} - essential information for application development with QML and Qt Quick -\li \l{Qt Quick} - documentation for the Qt Quick module, which provides a - visual canvas, an animation framework, model/view components and more for - building fluid user interfaces and applications with QML +\li \l{Qt Quick} - a module which provides a set of QML types and C++ classes + for building user interfaces and applications with QML +\li \l{Qt QML Release Notes} - list of changes and + additions in the Qt QML module +\endlist + +\section2 Reference +\list +\li \l{Qt QML C++ Classes}{C++ Classes} +\li \l{Qt QML QML Types}{QML Types} \endlist -*/ +*/ diff --git a/src/qml/doc/src/whatsnew.qdoc b/src/qml/doc/src/whatsnew.qdoc index 361f6e61ee..eece3bcaab 100644 --- a/src/qml/doc/src/whatsnew.qdoc +++ b/src/qml/doc/src/whatsnew.qdoc @@ -28,16 +28,37 @@ /*! \title Qt QML Release Notes \page qtqml-releasenotes.html -\inqmlmodule QtQuick 2.0 -\section1 Qt QML in Qt 5 +\section1 Qt QML in Qt 5.1 + +Qt 5.1 introduces several bug fixes and new functionalities to Qt QML. This is +a summary of the new changes: +\list +\li New QQmlApplicationEngine convenience class for QML applications. +\li New Instantiatior type for generic, dynamic object creation. +\li New properties for \l Qt.application: arguments, name, and version. +\endlist + +\section2 New Submodule + +The \l{Qt QML Models QML Types}{Qt QML Models} is a new submodule in Qt 5.1 and +provides several QML types for handling data with models and lists. These types +replace types such as \l VisualItem, \l VisualDataModel, and \l VisualDataGroup. + +\list +\li \l{Qt QML Models QML Types}{Models} +\endlist + +The \l{What's New in Qt 5.1} has more information about the Qt 5.1 release. + +\section1 Qt QML in Qt 5.0 The \l{Qt QML} module is new in Qt 5.0. It provides the QML engine and implements the QML language supporting infrastructure. -(Prior to Qt 5, this functionality was provided by the QtDeclarative module, which -has now been replaced by the new QtQml and QtQuick C++ modules. See the -\l {Porting QML Applications to Qt 5} for more information.) +(Prior to Qt 5, this functionality was provided by the \l {Qt Quick 1}{QtDeclarative} module, which +has now been replaced by the new \l {Qt QML} and \l {Qt Quick} modules. See the +\l {Porting QML Applications to Qt 5} page for more information.) \section2 QML Engine @@ -73,11 +94,11 @@ has now been replaced by the new QtQml and QtQuick C++ modules. See the \list \li QML now supports defining properties of value type basic types within QML documents. Supported types include QSizeF, QPointF and QRectF as \c size, \c point and \c rect respectively. - \li QColor is now a value type provided by the QtQuick module. The red, green, blue and alpha channels + \li QColor is now a value type provided by the \c QtQuick module. The red, green, blue and alpha channels of a \l color property can be accessed via \c r, \c g, \c b and \c a properties. \li Factory functions for various value types have been added to the \c Qt object exposed to QML. - Some of those functions require the QtQuick module to be imported in order to return valid values. - See the QtQuick 2.0 release notes for more information about these functions. + Some of those functions require the \c QtQuick module to be imported in order to return valid values. + See the \l {Qt Quick Release Notes} for more information about these functions. \endlist \li Support for sequence types QList<int>, QList<qreal>, QList<bool>, QList<QUrl>, QList<QString> and QStringList has been improved. QObjects can define Q_PROPERTYs of @@ -95,7 +116,7 @@ has now been replaced by the new QtQml and QtQuick C++ modules. See the \list \li QQmlExpression can now be constructed directly (and more efficiently) from a QQmlScriptString. -\li The \l {QML:Qt} object now provides a \l{QML:Qt::inputMethod} property to access the active +\li The \l {QtQml2::Qt}{Qt} global object now provides an \l{QtQml2::Qt::inputMethod}{inputMethod} property to access the active text input method for an application. \endlist |