diff options
Diffstat (limited to 'src/qml/doc/src/cppintegration/extending-tutorial.qdoc')
| -rw-r--r-- | src/qml/doc/src/cppintegration/extending-tutorial.qdoc | 100 |
1 files changed, 50 insertions, 50 deletions
diff --git a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc index 8ed3aa8279..63c06e2706 100644 --- a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc +++ b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** 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. @@ -44,12 +44,12 @@ examples/quick/tutorials/extending directory. Tutorial chapters: \list 1 -\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{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{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/quick/tutorials/extending/chapter1-basics +\example 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/quick/tutorials/extending/chapter1-basics/piechart.h 0 +\snippet 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/quick/tutorials/extending/chapter1-basics/piechart.cpp 0 +\snippet quick/tutorials/extending/chapter1-basics/piechart.cpp 0 \dots 0 -\snippet examples/quick/tutorials/extending/chapter1-basics/piechart.cpp 1 +\snippet 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/quick/tutorials/extending/chapter1-basics/app.qml 0 +\snippet 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,14 +142,14 @@ 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/quick/tutorials/extending/chapter1-basics/main.cpp 0 +\snippet 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/quick/tutorials/extending/chapter1-basics/chapter1-basics.pro +\quotefile quick/tutorials/extending/chapter1-basics/chapter1-basics.pro Now we can build and run the application: @@ -162,26 +162,26 @@ Try it yourself with the code in Qt's \c examples/quick/tutorials/extending/chap /*! \title Chapter 2: Connecting to C++ Methods and Signals -\example examples/quick/tutorials/extending/chapter2-methods +\example 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/quick/tutorials/extending/chapter2-methods/app.qml 0 +\snippet 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/quick/tutorials/extending/chapter2-methods/piechart.h 0 +\snippet quick/tutorials/extending/chapter2-methods/piechart.h 0 \dots -\snippet examples/quick/tutorials/extending/chapter2-methods/piechart.h 1 +\snippet quick/tutorials/extending/chapter2-methods/piechart.h 1 \dots -\snippet examples/quick/tutorials/extending/chapter2-methods/piechart.h 2 +\snippet quick/tutorials/extending/chapter2-methods/piechart.h 2 \dots -\snippet examples/quick/tutorials/extending/chapter2-methods/piechart.h 3 +\snippet 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/quick/tutorials/extending/chapter2-methods/piechart.cpp 0 +\snippet 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: @@ -207,7 +207,7 @@ Try out the example yourself with the updated code in Qt's \c examples/quick/tut /*! \title Chapter 3: Adding Property Bindings -\example examples/quick/tutorials/extending/chapter3-bindings +\example 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/quick/tutorials/extending/chapter3-bindings/app.qml 0 +\snippet 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/quick/tutorials/extending/chapter3-bindings/piechart.h 0 +\snippet quick/tutorials/extending/chapter3-bindings/piechart.h 0 \dots -\snippet examples/quick/tutorials/extending/chapter3-bindings/piechart.h 1 +\snippet quick/tutorials/extending/chapter3-bindings/piechart.h 1 \dots -\snippet examples/quick/tutorials/extending/chapter3-bindings/piechart.h 2 +\snippet quick/tutorials/extending/chapter3-bindings/piechart.h 2 \dots -\snippet examples/quick/tutorials/extending/chapter3-bindings/piechart.h 3 +\snippet quick/tutorials/extending/chapter3-bindings/piechart.h 3 Then, we emit this signal in \c setPieSlice(): -\snippet examples/quick/tutorials/extending/chapter3-bindings/piechart.cpp 0 +\snippet 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/quick/tutorials/extending/chapter4-customPropertyTypes +\example 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,41 +299,41 @@ 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/quick/tutorials/extending/chapter4-customPropertyTypes/app.qml 0 +\snippet 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/quick/tutorials/extending/chapter4-customPropertyTypes/pieslice.h 0 +\snippet 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/quick/tutorials/extending/chapter4-customPropertyTypes/piechart.h 0 +\snippet quick/tutorials/extending/chapter4-customPropertyTypes/piechart.h 0 \dots -\snippet examples/quick/tutorials/extending/chapter4-customPropertyTypes/piechart.h 1 +\snippet quick/tutorials/extending/chapter4-customPropertyTypes/piechart.h 1 \dots -\snippet examples/quick/tutorials/extending/chapter4-customPropertyTypes/piechart.h 2 +\snippet quick/tutorials/extending/chapter4-customPropertyTypes/piechart.h 2 \dots -\snippet examples/quick/tutorials/extending/chapter4-customPropertyTypes/piechart.h 3 +\snippet 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/quick/tutorials/extending/chapter4-customPropertyTypes/piechart.cpp 0 +\snippet 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/quick/tutorials/extending/chapter4-customPropertyTypes/main.cpp 0 +\snippet quick/tutorials/extending/chapter4-customPropertyTypes/main.cpp 0 \dots -\snippet examples/quick/tutorials/extending/chapter4-customPropertyTypes/main.cpp 1 +\snippet quick/tutorials/extending/chapter4-customPropertyTypes/main.cpp 1 \dots -\snippet examples/quick/tutorials/extending/chapter4-customPropertyTypes/main.cpp 2 +\snippet quick/tutorials/extending/chapter4-customPropertyTypes/main.cpp 2 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/quick/tutorials/extending/chapter4- /*! \title Chapter 5: Using List Property Types -\example examples/quick/tutorials/extending/chapter5-listproperties +\example 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/quick/tutorials/extending/chapter5-listproperties/app.qml 0 +\snippet 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/quick/tutorials/extending/chapter5-listproperties/piechart.h 0 +\snippet quick/tutorials/extending/chapter5-listproperties/piechart.h 0 \dots -\snippet examples/quick/tutorials/extending/chapter5-listproperties/piechart.h 1 +\snippet quick/tutorials/extending/chapter5-listproperties/piechart.h 1 \dots -\snippet examples/quick/tutorials/extending/chapter5-listproperties/piechart.h 2 +\snippet 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/quick/tutorials/extending/chapter5-listproperties/piechart.cpp 0 +\snippet 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 @@ -392,7 +392,7 @@ The complete code can be seen in the updated \c examples/quick/tutorials/extendi /*! \title Chapter 6: Writing an Extension Plugin -\example examples/quick/tutorials/extending/chapter6-plugins +\example 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/quick/tutorials/extending/chapter6-plugins/chartsplugin.h 0 +\snippet quick/tutorials/extending/chapter6-plugins/chartsplugin.h 0 And its implementation in \c chartsplugin.cpp: -\snippet examples/quick/tutorials/extending/chapter6-plugins/chartsplugin.cpp 0 +\snippet 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/quick/tutorials/extending/chapter6-plugins/chapter6-plugins.pro +\quotefile 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/quick/tutorials/extending/chapter6-plugins/Charts/qmldir +\quotefile 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}, |