Documentation for the Drag and Drop Robot example.

Checked that it doesn't introduce qdoc errors. Discussed with David
and Martin; recommendation was to commit first and fix any errors via
review in later commits.

5 files changed, 172 insertions, 108 deletions

diff --git a/examples/graphicsview/dragdroprobot/coloritem.cpp b/examples/graphicsview/dragdroprobot/coloritem.cpp
index 95878b1..08edd38 100644
--- a/examples/graphicsview/dragdroprobot/coloritem.cpp
+++ b/examples/graphicsview/dragdroprobot/coloritem.cpp
@@ -43,6 +43,7 @@
 
 #include "coloritem.h"
 
+//! [0]
 ColorItem::ColorItem()
     : color(qrand() % 256, qrand() % 256, qrand() % 256)
 {
@@ -50,13 +51,18 @@ ColorItem::ColorItem()
               .arg(color.red()).arg(color.green()).arg(color.blue())
               .arg("Click and drag this color onto the robot!"));
     setCursor(Qt::OpenHandCursor);
+    setAcceptedMouseButtons(Qt::LeftButton);
 }
+//! [0]
 
+//! [1]
 QRectF ColorItem::boundingRect() const
 {
     return QRectF(-15.5, -15.5, 34, 34);
 }
+//! [1]
 
