Merge branch 'kinetic-declarativeui' of git@scm.dev.nokia.troll.no:qt/kinetic into kinetic-declarativeui

13 files changed, 149 insertions, 75 deletions

diff --git a/src/declarative/fx/qfxblendedimage.cpp b/src/declarative/fx/qfxblendedimage.cpp
index 9a3bb72..b5d9a9a 100644
--- a/src/declarative/fx/qfxblendedimage.cpp
+++ b/src/declarative/fx/qfxblendedimage.cpp
@@ -49,12 +49,24 @@
 QT_BEGIN_NAMESPACE
 
 /*!
+    \qmlclass BlendedImage
+    \brief The BlendedImage elements blends two different images depending on a blend ratio.
+
+    This element can be used to simulate blur on slow devices by setting secondaryUrl with
+    a pre-rendered blurred version of primaryUrl.
+
+    Note that this class will only work under OpenGL. On the software canvas it will display
+    only the primary image unless the blend is > 0.75, in which case it will display only the
+    secondary image.
+*/
+
+/*!
     \internal
     \class QFxBlendedImage
     \brief The QFxBlendedImage blends two different images depending on a blend ratio.
 
-    This class can be used to simulate blur on slow devices by setting secondaryFile with
-    a pre-rendered blurred version of primaryFile.
+    This class can be used to simulate blur on slow devices by setting secondaryUrl with
+    a pre-rendered blurred version of primaryUrl.
 
     Note that this class will only work under OpenGL. On the software canvas it will display
     only the primary image unless the blend is > 0.75, in which case it will display only the
@@ -69,8 +81,8 @@ QFxBlendedImage::QFxBlendedImage(QFxItem *parent)
 }
 
 /*!
-    \property QFxBlendedImage::primaryUrl
-    \brief the URL of the first image to be displayed in this item.
+    \qmlproperty string BlendedImage::primaryUrl
+    The URL of the first image to be displayed in this item.
 */
 QString QFxBlendedImage::primaryUrl() const
 {
@@ -97,8 +109,8 @@ void QFxBlendedImage::setPrimaryUrl(const QString &url)
 }
 
 /*!
-    \property QFxBlendedImage::secondaryUrl
-    \brief the URL of the second image to be displayed in this item.
+    \qmlproperty string BlendedImage::secondaryUrl
+    The URL of the second image to be displayed in this item.
 */
 QString QFxBlendedImage::secondaryUrl() const
 {
@@ -125,8 +137,8 @@ void QFxBlendedImage::setSecondaryUrl(const QString &url)
 }
 
 /*!
-    \property QFxBlendedImage::blend
-    \brief the ratio used to blend the two images.
+    \qmlproperty real BlendedImage::blend
+    The ratio used to blend the two images.
 
     If blend has a value of 0, only the first image will be displayed.
     If blend has a value of 1, only the second image will be displayed.
@@ -246,4 +258,5 @@ void QFxBlendedImage::paintGLContents(GLPainter &p)
 #endif
 
 QML_DEFINE_TYPE(QFxBlendedImage,BlendedImage);
+
 QT_END_NAMESPACE
diff --git a/src/declarative/fx/qfxitem.cpp b/src/declarative/fx/qfxitem.cpp
index ed65b84..6b4c504 100644
--- a/src/declarative/fx/qfxitem.cpp
+++ b/src/declarative/fx/qfxitem.cpp
@@ -838,23 +838,6 @@ void QFxItem::qmlLoaded()
 }
 
 /*!
-  \qmlproperty Item Item::clipToItem
-
-  Experimental clip to item support.  Do not use.
-
-  \todo complete clip to item support.
- */
-QFxItem *QFxItem::clipToItem() const
-{
-    return 0;
-}
-
-void QFxItem::setClipToItem(QFxItem *)
-{
-    qWarning() << "QFxItem: clipToItem not implemented";
-}
-
-/*!
   \qmlproperty real Item::x
   \qmlproperty real Item::y
   \qmlproperty int Item::width
@@ -1361,7 +1344,7 @@ void QFxItem::setScale(qreal s)
   Opacity is an \e inherited attribute.  That is, the opacity is
   also applied individually to child items.  In almost all cases this
   is what you want.  If you can spot the issue in the following
-  example, you might need to use an opacity filter instead.
+  example, you might need to use an opacity filter (not yet available) instead.
 
   \table
   \row
@@ -1385,8 +1368,6 @@ void QFxItem::setScale(qreal s)
   </Item>
   \endqml
   \endtable
-
-  \todo There is no such thing as an opacity filter
 */
 
 qreal QFxItem::opacity() const
