Doc: Started to improve QML reference documentation.

4 files changed, 152 insertions, 63 deletions

diff --git a/doc/src/snippets/declarative/borderimage/normal-image.qml b/doc/src/snippets/declarative/borderimage/normal-image.qml
index adac4f3..76ec6e2 100644
--- a/doc/src/snippets/declarative/borderimage/normal-image.qml
+++ b/doc/src/snippets/declarative/borderimage/normal-image.qml
@@ -45,11 +45,11 @@ Rectangle {
     color: "white"
     width: 120; height: 120
 
-//! [scaled border image]
+//! [normal image]
 Image {
     source: "pics/borderframe.png"
 }
-//! [scaled border image]
+//! [normal image]
 
     Rectangle {
         x: 30; y: 0
diff --git a/src/declarative/graphicsitems/qdeclarativeanimatedimage.cpp b/src/declarative/graphicsitems/qdeclarativeanimatedimage.cpp
index e0a2149..16d1777 100644
--- a/src/declarative/graphicsitems/qdeclarativeanimatedimage.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeanimatedimage.cpp
@@ -63,35 +63,32 @@ QT_BEGIN_NAMESPACE
     \inherits Image
     \since 4.7
     \ingroup basic-visual-elements
-    
-    The AnimatedImage element provides for playing animations stored as images containing a series of frames,
-    such as GIF files. 
-    
+
+    The AnimatedImage element extends the features of the \l Image element, providing
+    a way to play animations stored as images containing a series of frames,
+    such as those stored in GIF files.
+
+    Information about the current frame and totla length of the animation can be
+    obtained using the \l currentFrame and \l frameCount properties. You can
+    start, pause and stop the animation by changing the values of the \l playing
+    and \l paused properties.
+
     The full list of supported formats can be determined with QMovie::supportedFormats().
 
-    \table
-    \row
-    \o \image animatedimageitem.gif
-    \o
-    \qml
-    import Qt 4.7
+    \section1 Example Usage
 
-    Rectangle {
-        width: animation.width; height: animation.height + 8
+    \beginfloatleft
+    \image animatedimageitem.gif
+    \endfloat
 
-        AnimatedImage { id: animation; source: "animation.gif" }
+    The following QML shows how to display an animated image and obtain information
+    about its state, such as the current frame and total number of frames.
+    The result is an animated image with a simple progress indicator underneath it.
 
-        Rectangle { 
-            property int frames: animation.frameCount
+    \clearfloat
+    \snippet doc/src/snippets/declarative/animatedimage.qml document
 
-            width: 4; height: 8
-            x: (animation.width - width) * animation.currentFrame / frames
-            y: animation.height
-            color: "red"
-        }
-    }
-    \endqml
-    \endtable
+    \sa BorderImage, Image
 */
 
 QDeclarativeAnimatedImage::QDeclarativeAnimatedImage(QDeclarativeItem *parent)
@@ -109,7 +106,8 @@ QDeclarativeAnimatedImage::~QDeclarativeAnimatedImage()
   \qmlproperty bool AnimatedImage::paused
   This property holds whether the animated image is paused.
 
-  Defaults to false, and can be set to true when you want to pause.
+  By default, this property is false. Set it to true when you want to pause
+  the animation.
 */
 bool QDeclarativeAnimatedImage::isPaused() const
 {
@@ -133,7 +131,8 @@ void QDeclarativeAnimatedImage::setPaused(bool pause)
   \qmlproperty bool AnimatedImage::playing
   This property holds whether the animated image is playing.
 
-  Defaults to true, so as to start playing immediately.
+  By defaults, this property is true, meaning that the animation
+  will start playing immediately.
 */
 bool QDeclarativeAnimatedImage::isPlaying() const
 {
@@ -161,9 +160,11 @@ void QDeclarativeAnimatedImage::setPlaying(bool play)
   \qmlproperty int AnimatedImage::currentFrame
   \qmlproperty int AnimatedImage::frameCount
 
-  currentFrame is the frame that is currently visible. Watching when this changes can
-  allow other things to animate at the same time as the image. frameCount is the number
-  of frames in the animation. For some animation formats, frameCount is unknown and set to zero.
+  currentFrame is the frame that is currently visible. By monitoring this property
+  for changes, you can animate other items at the same time as the image.
+
+  frameCount is the number of frames in the animation. For some animation formats,
+  frameCount is unknown and has a value of zero.
 */
 int QDeclarativeAnimatedImage::currentFrame() const
 {
diff --git a/src/declarative/graphicsitems/qdeclarativeborderimage.cpp b/src/declarative/graphicsitems/qdeclarativeborderimage.cpp
index e0c7fc2..5a9a18d 100644
--- a/src/declarative/graphicsitems/qdeclarativeborderimage.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeborderimage.cpp
@@ -56,27 +56,97 @@ QT_BEGIN_NAMESPACE
     \brief The BorderImage element provides an image that can be used as a border.
     \inherits Item
     \since 4.7
-    \ingroup qm-basic-visual-elements
+    \ingroup qml-basic-visual-elements
 
-    A BorderImage breaks an image into 9 sections, as shown below:
+    The BorderImage element is used to create borders out of images by scaling or tiling
+    parts of each image.
+
+    A BorderImage element breaks a source image, specified using the \l url property,
+    into 9 regions, as shown below:
 
     \image declarative-scalegrid.png
 
-    When the image is scaled:
+    When the image is scaled, regions of the source image are scaled or tiled to
+    create the displayed border image in the following way:
+
     \list
-    \i the corners (sections 1, 3, 7, and 9) are not scaled at all
-    \i sections 2 and 8 are scaled according to \l{BorderImage::horizontalTileMode}{horizontalTileMode}
-    \i sections 4 and 6 are scaled according to \l{BorderImage::verticalTileMode}{verticalTileMode}
-    \i the middle (section 5) is scaled according to both \l{BorderImage::horizontalTileMode}{horizontalTileMode} and \l{BorderImage::verticalTileMode}{verticalTileMode}
+    \i The corners (regions 1, 3, 7, and 9) are not scaled at all.
+    \i Regions 2 and 8 are scaled according to
+       \l{BorderImage::horizontalTileMode}{horizontalTileMode}.
+    \i Regions 4 and 6 are scaled according to
+       \l{BorderImage::verticalTileMode}{verticalTileMode}.
+    \i The middle (region 5) is scaled according to both
+       \l{BorderImage::horizontalTileMode}{horizontalTileMode} and
+       \l{BorderImage::verticalTileMode}{verticalTileMode}.
     \endlist
 
-    Examples:
-    \snippet snippets/declarative/borderimage.qml 0
+    The regions of the image are defined using the \l border property group, which
+    describes the distance from each edge of the source image to use as a border.
+
+    \section1 Example Usage
+
+    The following examples show the effects of the different modes on an image.
+    Guide lines are overlaid onto the image to show the different regions of the
+    image as described above.
+
+    \beginfloatleft
+    \image qml-borderimage-normal-image.png
+    \endfloat
+
+    An unscaled image is displayed using an Image element. The \l border property is
+    used to determine the parts of the image that will lie inside the unscaled corner
+    areas and the parts that will be stretched horizontally and vertically.
+
+    \snippet doc/src/snippets/declarative/borderimage/normal-image.qml normal image
+
+    \clearfloat
+    \beginfloatleft
+    \image qml-borderimage-scaled.png
+    \endfloat
+
+    A BorderImage element is used to display the image, and it is given a size that is
+    larger than the original image. Since the \l horizontalTileMode property is set to
+    \l{BorderImage::horizontalTileMode}{BorderImage.Stretch}, the parts of image in
+    regions 2 and 8 are stretched horizontally. Since the \l verticalTileMode property
+    is set to \l{BorderImage::verticalTileMode}{BorderImage.Stretch}, the parts of image
+    in regions 4 and 6 are stretched vertically.
+
+    \snippet doc/src/snippets/declarative/borderimage/borderimage-scaled.qml scaled border image
 
-    \image BorderImage.png
+    \clearfloat
+    \beginfloatleft
+    \image qml-borderimage-tiled.png
+    \endfloat
 
-    The \l{declarative/imageelements/borderimage}{BorderImage example} shows how a BorderImage can be used to simulate a shadow effect on a
-    rectangular item.
+    Again, a large BorderImage element is used to display the image. With the
+    \l horizontalTileMode property set to \l{BorderImage::horizontalTileMode}{BorderImage.Repeat},
+    the parts of image in regions 2 and 8 are tiled so that they fill the space at the
+    top and bottom of the element. Similarly, the \l verticalTileMode property is set to
+    \l{BorderImage::verticalTileMode}{BorderImage.Repeat}, the parts of image in regions
+    4 and 6 are tiled so that they fill the space at the left and right of the element.
+
+    \snippet doc/src/snippets/declarative/borderimage/borderimage-tiled.qml tiled border image
+
+    \clearfloat
+    In some situations, the width of regions 2 and 8 may not be an exact multiple of the width
+    of the corresponding regions in the source image. Similarly, the height of regions 4 and 6
+    may not be an exact multiple of the height of the corresponding regions. It can be useful
+    to use \l{BorderImage::horizontalTileMode}{BorderImage.Round} instead of
+    \l{BorderImage::horizontalTileMode}{BorderImage.Repeat} in cases like these.
+
+    The \l{declarative/imageelements/borderimage}{BorderImage example} shows how a BorderImage
+    can be used to simulate a shadow effect on a rectangular item.
+
+    \section1 Quality and Performance
+
+    By default, any scaled regions of the image are rendered without smoothing to improve
+    rendering speed. Setting the \l smooth property improves rendering quality of scaled
+    regions, but may slow down rendering.
+
+    The source image may not be loaded instantaneously, depending on its original location.
+    Loading progress can be monitored with the \l progress property.
+
+    \sa Image, AnimatedImage
  */
 
 /*!
@@ -127,6 +197,8 @@ QDeclarativeBorderImage::~QDeclarativeBorderImage()
     the image is displayed at its natural size, this property has no visual or
     performance effect.
 
+    By default, this property is set to false.
+
     \note Generally scaling artifacts are only visible if the image is stationary on
     the screen.  A common pattern when animating an image is to disable smooth
     filtering at the beginning of the animation and reenable it at the conclusion.
@@ -251,17 +323,21 @@ void QDeclarativeBorderImage::load()
     \qmlproperty int BorderImage::border.top
     \qmlproperty int BorderImage::border.bottom
 
-    The 4 border lines (2 horizontal and 2 vertical) break the image into 9 sections, as shown below:
+    The 4 border lines (2 horizontal and 2 vertical) break the image into 9 sections,
+    as shown below:
 
     \image declarative-scalegrid.png
 
-    Each border line (left, right, top, and bottom) specifies an offset in pixels from the respective side.
+    Each border line (left, right, top, and bottom) specifies an offset in pixels
+    from the respective edge of the source image. By default, each border line has
+    a value of 0.
+
+    For example, the following definition sets the bottom line 10 pixels up from
+    the bottom of the image:
 
-    For example:
     \qml
     border.bottom: 10
     \endqml
-    sets the bottom line 10 pixels up from the bottom of the image.
 
     The border lines can also be specified using a
     \l {BorderImage::source}{.sci file}.
diff --git a/src/declarative/graphicsitems/qdeclarativeimage.cpp b/src/declarative/graphicsitems/qdeclarativeimage.cpp
index 47a410c..eb8b00e 100644
--- a/src/declarative/graphicsitems/qdeclarativeimage.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeimage.cpp
@@ -51,34 +51,46 @@ QT_BEGIN_NAMESPACE
 /*!
     \qmlclass Image QDeclarativeImage
     \since 4.7
-    \ingroup qml-vasic-visual-elements
-
-    \brief The Image element allows you to add bitmaps to a scene.
+    \ingroup qml-basic-visual-elements
+    \brief The Image element displays an image in a declarative user interface
     \inherits Item
 
-    An Image element displays a specified \l source image:
+    The Image element is used to display images in a declarative user interface.
 
-    \table
-    \row
-    \o \image declarative-qtlogo.png
-    \o \qml
-        import Qt 4.7
+    The source of the image is specified as a URL using the \l source property.
+    Images can be supplied in any of the standard image formats supported by Qt,
+    including bitmap formats such as PNG and JPEG, and vector graphics formats
+    such as SVG. If you need to display animated images, use the \l AnimatedImage
+    element.
 
-        Image { source: "qtlogo.png" }
-    \endqml
-    \endtable
+    If the \l{Item::width}{width} and \l{Item::height}{height} properties are not
+    specified, the Image element automatically uses the size of the loaded image.
+    By default, specifying the width and height of the element causes the image
+    to be scaled to that size. This behavior can be changed by setting the
+    \l fillMode property, allowing the image to be stretched and tiled instead.
+
+    \section1 Example Usage
+
+    The following example shows the simplest usage of the Image element.
+
+    \snippet doc/src/snippets/declarative/image.qml
+
+    \beginfloatleft
+    \image declarative-qtlogo.png
+    \endfloat
+
+    \clearfloat
 
-    If the \l {Item::width}{width} and \l{Item::height}{height} properties are not specified,
-    the Image element is automatically sized to the loaded image. Image elements can be 
-    stretched and tiled using the \l fillMode property.
+    \section1 Performance
 
     By default, locally available images are loaded immediately, and the user interface
     is blocked until loading is complete. If a large image is to be loaded, it may be
     preferable to load the image in a low priority thread, by enabling the \l asynchronous
     property.
 
-    If the image is from a network rather than a local resource, it is automatically loaded
-    asynchronously, and the \l progress and \l status properties are updated as appropriate.  
+    If the image is obtained from a network rather than a local resource, it is
+    automatically loaded asynchronously, and the \l progress and \l status properties
+    are updated as appropriate.
 
     Images are cached and shared internally, so if several Image elements have the same \l source,
     only one copy of the image will be loaded.