Change tutorial from using "Musician" etc. types to using "PieChart"

etc. types to make a more practical example that shows how to do
painting as well. Also includes some tutorial improvments.

1 files changed, 149 insertions, 106 deletions

diff --git a/doc/src/declarative/extending-tutorial.qdoc b/doc/src/declarative/extending-tutorial.qdoc
index 2cf00b9..9170c5c 100644
--- a/doc/src/declarative/extending-tutorial.qdoc
+++ b/doc/src/declarative/extending-tutorial.qdoc
@@ -59,61 +59,94 @@ Tutorial chapters:
 
 \example declarative/tutorials/extending/chapter1-basics
 
-Let's create a new QML type called "Musician" that has two properties: a name
-and an instrument.  We will make it available in a \l {Modules}{module} called "Music", with
+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 {QML Elements}.
+For example, this could be done to implement particular data models, or provide
+elements with custom painting and drawing capabilities, or access system features
+like network programming that are not accessible through built-in QML features.
+
+In this tutorial, we will show how to use the C++ classes in the QtDeclarative
+module to extend QML. The end result will be a simple Pie Chart display implemented by
+several custom QML types connected together through QML features like bindings and 
+signals, and made available to the QML runtime through a plugin.
+
+To begin with, let's create a new QML type called "PieChart" that has two properties: a name
+and a color.  We will make it available in a \l {Modules}{module} called "Charts", with
 a module version of 1.0. 
-We want this \c Musician type to be usable from QML like this:
+
+We want this \c PieChart type to be usable from QML like this:
 
 \code
-    import Music 1.0
+    import Charts 1.0
     
