The Adding Types Example shows how to add a new object type, \c Person, to QML.
The \c Person type can be used from QML like this:
-\snippet qml/referenceexamples/adding/example.qml 0
+\snippet referenceexamples/adding/example.qml 0
\section1 Declare the Person class
Although in this example we use the same name for the C++ class as the QML
type, the C++ class can be named differently, or appear in a namespace.
-\snippet qml/referenceexamples/adding/person.h 0
+\snippet referenceexamples/adding/person.h 0
\section1 Define the Person class
-\snippet qml/referenceexamples/adding/person.cpp 0
+\snippet referenceexamples/adding/person.cpp 0
The Person class implementation is quite basic. The property accessors simply
return members of the object instance.
a birthday party, consisting of a celebrant and a list of guests. People are
specified using the People QML type built in the previous example.
-\snippet qml/referenceexamples/properties/example.qml 0
+\snippet referenceexamples/properties/example.qml 0
\section1 Declare the BirthdayParty
The BirthdayParty class is declared like this:
-\snippet qml/referenceexamples/properties/birthdayparty.h 0
-\snippet qml/referenceexamples/properties/birthdayparty.h 1
-\snippet qml/referenceexamples/properties/birthdayparty.h 2
-\snippet qml/referenceexamples/properties/birthdayparty.h 3
+\snippet referenceexamples/properties/birthdayparty.h 0
+\snippet referenceexamples/properties/birthdayparty.h 1
+\snippet referenceexamples/properties/birthdayparty.h 2
+\snippet referenceexamples/properties/birthdayparty.h 3
The class contains a member to store the celebrant object, and also a
QList<Person *> member.
The implementation of BirthdayParty property accessors is straight forward.
-\snippet qml/referenceexamples/properties/birthdayparty.cpp 0
+\snippet referenceexamples/properties/birthdayparty.cpp 0
\section1 Running the example
types of more than one type to a property. It specializes the Person type
developed in the previous examples into two types - a \c Boy and a \c Girl.
-\snippet qml/referenceexamples/coercion/example.qml 0
+\snippet referenceexamples/coercion/example.qml 0
\section1 Declare Boy and Girl
-\snippet qml/referenceexamples/coercion/person.h 0
+\snippet referenceexamples/coercion/person.h 0
The Person class remains unaltered in this example and the Boy and Girl C++
classes are trivial extensions of it. As an example, the inheritance used here
base for Boy and Girl, we want to prevent it from being instantiated from QML
directly - an explicit Boy or Girl should be instantiated instead.
-\snippet qml/referenceexamples/coercion/main.cpp 0
+\snippet referenceexamples/coercion/main.cpp 0
While we want to disallow instantiating Person from within QML, it still needs
to be registered with the QML engine, so that it can be used as a property type
The implementation of Boy and Girl are trivial.
-\snippet qml/referenceexamples/coercion/person.cpp 1
+\snippet referenceexamples/coercion/person.cpp 1
All that is necessary is to implement the constructor, and to register the types
and their QML name with the QML engine.
The BirthdayParty type has not changed since the previous example. The
celebrant and guests property still use the People type.
-\snippet qml/referenceexamples/coercion/birthdayparty.h 0
+\snippet referenceexamples/coercion/birthdayparty.h 0
However, as all three types, Person, Boy and Girl, have been registered with the
QML system, on assignment QML automatically (and type-safely) converts the Boy
\l {Extending QML - Inheritance and Coercion Example} that simplifies the
specification of a BirthdayParty through the use of a default property.
-\snippet qml/referenceexamples/default/example.qml 0
+\snippet referenceexamples/default/example.qml 0
\section1 Declaring the BirthdayParty class
The only difference between this example and the last, is the addition of the
\c DefaultProperty class info annotation.
-\snippet qml/referenceexamples/default/birthdayparty.h 0
+\snippet referenceexamples/default/birthdayparty.h 0
The default property specifies the property to assign to whenever an explicit
property is not specified, in the case of the BirthdayParty type the guest
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
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.
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
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.
*/
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
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:
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.
*/
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
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
"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.
*/
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
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.
\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
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.
*/
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},
projects / konrad/qtdeclarative.git / commitdiff