diff options
Diffstat (limited to 'src/qml/doc/src/cppintegration/extending-tutorial.qdoc')
| -rw-r--r-- | src/qml/doc/src/cppintegration/extending-tutorial.qdoc | 73 |
1 files changed, 33 insertions, 40 deletions
diff --git a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc index 66c133980d..156ad47089 100644 --- a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc +++ b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\example tutorials/extending-qml +\page qtqml-tutorials-extending-qml-example.html \title Writing QML Extensions with C++ \brief Tutorial about extending QML with Qt C++. -The \l {Qt QML} 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. @@ -20,18 +20,19 @@ particular, you may be interested in the sub-topics \l{qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ Classes to QML} and \l {qtqml-cppintegration-definetypes.html}{Defining QML Types from C++}. -\section1 Running the Tutorial Examples +\section1 Opening the Tutorial Sources -The code in this tutorial is available as an example project with subprojects -associated with each tutorial chapter. In \l{Qt Creator Manual}{Qt Creator}, open -the \uicontrol Welcome mode and select the tutorial from \uicontrol Examples. In -\uicontrol Edit mode, expand the \e extending-qml project, right-click on the -subproject (chapter) you want to run and select \uicontrol Run. +The code in this tutorial is available as part of the Qt sources. +If you installed Qt with the \QOI, you can +find the sources in the Qt installation directory under +Examples/Qt-\QtVersion/qml/tutorials/extending-qml/. -\section1 Creating Tutorial Project +\section1 Creating Project from Scratch -We create a new project using the \e {Qt Quick Application} template in Qt Creator, -as instructed in \l {Qt Creator: Creating Qt Quick Projects}. +Alternatively, you can follow the tutorial by creating the sources from scratch: +For each chapter, create a new project using the \e {Qt Quick Application} template +in Qt Creator, as instructed in \l {Qt Creator: Creating Qt Quick Projects}. +Then follow along by adapting and extending the generated skeleton code. \section1 Chapter 1: Creating a New Type \c extending-qml/chapter1-basics @@ -54,7 +55,7 @@ a version of 1.0. We want this \c PieChart type to be usable from QML like this: \qml - import Charts 1.0 + import Charts PieChart { width: 100; height: 100 @@ -89,7 +90,7 @@ operations with the QPainter API, we can just subclass QQuickItem. The \c PieChart class defines the two properties, \c name and \c color, with the Q_PROPERTY macro, and overrides QQuickPaintedItem::paint(). The \c PieChart class is registered using the QML_ELEMENT macro, to allow it to be used from -QML. If you don't register the class, \c app.qml won't be able to create a +QML. If you don't register the class, \c App.qml won't be able to create a \c PieChart. \section2 qmake Setup @@ -111,8 +112,7 @@ Similarly, for the registration to take effect when using CMake, use the The class implementation in \c piechart.cpp 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: +draw a simple pie chart: \snippet tutorials/extending-qml/chapter1-basics/piechart.cpp 0 \dots 0 @@ -121,10 +121,10 @@ flag to enable painting: \section2 QML Usage 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 displays the pie chart's details +App.qml file creates a \c PieChart item and displays the pie chart's details using a standard QML \l Text item: -\snippet tutorials/extending-qml/chapter1-basics/app.qml 0 +\snippet tutorials/extending-qml/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 @@ -132,7 +132,7 @@ provided for various other \l {QML Value Types}{value types}. For example, a str like "640x480" can be automatically converted to a QSize value. We'll also create a C++ application that uses a QQuickView to run and -display \c app.qml. +display \c App.qml. Here is the application \c main.cpp: @@ -162,18 +162,14 @@ Now we can build and run the application: cannot update the binding if the \c name value changes. This is addressed in the following chapters. -The source code from the following files are referred to in this chapter: -\noautolist -\generatelist examplefiles .*chapter1.* - \section1 Chapter 2: Connecting to C++ Methods and Signals \c extending-qml/chapter2-methods 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 +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 tutorials/extending-qml/chapter2-methods/app.qml 0 +\snippet tutorials/extending-qml/chapter2-methods/App.qml 0 \image extending-tutorial-chapter2.png @@ -205,8 +201,7 @@ disappears, and the application outputs: qml: The chart has been cleared \endcode -The source code from the following files are referred to in this chapter: -\generatelist examplefiles .*chapter2.* + \section1 Chapter 3: Adding Property Bindings \c extending-qml/chapter3-bindings @@ -218,7 +213,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 tutorials/extending-qml/chapter3-bindings/app.qml 0 +\snippet tutorials/extending-qml/chapter3-bindings/App.qml 0 \image extending-tutorial-chapter3.png @@ -256,8 +251,7 @@ automatically updated and cannot be used as flexibly in QML. Also, since bindings are invoked so often and relied upon in QML usage, users of your custom QML types may see unexpected behavior if bindings are not implemented. -The source code from the following files are referred to in this chapter: -\generatelist examplefiles .*chapter3.* + \section1 Chapter 4: Using Custom Property Types @@ -301,7 +295,7 @@ 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 tutorials/extending-qml/chapter4-customPropertyTypes/app.qml 0 +\snippet tutorials/extending-qml/chapter4-customPropertyTypes/App.qml 0 Like \c PieChart, this new \c PieSlice type inherits from QQuickPaintedItem and declares its properties with Q_PROPERTY(): @@ -346,8 +340,7 @@ Using CMake: \snippet tutorials/extending-qml/chapter4-customPropertyTypes/CMakeLists.txt 1 \dots -The source code from the following files are referred to in this chapter: -\generatelist examplefiles .*chapter4.* + \section1 Chapter 5: Using List Property Types \c extending-qml/chapter5-listproperties @@ -356,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 tutorials/extending-qml/chapter5-listproperties/app.qml 0 +\snippet tutorials/extending-qml/chapter5-listproperties/App.qml 0 \image extending-tutorial-chapter5.png @@ -391,14 +384,13 @@ 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 source code from the following files are referred to in this chapter: -\generatelist examplefiles .*chapter5.* + \section1 Chapter 6: Writing an Extension Plugin \c extending-qml/chapter6-plugins -Currently the \c PieChart and \c PieSlice types are used by \c app.qml, +Currently the \c PieChart and \c PieSlice types are used by \c App.qml, which is displayed using a QQuickView in a C++ application. An alternative way to use our QML extension is to create a plugin library to make it available to the QML engine as a new QML import module. This allows the \c PieChart and @@ -456,19 +448,18 @@ by the module: Now we have a QML module that can be imported to any application, provided that the QML engine knows where to find it. The example contains an executable that loads -\c app.qml, which uses the \c {import Charts 1.0} statement. Alternatively, you can +\c App.qml, which uses the \c {import Charts 1.0} statement. Alternatively, you can load the QML file using the \l {Prototyping with the QML Runtime Tool}{qml tool}, setting the import path to the current directory so that it finds the \c qmldir file: \code - qml -I . app.qml + qml -I . App.qml \endcode The module "Charts" will be loaded by the QML engine, and the types provided by that module will be available for use in any QML document which imports it. -The source code from the following files are referred to in this chapter: -\generatelist examplefiles .*chapter6.* + \section1 Chapter 7: Summary @@ -507,4 +498,6 @@ Or randomly add and remove slices from time to time using \l{Property Value Sour } \endcode +\note To continue learning about QML extensions and features follow the +\l {Writing advanced QML Extensions with C++} tutorial. */ |