@@ -1488,8 +1469,8 @@ QmlList<QmlTransition *>* QFxItem::transitions()
   \qmlproperty list<Filter> Item::filter
   This property holds a list of graphical filters to be applied to the item.
 
-  \l {qmlfilter}{Filters} include things like \l {qmlblur}{blurring}
-  the item, or giving it a Reflection.  Some
+  \l {Filter}{Filters} include things like \l {Blur}{blurring}
+  the item, or giving it a \l Reflection.  Some
   filters may not be available on all canvases; if a filter is not
   available on a certain canvas, it will simply not be applied for
   that canvas (but the XML will still be considered valid).
@@ -1677,7 +1658,7 @@ void QFxItem::classBegin()
 void QFxItem::classComplete()
 {
 #ifdef Q_ENABLE_PERFORMANCE_LOG
-    QFxPerfTimer<QFxPerf::ItemClassComplete> cc;
+    QFxPerfTimer<QFxPerf::ItemComponentComplete> cc;
 #endif
     Q_D(QFxItem);
     d->_classComplete = true;
diff --git a/src/declarative/fx/qfxitem.h b/src/declarative/fx/qfxitem.h
index d3b9899..c47a1e1 100644
--- a/src/declarative/fx/qfxitem.h
+++ b/src/declarative/fx/qfxitem.h
@@ -113,7 +113,6 @@ class Q_DECLARATIVE_EXPORT QFxItem : public QSimpleCanvasItem, public QmlParserS
     Q_PROPERTY(QString state READ state WRITE setState NOTIFY stateChanged)
     Q_PROPERTY(QString qml READ qml WRITE setQml NOTIFY qmlChanged)
     Q_PROPERTY(QFxItem *qmlItem READ qmlItem NOTIFY qmlChanged)
-    Q_PROPERTY(QFxItem *clipToItem READ clipToItem WRITE setClipToItem)
     Q_PROPERTY(qreal x READ x WRITE setX NOTIFY leftChanged)
     Q_PROPERTY(qreal y READ y WRITE setY NOTIFY topChanged)
     Q_PROPERTY(qreal z READ z WRITE setZ)
@@ -174,9 +173,6 @@ public:
     QString qml() const;
     void setQml(const QString &);
 
-    QFxItem *clipToItem() const;
-    void setClipToItem(QFxItem *i);
-
     bool flipVertically() const;
     void setFlipVertically(bool);
     bool flipHorizontally() const;
diff --git a/src/declarative/fx/qfxpainted.cpp b/src/declarative/fx/qfxpainted.cpp
index 8109efa..ad1b3ad 100644
--- a/src/declarative/fx/qfxpainted.cpp
+++ b/src/declarative/fx/qfxpainted.cpp
@@ -77,13 +77,12 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    Constructs the painted item.
+    Constructs a painted item with parent object \a parent.
 */
-
-//### what options do we need to set?
 QFxPainted::QFxPainted(QFxItem *parent)
   : QFxItem(*(new QFxPaintedPrivate), parent)
 {
+    //### what options do we need to set?
     setOptions(HasContents, true);
 }
 
@@ -105,8 +104,9 @@ QFxPainted::QFxPainted(QFxPaintedPrivate &dd, QFxItem *parent)
 /*!
     \fn QFxPainted::paint(QPainter *painter)
 
-    Implement this method to paint the item.  The painting will be cached and
-    paint() will only be called again if \l markDirty() has been called.
+    Implement this method to paint the item using \a painter.
+    The painting will be cached and paint() will only be called again
+    if \l markDirty() has been called.
 
     \sa markDirty()
 */
diff --git a/src/declarative/fx/qfxparticles.cpp b/src/declarative/fx/qfxparticles.cpp
index 939afba..9319c46 100644
--- a/src/declarative/fx/qfxparticles.cpp
+++ b/src/declarative/fx/qfxparticles.cpp
@@ -917,7 +917,7 @@ void QFxParticles::setStreamIn(bool b)
   will be produced until it is set to true.
 */
 /*!
-  \property bool Particles::emitting
+  \property QFxParticles::emitting
   If emitting is set to false no new particles will be created. This means that
   when a particle reaches the end of its lifespan it is not replaced. This
   property can be used to turn particles on and off with a more natural look.
diff --git a/src/declarative/fx/qfxpath.cpp b/src/declarative/fx/qfxpath.cpp
index 14c06bb..06c9f2b 100644
--- a/src/declarative/fx/qfxpath.cpp
+++ b/src/declarative/fx/qfxpath.cpp
@@ -462,8 +462,43 @@ void QFxCurve::setY(int y)
 /****************************************************************************/
 
 /*!
-   \qmlclass PathAttribute
-   \brief The PathAttribute allows to set an attribute at a given position in the path.
+    \qmlclass PathAttribute
+    \brief The PathAttribute allows setting an attribute at a given position in a Path.
+
+    The PathAttribute element allows attibutes consisting of a name and a
+    value to be specified for the endpoints of path segments.  The attributes
+    are exposed to the delegate as \l {Attached Properties}.  The value of
+    an attribute at any particular point is interpolated from the PathAttributes
+    bounding the point.
+
+    The example below shows a path with the items scaled to 10% at the ends of
+    the path and scaled 100% along the PathLine in the middle.  Note the use
+    of the PathView.scale attached property to set the scale of the delegate.
+    \table
+    \row
+    \o \image declarative-pathattribute.png
+    \o
+    \code
+    <Component id="Delegate">
+        <Rect id="Wrapper" width="20" height="20" scale="{PathView.scale}" color="steelblue"/>
+    </Component>
+    <PathView width="200" height="100" model="{Model}" delegate="{Delegate}">
+        <path>
+            <Path startX="20" startY="0">
+                <PathAttribute name="scale" value="0.1"/>
+                <PathQuad x="50" y="80" controlX="0" controlY="80"/>
+                <PathAttribute name="scale" value="1"/>
+                <PathLine x="150" y="80"/>
+                <PathAttribute name="scale" value="1"/>
+                <PathQuad x="180" y="0" controlX="200" controlY="80"/>
+                <PathAttribute name="scale" value="0.1"/>
+            </Path>
+        </path>
+    </PathView>
+    \endcode
+    \endtable
+
+   \sa Path
 */
 
 /*!
@@ -519,8 +554,19 @@ void QFxPathAttribute::setValue(qreal value)
 /****************************************************************************/
 
 /*!
-   \qmlclass PathLine
-   \brief The PathLine defines a straight line.
+    \qmlclass PathLine
+    \brief The PathLine defines a straight line.
+
+    The example below creates a path consisting of a straight line from
+    0,100 to 200,100:
+
+    \code
+    <Path startX="0" startY="100">
+        <PathLine x="200" y="100"/>
+    </Path>
+    \endcode
+
+    \sa Path, PathQuad, PathCubic
 
 */
 
@@ -541,9 +587,22 @@ void QFxPathLine::addToPath(QPainterPath &path)
 /****************************************************************************/
 
 /*!
-   \qmlclass PathQuad
-   \brief The PathQuad defines a quadratic Bezier curve with a control point.
+    \qmlclass PathQuad
+    \brief The PathQuad defines a quadratic Bezier curve with a control point.
+
+    The following QML produces the path shown below:
+    \table
+    \row
+    \o \image declarative-pathquad.png
+    \o
+    \code
+    <Path startX="0" startY="0">
+        <PathQuad x="200" y="0" controlX="100" controlY="150"/>
+    </Path>
+    \endcode
+    \endtable
 
+    \sa Path, PathCubic, PathLine
 */
 
 /*!
@@ -557,7 +616,7 @@ void QFxPathLine::addToPath(QPainterPath &path)
 
 /*!
    \qmlproperty string PathQuad::controlX
-   the x position of the control point.
+   The x position of the control point.
 */
 
 /*!
@@ -578,7 +637,7 @@ void QFxPathQuad::setControlX(int x)
 
 /*!
    \qmlproperty string PathQuad::controlY
-   the y position of the control point.
+   The y position of the control point.
 */
 
 /*!
@@ -608,6 +667,20 @@ void QFxPathQuad::addToPath(QPainterPath &path)
    \qmlclass PathCubic
    \brief The PathCubic defines a cubic Bezier curve with two control points.
 
+    The following QML produces the path shown below:
+    \table
+    \row
+    \o \image declarative-pathcubic.png
+    \o
+    \code
+    <Path startX="20" startY="0">
+         <PathCubic x="180" y="0" control1X="-10" control1Y="90"
+                    control2X="210" control2Y="90"/>
+    </Path>
+    \endcode
+    \endtable
+
+    \sa Path, PathQuad, PathLine
 */
 
 /*!
@@ -715,9 +788,39 @@ void QFxPathCubic::addToPath(QPainterPath &path)
 /****************************************************************************/
 
 /*!
-   \qmlclass PathPercent
-   \brief The PathPercent manipulates the way a path is interpreted.
+    \qmlclass PathPercent
+    \brief The PathPercent manipulates the way a path is interpreted.
+
+    The examples below show the normal distrubution of items along a path
+    compared to a distribution which places 50% of the items along the
+    PathLine section of the path.
+    \table
+    \row
+    \o \image declarative-nopercent.png
+    \o
+    \code
+    <Path startX="20" startY="0">
+        <PathQuad x="50" y="80" controlX="0" controlY="80"/>
+        <PathLine x="150" y="80"/>
+        <PathQuad x="180" y="0" controlX="200" controlY="80"/>
+    </Path>
+    \endcode
+    \row
+    \o \image declarative-percent.png
+    \o
+    \code
+    <Path startX="20" startY="0">
+        <PathQuad x="50" y="80" controlX="0" controlY="80"/>
+        <PathPercent value=".25"/>
+        <PathLine x="150" y="80"/>
+        <PathPercent value=".75"/>
+        <PathQuad x="180" y="0" controlX="200" controlY="80"/>
+        <PathPercent value="1"/>
+    </Path>
+    \endcode
+    \endtable
 
+    \sa Path
 */
 
 /*!
diff --git a/src/declarative/fx/qfxrect.cpp b/src/declarative/fx/qfxrect.cpp
index 2e84c74..a761ec5 100644
--- a/src/declarative/fx/qfxrect.cpp
+++ b/src/declarative/fx/qfxrect.cpp
@@ -70,10 +70,7 @@ QML_DEFINE_TYPE(QFxPen,Pen);
     \brief the color of the pen.
 
     color is most commonly specified in hexidecimal notation (#RRGGBB)
-    or as an
-    \htmlonly
-    <a href="http://www.w3.org/TR/SVG/types.html#ColorKeywords"> SVG color keyword name</a>
-    \endhtmlonly
+    or as an \l {http://www.w3.org/TR/SVG/types.html#ColorKeywords}{SVG color keyword name}
      (as defined by the World Wide Web Consortium). For example:
     \code
     <!-- rect with green border using hexidecimal notation -->
diff --git a/src/declarative/fx/qfxreflectionfilter.cpp b/src/declarative/fx/qfxreflectionfilter.cpp
index d67095b..39342d7 100644
--- a/src/declarative/fx/qfxreflectionfilter.cpp
+++ b/src/declarative/fx/qfxreflectionfilter.cpp
@@ -103,9 +103,6 @@ public:
 
     Reflection is only supported when Qt Declarative is compiled for OpenGL ES 2.0.
     Otherwise the Reflection filter has no effect.
-    
-    \todo describe (and fix) reflection and bounding box interaction
-
 */
 
 /*!
diff --git a/src/declarative/fx/qfxrepeater.cpp b/src/declarative/fx/qfxrepeater.cpp
index ec1d88c..570d54d 100644
--- a/src/declarative/fx/qfxrepeater.cpp
+++ b/src/declarative/fx/qfxrepeater.cpp
@@ -110,13 +110,7 @@ QML_DEFINE_TYPE(QFxRepeater,Repeater);
 
     The repeater instance continues to own all items it instantiates, even
     if they are otherwise manipulated.  It is illegal to manually remove an item
-    created by the Repeater.  
-
-    \todo Repeater is very conservative in how it instatiates/deletes items.  
-    Also new model entries will not be created and old ones will not be removed.
-
-    \todo Need an example
-
+    created by the Repeater.
  */
 
 /*!
diff --git a/src/declarative/fx/qfxtext.cpp b/src/declarative/fx/qfxtext.cpp
index bc03d7c..e7085d8 100644
--- a/src/declarative/fx/qfxtext.cpp
+++ b/src/declarative/fx/qfxtext.cpp
@@ -85,8 +85,6 @@ QML_DEFINE_TYPE(QFxText,Text);
     plain text to a set width.
 
     Text provides read-only text. For editable text, see \l TextEdit.
-
-    \todo explain details of auto-sizing
 */
 
 /*!
diff --git a/src/declarative/fx/qfxtextedit.cpp b/src/declarative/fx/qfxtextedit.cpp
index 96ebe0d..7efb826 100644
--- a/src/declarative/fx/qfxtextedit.cpp
+++ b/src/declarative/fx/qfxtextedit.cpp
@@ -294,7 +294,7 @@ void QFxTextEdit::setColor(const QColor &color)
 */
 
 /*!
-    \property QFxText::hAlign
+    \property QFxTextEdit::hAlign
     \brief the horizontal alignment of the text.
 
     Valid values are \c AlignLeft, \c AlignRight, and \c AlignHCenter. The default value is \c AlignLeft.
@@ -316,7 +316,7 @@ void QFxTextEdit::setHAlign(QFxTextEdit::HAlignment alignment)
 }
 
 /*!
-    \property QFxText::vAlign
+    \property QFxTextEdit::vAlign
     \brief the vertical alignment of the text.
 
     Valid values are \c AlignTop, \c AlignBottom, and \c AlignVCenter. The default value is \c AlignTop.
diff --git a/src/declarative/fx/qfxtransform.cpp b/src/declarative/fx/qfxtransform.cpp
index 90875a6..a001214 100644
--- a/src/declarative/fx/qfxtransform.cpp
+++ b/src/declarative/fx/qfxtransform.cpp
@@ -56,8 +56,6 @@ QML_DEFINE_TYPE(QFxTransform,Transform);
 /*!
     \qmlclass Transform
     \brief A transformation.
-
-    \todo Document Transform.
 */
 QFxTransform::QFxTransform(QObject *parent) :
     QObject(parent)
@@ -334,9 +332,6 @@ public:
     \endcode
 
     \image flipable.gif
-
-    \todo A lot needs to be done to get a fully-functioning Flipable. Should we simplify?
-
 */
 
 /*!
diff --git a/src/declarative/fx/qfxwidgetcontainer.cpp b/src/declarative/fx/qfxwidgetcontainer.cpp
index 44ccf0f..f86c8dc 100644
--- a/src/declarative/fx/qfxwidgetcontainer.cpp
+++ b/src/declarative/fx/qfxwidgetcontainer.cpp
@@ -73,7 +73,7 @@ QGraphicsWidget *QFxWidgetContainer::graphicsWidget() const
 }
 
 /*!
-    \property QGraphicsWidget QFxWidgetContainer::graphicsWidget
+    \qmlproperty QGraphicsWidget QFxWidgetContainer::graphicsWidget
     The QGraphicsWidget associated with this element.
 */
 void QFxWidgetContainer::setGraphicsWidget(QGraphicsWidget *widget)