+//! [2]
 void ColorItem::paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget)
 {
     Q_UNUSED(option);
@@ -68,17 +74,16 @@ void ColorItem::paint(QPainter *painter, const QStyleOptionGraphicsItem *option,
     painter->setBrush(QBrush(color));
     painter->drawEllipse(-15, -15, 30, 30);
 }
+//! [2]
 
+//! [3]
 void ColorItem::mousePressEvent(QGraphicsSceneMouseEvent *event)
 {
-    if (event->button() != Qt::LeftButton) {
-        event->ignore();
-        return;
-    }
-
     setCursor(Qt::ClosedHandCursor);
 }
+//! [3]
 
+//! [5]
 void ColorItem::mouseMoveEvent(QGraphicsSceneMouseEvent *event)
 {
     if (QLineF(event->screenPos(), event->buttonDownScreenPos(Qt::LeftButton))
@@ -89,7 +94,9 @@ void ColorItem::mouseMoveEvent(QGraphicsSceneMouseEvent *event)
     QDrag *drag = new QDrag(event->widget());
     QMimeData *mime = new QMimeData;
     drag->setMimeData(mime);
+//! [5]
 
+//! [6]
     static int n = 0;
     if (n++ > 2 && (qrand() % 3) == 0) {
         QImage image(":/images/head.png");
@@ -97,6 +104,8 @@ void ColorItem::mouseMoveEvent(QGraphicsSceneMouseEvent *event)
 
         drag->setPixmap(QPixmap::fromImage(image).scaled(30, 40));
         drag->setHotSpot(QPoint(15, 30));
+//! [6]
+//! [7]
     } else {
         mime->setColorData(color);
         mime->setText(QString("#%1%2%3")
@@ -118,12 +127,17 @@ void ColorItem::mouseMoveEvent(QGraphicsSceneMouseEvent *event)
         drag->setPixmap(pixmap);
         drag->setHotSpot(QPoint(15, 20));
     }
+//! [7]
 
+//! [8]
     drag->exec();
     setCursor(Qt::OpenHandCursor);
 }
+//! [8]
 
+//! [4]
 void ColorItem::mouseReleaseEvent(QGraphicsSceneMouseEvent *)
 {
     setCursor(Qt::OpenHandCursor);
 }
+//! [4]
diff --git a/examples/graphicsview/dragdroprobot/coloritem.h b/examples/graphicsview/dragdroprobot/coloritem.h
index 788d19e..eb19db6 100644
--- a/examples/graphicsview/dragdroprobot/coloritem.h
+++ b/examples/graphicsview/dragdroprobot/coloritem.h
@@ -44,6 +44,7 @@
 
 #include <QGraphicsItem>
 
+//! [0]
 class ColorItem : public QGraphicsItem
 {
 public:
@@ -60,5 +61,6 @@ protected:
 private:
     QColor color;
 };
+//! [0]
 
 #endif
diff --git a/examples/graphicsview/dragdroprobot/main.cpp b/examples/graphicsview/dragdroprobot/main.cpp
index 02585e1..2669c41 100644
--- a/examples/graphicsview/dragdroprobot/main.cpp
+++ b/examples/graphicsview/dragdroprobot/main.cpp
@@ -46,12 +46,14 @@
 
 #include <math.h>
 
+//! [0]
 int main(int argc, char **argv)
 {
     QApplication app(argc, argv);
 
     qsrand(QTime(0,0,0).secsTo(QTime::currentTime()));
-
+//! [0]
+//! [1]
     QGraphicsScene scene(-200, -200, 400, 400);
 
     for (int i = 0; i < 10; ++i) {
@@ -66,7 +68,8 @@ int main(int argc, char **argv)
     robot->scale(1.2, 1.2);
     robot->setPos(0, -20);
     scene.addItem(robot);
-
+//! [1]
+//! [2]
     QGraphicsView view(&scene);
     view.setRenderHint(QPainter::Antialiasing);
     view.setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate);
@@ -76,3 +79,4 @@ int main(int argc, char **argv)
 
     return app.exec();
 }
+//! [2]
diff --git a/examples/graphicsview/dragdroprobot/robot.cpp b/examples/graphicsview/dragdroprobot/robot.cpp
index 9ac6d26..705bd9d 100644
--- a/examples/graphicsview/dragdroprobot/robot.cpp
+++ b/examples/graphicsview/dragdroprobot/robot.cpp
@@ -43,16 +43,18 @@
 
 #include "robot.h"
 
+//! [0]
 RobotPart::RobotPart(QGraphicsItem *parent)
-    : QGraphicsItem(parent), color(Qt::lightGray), dragOver(false)
+    : QGraphicsObject(parent), color(Qt::lightGray), dragOver(false)
 {
     setAcceptDrops(true);
 }
+//! [0]
 
+//! [1]
 void RobotPart::dragEnterEvent(QGraphicsSceneDragDropEvent *event)
 {
-    if (event->mimeData()->hasColor()
-        || (qgraphicsitem_cast<RobotHead *>(this) && event->mimeData()->hasImage())) {
+    if (event->mimeData()->hasColor()) {
         event->setAccepted(true);
         dragOver = true;
         update();
@@ -60,34 +62,42 @@ void RobotPart::dragEnterEvent(QGraphicsSceneDragDropEvent *event)
         event->setAccepted(false);
     }
 }
+//! [1]
 
+//! [2]
 void RobotPart::dragLeaveEvent(QGraphicsSceneDragDropEvent *event)
 {
     Q_UNUSED(event);
     dragOver = false;
     update();
 }
+//! [2]
 
+//! [3]
 void RobotPart::dropEvent(QGraphicsSceneDragDropEvent *event)
 {
     dragOver = false;
     if (event->mimeData()->hasColor())
         color = qVariantValue<QColor>(event->mimeData()->colorData());
-    else if (event->mimeData()->hasImage())
-        pixmap = qVariantValue<QPixmap>(event->mimeData()->imageData());
     update();
 }
+//! [3]
 
+//! [4]
 RobotHead::RobotHead(QGraphicsItem *parent)
     : RobotPart(parent)
 {
 }
+//! [4]
 
+//! [5]
 QRectF RobotHead::boundingRect() const
 {
     return QRectF(-15, -50, 30, 50);
 }
+//! [5]
 
+//! [6]
 void RobotHead::paint(QPainter *painter,
            const QStyleOptionGraphicsItem *option, QWidget *widget)
 {
@@ -110,11 +120,33 @@ void RobotHead::paint(QPainter *painter,
         painter->drawPixmap(QPointF(-15 * 4.4, -50 * 3.54), pixmap);
     }
 }
+//! [6]
 
-int RobotHead::type() const
+//! [7]
+void RobotHead::dragEnterEvent(QGraphicsSceneDragDropEvent *event)
 {
-    return Type;
+    if (event->mimeData()->hasImage()) {
+        event->setAccepted(true);
+        dragOver = true;
+        update();
+    } else {
+        RobotPart::dragEnterEvent(event);
+    }
 }
+//! [7]
+
+//! [8]
+void RobotHead::dropEvent(QGraphicsSceneDragDropEvent *event)
+{
+    if (event->mimeData()->hasImage()) {
+        dragOver = false;
+        pixmap = qVariantValue<QPixmap>(event->mimeData()->imageData());
+        update();
+    } else {
+        RobotPart::dropEvent(event);
+    }
+}
+//! [8]
 
 RobotTorso::RobotTorso(QGraphicsItem *parent)
     : RobotPart(parent)
@@ -161,19 +193,25 @@ void RobotLimb::paint(QPainter *painter,
     painter->drawEllipse(-5, -5, 10, 10);
 }
 
-Robot::Robot()
+//! [10]
+Robot::Robot(QGraphicsItem *parent)
+    : RobotPart(parent)
 {
-    QGraphicsItem *torsoItem = new RobotTorso(this);    
-    QGraphicsItem *headItem = new RobotHead(torsoItem);
-    QGraphicsItem *upperLeftArmItem = new RobotLimb(torsoItem);
-    QGraphicsItem *lowerLeftArmItem = new RobotLimb(upperLeftArmItem);
-    QGraphicsItem *upperRightArmItem = new RobotLimb(torsoItem);
-    QGraphicsItem *lowerRightArmItem = new RobotLimb(upperRightArmItem);
-    QGraphicsItem *upperRightLegItem = new RobotLimb(torsoItem);
-    QGraphicsItem *lowerRightLegItem = new RobotLimb(upperRightLegItem);
-    QGraphicsItem *upperLeftLegItem = new RobotLimb(torsoItem);
-    QGraphicsItem *lowerLeftLegItem = new RobotLimb(upperLeftLegItem);
-    
+    setFlag(ItemHasNoContents);
+
+    QGraphicsObject *torsoItem = new RobotTorso(this);
+    QGraphicsObject *headItem = new RobotHead(torsoItem);
+    QGraphicsObject *upperLeftArmItem = new RobotLimb(torsoItem);
+    QGraphicsObject *lowerLeftArmItem = new RobotLimb(upperLeftArmItem);
+    QGraphicsObject *upperRightArmItem = new RobotLimb(torsoItem);
+    QGraphicsObject *lowerRightArmItem = new RobotLimb(upperRightArmItem);
+    QGraphicsObject *upperRightLegItem = new RobotLimb(torsoItem);
+    QGraphicsObject *lowerRightLegItem = new RobotLimb(upperRightLegItem);
+    QGraphicsObject *upperLeftLegItem = new RobotLimb(torsoItem);
+    QGraphicsObject *lowerLeftLegItem = new RobotLimb(upperLeftLegItem);
+//! [10]
+
+//! [11]
     headItem->setPos(0, -18);
     upperLeftArmItem->setPos(-15, -10);
     lowerLeftArmItem->setPos(30, 0);
@@ -183,82 +221,78 @@ Robot::Robot()
     lowerRightLegItem->setPos(30, 0);
     upperLeftLegItem->setPos(-10, 32);
     lowerLeftLegItem->setPos(30, 0);
+//! [11]
 
-    timeLine = new QTimeLine;
-
-    QGraphicsItemAnimation *headAnimation = new QGraphicsItemAnimation;
-    headAnimation->setItem(headItem);
-    headAnimation->setTimeLine(timeLine);
-    headAnimation->setRotationAt(0, 20);
-    headAnimation->setRotationAt(1, -20);
-    headAnimation->setScaleAt(1, 1.1, 1.1);
-
-    QGraphicsItemAnimation *upperLeftArmAnimation = new QGraphicsItemAnimation;
-    upperLeftArmAnimation->setItem(upperLeftArmItem);
-    upperLeftArmAnimation->setTimeLine(timeLine);
-    upperLeftArmAnimation->setRotationAt(0, 190);
-    upperLeftArmAnimation->setRotationAt(1, 180);
-
-    QGraphicsItemAnimation *lowerLeftArmAnimation = new QGraphicsItemAnimation;
-    lowerLeftArmAnimation->setItem(lowerLeftArmItem);
-    lowerLeftArmAnimation->setTimeLine(timeLine);
-    lowerLeftArmAnimation->setRotationAt(0, 50);
-    lowerLeftArmAnimation->setRotationAt(1, 10);
-    
-    QGraphicsItemAnimation *upperRightArmAnimation = new QGraphicsItemAnimation;
-    upperRightArmAnimation->setItem(upperRightArmItem);
-    upperRightArmAnimation->setTimeLine(timeLine);
-    upperRightArmAnimation->setRotationAt(0, 300);
-    upperRightArmAnimation->setRotationAt(1, 310);
-
-    QGraphicsItemAnimation *lowerRightArmAnimation = new QGraphicsItemAnimation;
-    lowerRightArmAnimation->setItem(lowerRightArmItem);
-    lowerRightArmAnimation->setTimeLine(timeLine);
-    lowerRightArmAnimation->setRotationAt(0, 0);
-    lowerRightArmAnimation->setRotationAt(1, -70);
-
-    QGraphicsItemAnimation *upperLeftLegAnimation = new QGraphicsItemAnimation;
-    upperLeftLegAnimation->setItem(upperLeftLegItem);
-    upperLeftLegAnimation->setTimeLine(timeLine);
-    upperLeftLegAnimation->setRotationAt(0, 150);
-    upperLeftLegAnimation->setRotationAt(1, 80);
-
-    QGraphicsItemAnimation *lowerLeftLegAnimation = new QGraphicsItemAnimation;
-    lowerLeftLegAnimation->setItem(lowerLeftLegItem);
-    lowerLeftLegAnimation->setTimeLine(timeLine);
-    lowerLeftLegAnimation->setRotationAt(0, 70);
-    lowerLeftLegAnimation->setRotationAt(1, 10);
-
-    QGraphicsItemAnimation *upperRightLegAnimation = new QGraphicsItemAnimation;
-    upperRightLegAnimation->setItem(upperRightLegItem);
-    upperRightLegAnimation->setTimeLine(timeLine);
-    upperRightLegAnimation->setRotationAt(0, 40);
-    upperRightLegAnimation->setRotationAt(1, 120);
-    
-    QGraphicsItemAnimation *lowerRightLegAnimation = new QGraphicsItemAnimation;
-    lowerRightLegAnimation->setItem(lowerRightLegItem);
-    lowerRightLegAnimation->setTimeLine(timeLine);
-    lowerRightLegAnimation->setRotationAt(0, 10);
-    lowerRightLegAnimation->setRotationAt(1, 50);
-    
-    QGraphicsItemAnimation *torsoAnimation = new QGraphicsItemAnimation;
-    torsoAnimation->setItem(torsoItem);
-    torsoAnimation->setTimeLine(timeLine);
-    torsoAnimation->setRotationAt(0, 5);
-    torsoAnimation->setRotationAt(1, -20);
-
-    timeLine->setUpdateInterval(1000 / 25);
-    timeLine->setCurveShape(QTimeLine::SineCurve);
-    timeLine->setLoopCount(0);
-    timeLine->setDuration(2000);
-    timeLine->start();
-}
+//! [12]
+    QParallelAnimationGroup *animation = new QParallelAnimationGroup(this);
 
-Robot::~Robot()
-{
-    delete timeLine;
+    QPropertyAnimation *headAnimation = new QPropertyAnimation(headItem, "rotation");
+    headAnimation->setStartValue(20);
+    headAnimation->setEndValue(-20);
+    QPropertyAnimation *headScaleAnimation = new QPropertyAnimation(headItem, "scale");
+    headScaleAnimation->setEndValue(1.1);
+    animation->addAnimation(headAnimation);
+    animation->addAnimation(headScaleAnimation);
+//! [12]
+
+    QPropertyAnimation *upperLeftArmAnimation = new QPropertyAnimation(upperLeftArmItem, "rotation");
+    upperLeftArmAnimation->setStartValue(190);
+    upperLeftArmAnimation->setEndValue(180);
+    animation->addAnimation(upperLeftArmAnimation);
+
+    QPropertyAnimation *lowerLeftArmAnimation = new QPropertyAnimation(lowerLeftArmItem, "rotation");
+    lowerLeftArmAnimation->setStartValue(50);
+    lowerLeftArmAnimation->setEndValue(10);
+    animation->addAnimation(lowerLeftArmAnimation);
+
+    QPropertyAnimation *upperRightArmAnimation = new QPropertyAnimation(upperRightArmItem, "rotation");
+    upperRightArmAnimation->setStartValue(300);
+    upperRightArmAnimation->setEndValue(310);
+    animation->addAnimation(upperRightArmAnimation);
+
+    QPropertyAnimation *lowerRightArmAnimation = new QPropertyAnimation(lowerRightArmItem, "rotation");
+    lowerRightArmAnimation->setStartValue(0);
+    lowerRightArmAnimation->setEndValue(-70);
+    animation->addAnimation(lowerRightArmAnimation);
+
+    QPropertyAnimation *upperLeftLegAnimation = new QPropertyAnimation(upperLeftLegItem, "rotation");
+    upperLeftLegAnimation->setStartValue(150);
+    upperLeftLegAnimation->setEndValue(80);
+    animation->addAnimation(upperLeftLegAnimation);
+
+    QPropertyAnimation *lowerLeftLegAnimation = new QPropertyAnimation(lowerLeftLegItem, "rotation");
+    lowerLeftLegAnimation->setStartValue(70);
+    lowerLeftLegAnimation->setEndValue(10);
+    animation->addAnimation(lowerLeftLegAnimation);
+
+    QPropertyAnimation *upperRightLegAnimation = new QPropertyAnimation(upperRightLegItem, "rotation");
+    upperRightLegAnimation->setStartValue(40);
+    upperRightLegAnimation->setEndValue(120);
+    animation->addAnimation(upperRightLegAnimation);
+
+    QPropertyAnimation *lowerRightLegAnimation = new QPropertyAnimation(lowerRightLegItem, "rotation");
+    lowerRightLegAnimation->setStartValue(10);
+    lowerRightLegAnimation->setEndValue(50);
+    animation->addAnimation(lowerRightLegAnimation);
+
+    QPropertyAnimation *torsoAnimation = new QPropertyAnimation(torsoItem, "rotation");
+    torsoAnimation->setStartValue(5);
+    torsoAnimation->setEndValue(-20);
+    animation->addAnimation(torsoAnimation);
+
+//! [13]
+    for (int i = 0; i < animation->animationCount(); ++i) {
+        QPropertyAnimation *anim = qobject_cast<QPropertyAnimation *>(animation->animationAt(i));
+        anim->setEasingCurve(QEasingCurve::SineCurve);
+        anim->setDuration(2000);
+    }
+
+    animation->setLoopCount(-1);
+    animation->start();
+//! [13]
 }
 
+//! [9]
 QRectF Robot::boundingRect() const
 {
     return QRectF();
@@ -271,3 +305,4 @@ void Robot::paint(QPainter *painter,
     Q_UNUSED(option);
     Q_UNUSED(widget);
 }
+//! [9]
diff --git a/examples/graphicsview/dragdroprobot/robot.h b/examples/graphicsview/dragdroprobot/robot.h
index 88c4364..f5ff32c 100644
--- a/examples/graphicsview/dragdroprobot/robot.h
+++ b/examples/graphicsview/dragdroprobot/robot.h
@@ -46,10 +46,11 @@
 
 QT_BEGIN_NAMESPACE
 class QGraphicsSceneMouseEvent;
-class QTimeLine;
+class QParallelAnimationGroup;
 QT_END_NAMESPACE
 
-class RobotPart : public QGraphicsItem
+//! [0]
+class RobotPart : public QGraphicsObject
 {
 public:
     RobotPart(QGraphicsItem *parent = 0);
@@ -59,11 +60,12 @@ protected:
     void dragLeaveEvent(QGraphicsSceneDragDropEvent *event);
     void dropEvent(QGraphicsSceneDragDropEvent *event);
 
-    QPixmap pixmap;
     QColor color;
     bool dragOver;
 };
+//! [0]
 
+//! [1]
 class RobotHead : public RobotPart
 {
 public:
@@ -72,10 +74,16 @@ public:
     QRectF boundingRect() const;
     void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = 0);
 
-    enum { Type = UserType + 1 };
-    int type() const;
+protected:
+    void dragEnterEvent(QGraphicsSceneDragDropEvent *event);
+    void dropEvent(QGraphicsSceneDragDropEvent *event);
+
+private:
+    QPixmap pixmap;
 };
+//! [1]
 
+//! [2]
 class RobotTorso : public RobotPart
 {
 public:
@@ -84,7 +92,9 @@ public:
     QRectF boundingRect() const;
     void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = 0);
 };
+//! [2]
 
+//! [3]
 class RobotLimb : public RobotPart
 {
 public:
@@ -93,18 +103,17 @@ public:
     QRectF boundingRect() const;
     void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = 0);
 };
+//! [3]
 
+//! [4]
 class Robot : public RobotPart
 {
 public:
-    Robot();
-    ~Robot();
+    Robot(QGraphicsItem *parent = 0);
     
     QRectF boundingRect() const;
     void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = 0);
-
-private:
-    QTimeLine *timeLine;    
 };
+//! [4]
 
 #endif