diff options
Diffstat (limited to 'src/qml/doc/src/cppintegration/extending-tutorial.qdoc')
| -rw-r--r-- | src/qml/doc/src/cppintegration/extending-tutorial.qdoc | 106 |
1 files changed, 53 insertions, 53 deletions
diff --git a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc index d59a8cd827..8ed3aa8279 100644 --- a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc +++ b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc @@ -44,12 +44,12 @@ examples/quick/tutorials/extending directory. Tutorial chapters: \list 1 -\li \l{examples/tutorials/extending/chapter1-basics}{Creating a New Type} -\li \l{examples/tutorials/extending/chapter2-methods}{Connecting to C++ Methods and Signals} -\li \l{examples/tutorials/extending/chapter3-bindings}{Property Binding} -\li \l{examples/tutorials/extending/chapter4-customPropertyTypes}{Using Custom Property Types} -\li \l{examples/tutorials/extending/chapter5-listproperties}{Using List Property Types} -\li \l{examples/tutorials/extending/chapter6-plugins}{Writing an Extension Plugin} +\li \l{examples/quick/tutorials/extending/chapter1-basics}{Creating a New Type} +\li \l{examples/quick/tutorials/extending/chapter2-methods}{Connecting to C++ Methods and Signals} +\li \l{examples/quick/tutorials/extending/chapter3-bindings}{Property Binding} +\li \l{examples/quick/tutorials/extending/chapter4-customPropertyTypes}{Using Custom Property Types} +\li \l{examples/quick/tutorials/extending/chapter5-listproperties}{Using List Property Types} +\li \l{examples/quick/tutorials/extending/chapter6-plugins}{Writing an Extension Plugin} \li \l{qml-extending-tutorial7.html}{In Summary} \endlist @@ -64,7 +64,7 @@ and \l {qtqml-cppintegration-definetypes.html}{Defining QML Types from C++}. /*! \title Chapter 1: Creating a New Type -\example examples/tutorials/extending/chapter1-basics +\example examples/quick/tutorials/extending/chapter1-basics A common task when extending QML is to provide a new QML type that supports some custom functionality beyond what is provided by the built-in \l {Qt Quick QML Types}{QtQuick types}. @@ -104,7 +104,7 @@ this new class must: Here is our \c PieChart class, defined in \c piechart.h: -\snippet examples/tutorials/extending/chapter1-basics/piechart.h 0 +\snippet examples/quick/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 examples/tutorials/extending/chapter1-basics/piechart.cpp 0 +\snippet examples/quick/tutorials/extending/chapter1-basics/piechart.cpp 0 \dots 0 -\snippet examples/tutorials/extending/chapter1-basics/piechart.cpp 1 +\snippet examples/quick/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 examples/tutorials/extending/chapter1-basics/app.qml 0 +\snippet examples/quick/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,46 +142,46 @@ 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 examples/tutorials/extending/chapter1-basics/main.cpp 0 +\snippet examples/quick/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 examples/tutorials/extending/chapter1-basics/chapter1-basics.pro +\quotefile examples/quick/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/tutorials/extending/chapter1-basics directory. +Try it yourself with the code in Qt's \c examples/quick/tutorials/extending/chapter1-basics directory. */ /*! \title Chapter 2: Connecting to C++ Methods and Signals -\example examples/tutorials/extending/chapter2-methods +\example examples/quick/tutorials/extending/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 to call \c clearChart() and receive \c chartCleared() signals like this: -\snippet examples/tutorials/extending/chapter2-methods/app.qml 0 +\snippet examples/quick/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 examples/tutorials/extending/chapter2-methods/piechart.h 0 +\snippet examples/quick/tutorials/extending/chapter2-methods/piechart.h 0 \dots -\snippet examples/tutorials/extending/chapter2-methods/piechart.h 1 +\snippet examples/quick/tutorials/extending/chapter2-methods/piechart.h 1 \dots -\snippet examples/tutorials/extending/chapter2-methods/piechart.h 2 +\snippet examples/quick/tutorials/extending/chapter2-methods/piechart.h 2 \dots -\snippet examples/tutorials/extending/chapter2-methods/piechart.h 3 +\snippet examples/quick/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 examples/tutorials/extending/chapter2-methods/piechart.cpp 0 +\snippet examples/quick/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,14 +200,14 @@ 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/tutorials/extending/chapter2-methods directory. +Try out the example yourself with the updated code in Qt's \c examples/quick/tutorials/extending/chapter2-methods directory. */ /*! \title Chapter 3: Adding Property Bindings -\example examples/tutorials/extending/chapter3-bindings +\example examples/quick/tutorials/extending/chapter3-bindings Property binding is a powerful feature of QML that allows values of different elements to be synchronized automatically. It uses signals to notify and update @@ -216,7 +216,7 @@ other elements' 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 examples/tutorials/extending/chapter3-bindings/app.qml 0 +\snippet examples/quick/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 examples/tutorials/extending/chapter3-bindings/piechart.h 0 +\snippet examples/quick/tutorials/extending/chapter3-bindings/piechart.h 0 \dots -\snippet examples/tutorials/extending/chapter3-bindings/piechart.h 1 +\snippet examples/quick/tutorials/extending/chapter3-bindings/piechart.h 1 \dots -\snippet examples/tutorials/extending/chapter3-bindings/piechart.h 2 +\snippet examples/quick/tutorials/extending/chapter3-bindings/piechart.h 2 \dots -\snippet examples/tutorials/extending/chapter3-bindings/piechart.h 3 +\snippet examples/quick/tutorials/extending/chapter3-bindings/piechart.h 3 Then, we emit this signal in \c setPieSlice(): -\snippet examples/tutorials/extending/chapter3-bindings/piechart.cpp 0 +\snippet examples/quick/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 @@ -259,7 +259,7 @@ custom QML types may see unexpected behavior if bindings are not implemented. /*! \title Chapter 4: Using Custom Property Types -\example examples/tutorials/extending/chapter4-customPropertyTypes +\example examples/quick/tutorials/extending/chapter4-customPropertyTypes The \c PieChart type currently has a string-type property and a color-type property. It could have many other types of properties. For example, it could have an @@ -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 examples/tutorials/extending/chapter4-customPropertyTypes/app.qml 0 +\snippet examples/quick/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 examples/tutorials/extending/chapter4-customPropertyTypes/pieslice.h 0 +\snippet examples/quick/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 examples/tutorials/extending/chapter4-customPropertyTypes/piechart.h 0 +\snippet examples/quick/tutorials/extending/chapter4-customPropertyTypes/piechart.h 0 \dots -\snippet examples/tutorials/extending/chapter4-customPropertyTypes/piechart.h 1 +\snippet examples/quick/tutorials/extending/chapter4-customPropertyTypes/piechart.h 1 \dots -\snippet examples/tutorials/extending/chapter4-customPropertyTypes/piechart.h 2 +\snippet examples/quick/tutorials/extending/chapter4-customPropertyTypes/piechart.h 2 \dots -\snippet examples/tutorials/extending/chapter4-customPropertyTypes/piechart.h 3 +\snippet examples/quick/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 examples/tutorials/extending/chapter4-customPropertyTypes/piechart.cpp 0 +\snippet examples/quick/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 examples/tutorials/extending/chapter4-customPropertyTypes/main.cpp 0 +\snippet examples/quick/tutorials/extending/chapter4-customPropertyTypes/main.cpp 0 \dots -\snippet examples/tutorials/extending/chapter4-customPropertyTypes/main.cpp 1 +\snippet examples/quick/tutorials/extending/chapter4-customPropertyTypes/main.cpp 1 \dots -\snippet examples/tutorials/extending/chapter4-customPropertyTypes/main.cpp 2 +\snippet examples/quick/tutorials/extending/chapter4-customPropertyTypes/main.cpp 2 -Try it out with the code in Qt's \c examples/tutorials/extending/chapter4-customPropertyTypes directory. +Try it out with the code in Qt's \c examples/quick/tutorials/extending/chapter4-customPropertyTypes directory. */ @@ -343,13 +343,13 @@ Try it out with the code in Qt's \c examples/tutorials/extending/chapter4-custom /*! \title Chapter 5: Using List Property Types -\example examples/tutorials/extending/chapter5-listproperties +\example examples/quick/tutorials/extending/chapter5-listproperties 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 examples/tutorials/extending/chapter5-listproperties/app.qml 0 +\snippet examples/quick/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 examples/tutorials/extending/chapter5-listproperties/piechart.h 0 +\snippet examples/quick/tutorials/extending/chapter5-listproperties/piechart.h 0 \dots -\snippet examples/tutorials/extending/chapter5-listproperties/piechart.h 1 +\snippet examples/quick/tutorials/extending/chapter5-listproperties/piechart.h 1 \dots -\snippet examples/tutorials/extending/chapter5-listproperties/piechart.h 2 +\snippet examples/quick/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 examples/tutorials/extending/chapter5-listproperties/piechart.cpp 0 +\snippet examples/quick/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/tutorials/extending/chapter5-listproperties directory. +The complete code can be seen in the updated \c examples/quick/tutorials/extending/chapter5-listproperties directory. */ @@ -392,7 +392,7 @@ The complete code can be seen in the updated \c examples/tutorials/extending/cha /*! \title Chapter 6: Writing an Extension Plugin -\example examples/tutorials/extending/chapter6-plugins +\example examples/quick/tutorials/extending/chapter6-plugins 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 @@ -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 examples/tutorials/extending/chapter6-plugins/chartsplugin.h 0 +\snippet examples/quick/tutorials/extending/chapter6-plugins/chartsplugin.h 0 And its implementation in \c chartsplugin.cpp: -\snippet examples/tutorials/extending/chapter6-plugins/chartsplugin.cpp 0 +\snippet examples/quick/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 examples/tutorials/extending/chapter6-plugins/chapter6-plugins.pro +\quotefile examples/quick/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 examples/tutorials/extending/chapter6-plugins/Charts/qmldir +\quotefile examples/quick/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}, |