-    Musician {
-        name: "Reddy the Rocker"
-        instrument: "Guitar"
+    PieChart {
+        width: 100; height: 100
+        name: "A simple pie chart"
+        color: "red"
     }
 \endcode
 
-To do this, we need a C++ class that encapsulates this \c Musician type and its two
-properties. Since QML relies heavily on Qt's \l{Meta-Object System}{meta object system},
+To do this, we need a C++ class that encapsulates this \c PieChart type and its two
+properties. Since QML makes extensive use of Qt's \l{Meta-Object System}{meta object system},
 this new class must:
 
 \list
-\o inherit from QObject
-\o declare its properties using the Q_PROPERTY() macro
+\o Inherit from QObject
+\o Declare its properties using the Q_PROPERTY macro
 \endlist
 
-Here is our \c Musician class, defined in \c musician.h:
+Here is our \c PieChart class, defined in \c piechart.h:
+
+\snippet declarative/tutorials/extending/chapter1-basics/piechart.h 0
 
-\snippet declarative/tutorials/extending/chapter1-basics/musician.h 0
+The class inherits from QDeclarativeItem because we want to override 
+QDeclarativeItem::paint() in order to draw. If the class just represented some
+data type and was not an item that actually needed to be displayed, it could simply inherit
+from QObject. Or, if we want to extend the functionality of an existing QObject-based 
+class, it could inherit from that class instead.
 
-It defines the two properties, \c name and \c instrument, with the Q_PROPERTY() macro.
-The class implementation in \c musician.cpp simply sets and returns the \c m_name and
-\c m_instrument values as appropriate.
+The \c PieChart class defines the two properties, \c name and \c color, with the Q_PROPERTY macro,
+and overrides QDeclarativeItem::paint(). 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:
 
-Our QML file, \c app.qml, creates a \c Musician item and display the musician's details
+\snippet declarative/tutorials/extending/chapter1-basics/piechart.cpp 0
+\dots 0
+\snippet declarative/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 declarative/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
+provided for various other \l {QML Basic Types}{basic types}; for example, a string
+like "640x480" can be automatically converted to a QSize value.
+
 We'll also create a C++ application that uses a QDeclarativeView to run and
-display \c app.qml. The application must register the \c Musician type
+display \c app.qml. The application must register the \c PieChart type
 using the qmlRegisterType() function, to allow it to be used from QML. If
-you don't register the type, \c app.qml won't be able to create a \c Musician.
+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 declarative/tutorials/extending/chapter1-basics/main.cpp 0
 
-This call to qmlRegisterType() registers the \c Musician type as a type called "Musician", in a module named "Music",
+This call to qmlRegisterType() registers the \c PieChart type as a type called "PieChart", in a module named "Charts",
 with a module version of 1.0.
 
 Lastly, we write a \c .pro project file that includes the files and the \c declarative library:
 
 \quotefile declarative/tutorials/extending/chapter1-basics/chapter1-basics.pro
 
-Now we can build and run the application. Try it yourself with the code in Qt's \c examples/tutorials/extending/chapter1-basics directory.
+Now we can build and run the application:
 
-\example declarative/tutorials/extending/chapter1-basics
+\image extending-tutorial-chapter1.png
+
+Try it yourself with the code in Qt's \c examples/tutorials/extending/chapter1-basics directory.
 
 At the moment, the \c app.qml is run from within a C++ application.
 This may seem odd if you're used to running QML files with the \l {QML Viewer}.
@@ -128,39 +161,40 @@ Later on, we'll show how to create a plugin so that you can run \c app.qml using
 
 \example declarative/tutorials/extending/chapter2-methods
 
-Suppose we want \c Musician to have a "perform" method that prints a message
-to the console and then emits a "performanceEnded" signal.
-Other elements would be able to call \c perform() and receive
-\c performanceEnded() signals like this:
+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 declarative/tutorials/extending/chapter2-methods/app.qml 0
 
-To do this, we add a \c perform() method and a \c performanceEnded() signal
+\image extending-tutorial-chapter2.png
+
+To do this, we add a \c clearChart() method and a \c chartCleared() signal
 to our C++ class:
 
-\snippet declarative/tutorials/extending/chapter2-methods/musician.h 0
+\snippet declarative/tutorials/extending/chapter2-methods/piechart.h 0
 \dots
-\snippet declarative/tutorials/extending/chapter2-methods/musician.h 1
+\snippet declarative/tutorials/extending/chapter2-methods/piechart.h 1
 \dots
-\snippet declarative/tutorials/extending/chapter2-methods/musician.h 2
+\snippet declarative/tutorials/extending/chapter2-methods/piechart.h 2
 \dots
-\snippet declarative/tutorials/extending/chapter2-methods/musician.h 3
+\snippet declarative/tutorials/extending/chapter2-methods/piechart.h 3
 
-The use of Q_INVOKABLE makes the \c perform() method available to the
+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
 been declared as as a Qt slot instead of using Q_INVOKABLE, as
 slots are also callable from QML. Both of these approaches are valid.
 
-The \c perform() method simply prints a message to the console and
-then emits \c performanceEnded():
+The \c clearChart() method simply changes the color to Qt::transparent,
+repaints the chart, then emits the \c chartCleared() signal:
 
-\snippet declarative/tutorials/extending/chapter2-methods/musician.cpp 0
+\snippet declarative/tutorials/extending/chapter2-methods/piechart.cpp 0
 
-Now when we run the application and click the window, the application outputs:
+Now when we run the application and click the window, the pie chart
+disappears, and the application outputs:
 
 \code
-    "Reddy the Rocker" is playing the "Guitar"
-    The performance has now ended
+    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.
@@ -174,45 +208,49 @@ Try out the example yourself with the updated code in Qt's \c examples/tutorials
 
 Property bindings is a powerful feature of QML that allows values of different
 elements to be synchronized automatically. It uses signals to notify and update
-other elements' values when property values change.
+other elements' values when property values are changed.
 
-Let's enable property bindings for the \c instrument property. That means 
+Let's enable property bindings for the \c color property. That means 
 if we have code like this:
 
 \snippet declarative/tutorials/extending/chapter3-bindings/app.qml 0
 
-The "instrument: reddy.instrument" statement binds the \c instrument value of
-\c craig to the \c instrument of \c reddy.
-Whenever \c reddy's \c instrument value changes, \c craig's \c instrument value
-updates to the same value. When the window is clicked, the application outputs:
+\image extending-tutorial-chapter3.png
 
-\code
-    "Reddy the Rocker" is playing the "Guitar"
-    "Craig the Copycat" is playing the "Guitar"
-    "Reddy the Rocker" is playing the "Drums"
-    "Craig the Copycat" is playing the "Drums"
-\endcode
+The "color: chartA.color" statement binds the \c color value of
+\c chartB to the \c color of \c chartA.
+Whenever \c chartA's \c color value changes, \c chartB's \c color value
+updates to the same value. When the window is clicked, the \c onClicked
+handler in the MouseArea changes the color of \c chartA, thereby changing
+both charts to the color blue.
 
-It's easy to enable property binding for the \c instrument property. 
-We add a \l{Qt's Property System}{NOTIFY} feature to its Q_PROPERTY() declaration to indicate that a "instrumentChanged" signal
+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 declarative/tutorials/extending/chapter3-bindings/musician.h 0
+\snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 0
 \dots
-\snippet declarative/tutorials/extending/chapter3-bindings/musician.h 1
+\snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 1
 \dots
-\snippet declarative/tutorials/extending/chapter3-bindings/musician.h 2
+\snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 2
 \dots
-\snippet declarative/tutorials/extending/chapter3-bindings/musician.h 3
+\snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 3
 
-Then, we emit this signal in \c setInstrument():
+Then, we emit this signal in \c setPieSlice():
 
-\snippet declarative/tutorials/extending/chapter3-bindings/musician.cpp 0
+\snippet declarative/tutorials/extending/chapter3-bindings/piechart.cpp 0
 
-It's important for \c setInstrument() to check that the instrument value has actually changed
-before emitting \c instrumentChanged(). This ensures the signal is not emitted unnecessarily and
+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
 also prevents loops when other elements respond to the value change.
 
+The use of bindings is essential to QML. You should always add NOTIFY 
+signals for properties if they are able to be implemented, so that your
+properties can be used in bindings. Properties that cannot be bound cannot be
+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.
+
 */
 
 /*!
@@ -220,19 +258,19 @@ also prevents loops when other elements respond to the value change.
 
 \example declarative/tutorials/extending/chapter4-customPropertyTypes
 
-The \c Musician type currently has two properties that are both strings. 
-It could have all sorts of other properties. For example, we could add an
-integer-type property to store the age of each musician:
+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, we could add an
+integer-type property to store an identifier for each pie chart:
 
 \code
-    class Musician : public QObject
+    class PieChart : public QDeclarativeItem
     {
         ...
-        Q_PROPERTY(int age READ age WRITE setAge)
+        Q_PROPERTY(int id READ id WRITE setId)
     public:
         ...
-        int age() const;
-        void setAge(int age);
+        int id() const;
+        void setId(int id);
         ...
     };
 \endcode
@@ -257,31 +295,39 @@ types:
 If we want to create a property whose type is not supported by QML by default,
 we need to register the type with QML.
 
-For example, let's change the type of the \c instrument property from a string to a
-new type called "Instrument". Instead of assigning a string value to \c instrument,
-we assign an \c Instrument value:
+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 declarative/tutorials/extending/chapter4-customPropertyTypes/app.qml 0
 
-Like \c Musician, this new \c Instrument type has to inherit from QObject and declare
+Like \c PieChart, this new \c PieSlice type inherits from QDeclarativeItem and declares
 its properties with Q_PROPERTY():
 
-\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/instrument.h 0
+\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/pieslice.h 0
 
-To use it from \c Musician, we modify the \c instrument property declaration
+To use it in \c PieChart, we modify the \c color property declaration
 and associated method signatures:
 
-\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/musician.h 0
+\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 0
 \dots
-\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/musician.h 1
+\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 1
 \dots
-\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/musician.h 2
+\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 2
 \dots
-\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/musician.h 3
+\snippet declarative/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
+QDeclarativeItem::setParentItem() so that the \c PieChart knows to paint this child
+item when its contents are drawn:
 
-Like the \c Musician type, the \c Instrument type has to be registered
-using qmlRegisterType() to be used from QML. As with \c Musician, we'll add the
-type to the "Music" module, version 1.0:
+\snippet declarative/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" module, version 1.0:
 
 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/main.cpp 0
 \dots
@@ -298,10 +344,10 @@ Try it out with the code in Qt's \c examples/tutorials/extending/chapter4-custom
 
 \example declarative/tutorials/extending/chapter5-plugins
 
-Currently the \c Musician and \c Instrument 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 QDeclarativeView 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. This means we could load \c app.qml using the \l {QML Viewer}
+to the QML engine. This allows us to load \c app.qml using the \l {QML Viewer}
 (or some other QML \l{Qt Declarative UI Runtime}{runtime} application) instead of writing a \c main.cpp file and
 loading our own C++ application.
 
@@ -313,17 +359,17 @@ To create a plugin library, we need:
 \o A "qmldir" file that tells the QML engine to load the plugin
 \endlist
 
-First, we create a plugin class named \c MusicPlugin. It subclasses QDeclarativeExtensionPlugin
+First, we create a plugin class named \c ChartsPlugin. It subclasses QDeclarativeExtensionPlugin
 and registers our QML types in the inherited \l{QDeclarativeExtensionPlugin::}{registerTypes()} method. It also calls
 Q_EXPORT_PLUGIN2 for Qt's \l{How to Create Qt Plugins}{plugin system}.
 
-Here is the \c MusicPlugin definition in \c musicplugin.h:
+Here is the \c ChartsPlugin definition in \c chartsplugin.h:
 
-\snippet declarative/tutorials/extending/chapter5-plugins/musicplugin.h 0
+\snippet declarative/tutorials/extending/chapter5-plugins/chartsplugin.h 0
 
-And its implementation in \c musicplugin.cpp:
+And its implementation in \c chartsplugin.cpp:
 
-\snippet declarative/tutorials/extending/chapter5-plugins/musicplugin.cpp 0
+\snippet declarative/tutorials/extending/chapter5-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:
@@ -345,9 +391,9 @@ the project and then load the QML file in the \l {QML Viewer}:
 
 (On Mac OS X, you can launch the "QMLViewer" application instead.)
 
-Notice the "import Music 1.0" statement has disappeared from \c app.qml. This is
+Notice the "import Charts 1.0" statement has disappeared from \c app.qml. This is
 because the \c qmldir file is in the same directory as \c app.qml: this is equivalent to
-having Musician.qml and Instrument.qml files inside the project directory, which could both
+having PieChart.qml and PieSlice.qml files inside the project directory, which could both
 be used by \c app.qml without import statements.
 */
 
@@ -367,42 +413,39 @@ In this tutorial, we've shown the basic steps for creating a QML extension:
 
 
 The \l {Extending QML in C++} reference documentation shows other useful features that can be added to
-QML extensions. For example, we could use \l{Object and List Property Types}{list properties} to allow multiple instruments for a \c Musician:
+QML extensions. For example, we could use \l{Object and List Property Types}{list properties} to allow multiple slices for a \c PieChart:
 
 \code
-    Musician {
-        instruments: [
-            Instrument { type: "Guitar" }
-            Instrument { type: "Drums" }
-            Instrument { type: "Keyboard" }
+    PieChart {
+        slices: [
+            PieSlice { color: "red" }
+            PieSlice { color: "blue" }
+            PieSlice { color: "yellow" }
         ]
     }
 \endcode
 
 Or use \l{Default Property}{default properties} and avoid an
-\c instruments property altogether:
+\c slices property altogether:
 
 \code
-    Musician {
-        Instrument { type: "Guitar" }
-        Instrument { type: "Drums" }
-        Instrument { type: "Keyboard" }
+    PieChart {
+        PieSlice { color: "red" }
+        PieSlice { color: "blue" }
+        PieSlice { color: "yellow" }
     }
 \endcode
 
-Or even change the \c instrument of a \c Musician from time to time using \l{Property Value Sources}{property value sources}:
+Or even change the \c color of a \c PieChart from time to time using \l{Property Value Sources}{property value sources}:
 
 \code
-    Musician {
-        InstrumentRandomizer on instrument {}
+    PieChart {
+        PieSliceRandomizer on color {}
     }
 \endcode
 
 
 See the \l{Extending QML in C++}{reference documentation} for more information.
 
-Additionally, \l {Integrating QML with existing Qt UI code} shows how to create
-and integrate with QML extensions that have drawing and graphical capabilities (through QGraphicsWidget).
-
 */