Add documentation for QSGImage

Change-Id: I1cfae5fb57025372789391632bac4cb97b8450dc
Reviewed-on: http://codereview.qt.nokia.com/1684
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Yann Bodson <yann.bodson@nokia.com>

diff --git a/src/declarative/items/qsgimage.cpp b/src/declarative/items/qsgimage.cpp
index b77a654..ed55104 100644 (file)
--- a/src/declarative/items/qsgimage.cpp
+++ b/src/declarative/items/qsgimage.cpp
@@ -60,6 +60,62 @@ QSGImagePrivate::QSGImagePrivate()
 {
 }
 
+/*!
+    \qmlclass Image QSGImage
+    \since QtQuick 1.0
+    \inqmlmodule QtQuick 2
+    \ingroup qml-basic-visual-elements
+    \brief The Image element displays an image in a declarative user interface
+    \inherits Item
+
+    The Image element is used to display images in a declarative user interface.
+
+    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.
+
+    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 document
+
+    \beginfloatleft
+    \image declarative-qtlogo.png
+    \endfloat
+
+    \clearfloat
+
+    \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 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.
+
+    \bold Note: Images are often the greatest user of memory in QML user interfaces.  It is recommended
+    that images which do not form part of the user interface have their
+    size bounded via the \l sourceSize property. This is especially important for content
+    that is loaded from external sources or provided by the user.
+
+    \sa {declarative/imageelements/image}{Image example}, QDeclarativeImageProvider
+*/
+
 QSGImage::QSGImage(QSGItem *parent)
     : QSGImageBase(*(new QSGImagePrivate), parent)
 {
@@ -85,6 +141,102 @@ void QSGImagePrivate::setPixmap(const QPixmap &pixmap)
     q->update();
 }
 
+/*!
+    \qmlproperty enumeration QtQuick2::Image::fillMode
+
+    Set this property to define what happens when the source image has a different size
+    than the item.
+
+    \list
+    \o Image.Stretch - the image is scaled to fit
+    \o Image.PreserveAspectFit - the image is scaled uniformly to fit without cropping
+    \o Image.PreserveAspectCrop - the image is scaled uniformly to fill, cropping if necessary
+    \o Image.Tile - the image is duplicated horizontally and vertically
+    \o Image.TileVertically - the image is stretched horizontally and tiled vertically
+    \o Image.TileHorizontally - the image is stretched vertically and tiled horizontally
+    \o Image.Pad - the image is not transformed
+    \endlist
+
+    \table
+
+    \row
+    \o \image declarative-qtlogo-stretch.png
+    \o Stretch (default)
+    \qml
+    Image {
+        width: 130; height: 100
+        smooth: true
+        source: "qtlogo.png"
+    }
+    \endqml
+
+    \row
+    \o \image declarative-qtlogo-preserveaspectfit.png
+    \o PreserveAspectFit
+    \qml
+    Image {
+        width: 130; height: 100
+        fillMode: Image.PreserveAspectFit
+        smooth: true
+        source: "qtlogo.png"
+    }
+    \endqml
+
+    \row
+    \o \image declarative-qtlogo-preserveaspectcrop.png
+    \o PreserveAspectCrop
+    \qml
+    Image {
+        width: 130; height: 100
+        fillMode: Image.PreserveAspectCrop
+        smooth: true
+        source: "qtlogo.png"
+        clip: true
+    }
+    \endqml
+
+    \row
+    \o \image declarative-qtlogo-tile.png
+    \o Tile
+    \qml
+    Image {
+        width: 120; height: 120
+        fillMode: Image.Tile
+        source: "qtlogo.png"
+    }
+    \endqml
+
+    \row
+    \o \image declarative-qtlogo-tilevertically.png
+    \o TileVertically
+    \qml
+    Image {
+        width: 120; height: 120
+        fillMode: Image.TileVertically
+        smooth: true
+        source: "qtlogo.png"
+    }
+    \endqml
+
+    \row
+    \o \image declarative-qtlogo-tilehorizontally.png
+    \o TileHorizontally
+    \qml
+    Image {
+        width: 120; height: 120
+        fillMode: Image.TileHorizontally
+        smooth: true
+        source: "qtlogo.png"
+    }
+    \endqml
+
+    \endtable
+
+    Note that \c clip is \c false by default which means that the element might
+    paint outside its bounding rectangle even if the fillMode is set to \c PreserveAspectCrop.
+
+    \sa {declarative/imageelements/image}{Image example}
+*/
 QSGImage::FillMode QSGImage::fillMode() const
 {
     Q_D(const QSGImage);
@@ -102,6 +254,17 @@ void QSGImage::setFillMode(FillMode mode)
     emit fillModeChanged();
 }
 
+/*!
+
+    \qmlproperty real QtQuick2::Image::paintedWidth
+    \qmlproperty real QtQuick2::Image::paintedHeight
+
+    These properties hold the size of the image that is actually painted.
+    In most cases it is the same as \c width and \c height, but when using a
+    \c fillMode \c PreserveAspectFit or \c fillMode \c PreserveAspectCrop
+    \c paintedWidth or \c paintedHeight can be smaller or larger than
+    \c width and \c height of the Image element.
+*/
 qreal QSGImage::paintedWidth() const
 {
     Q_D(const QSGImage);
@@ -114,6 +277,167 @@ qreal QSGImage::paintedHeight() const
     return d->paintedHeight;
 }
 
+/*!
+    \qmlproperty enumeration QtQuick2::Image::status
+
+    This property holds the status of image loading.  It can be one of:
+    \list
+    \o Image.Null - no image has been set
+    \o Image.Ready - the image has been loaded
+    \o Image.Loading - the image is currently being loaded
+    \o Image.Error - an error occurred while loading the image
+    \endlist
+
+    Use this status to provide an update or respond to the status change in some way.
+    For example, you could:
+
+    \list
+    \o Trigger a state change:
+    \qml
+        State { name: 'loaded'; when: image.status == Image.Ready }
+    \endqml
+
+    \o Implement an \c onStatusChanged signal handler:
+    \qml
+        Image {
+            id: image
+            onStatusChanged: if (image.status == Image.Ready) console.log('Loaded')
+        }
+    \endqml
+
+    \o Bind to the status value:
+    \qml
+        Text { text: image.status == Image.Ready ? 'Loaded' : 'Not loaded' }
+    \endqml
+    \endlist
+
+    \sa progress
+*/
+
+/*!
+    \qmlproperty real QtQuick2::Image::progress
+
+    This property holds the progress of image loading, from 0.0 (nothing loaded)
+    to 1.0 (finished).
+
+    \sa status
+*/
+
+/*!
+    \qmlproperty bool QtQuick2::Image::smooth
+
+    Set this property if you want the image to be smoothly filtered when scaled or
+    transformed.  Smooth filtering gives better visual quality, but is slower.  If
+    the image is displayed at its natural size, this property has no visual or
+    performance effect.
+
+    \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.
+*/
+
+/*!
+    \qmlproperty QSize QtQuick2::Image::sourceSize
+
+    This property holds the actual width and height of the loaded image.
+
+    Unlike the \l {Item::}{width} and \l {Item::}{height} properties, which scale
+    the painting of the image, this property sets the actual number of pixels
+    stored for the loaded image so that large images do not use more
+    memory than necessary. For example, this ensures the image in memory is no
+    larger than 1024x1024 pixels, regardless of the Image's \l {Item::}{width} and
+    \l {Item::}{height} values:
+
+    \code
+    Rectangle {
+        width: ...
+        height: ...
+
+        Image {
+           anchors.fill: parent
+           source: "reallyBigImage.jpg"
+           sourceSize.width: 1024
+           sourceSize.height: 1024
+        }
+    }
+    \endcode
+
+    If the image's actual size is larger than the sourceSize, the image is scaled down.
+    If only one dimension of the size is set to greater than 0, the
+    other dimension is set in proportion to preserve the source image's aspect ratio.
+    (The \l fillMode is independent of this.)
+
+    If the source is an instrinsically scalable image (eg. SVG), this property
+    determines the size of the loaded image regardless of intrinsic size.
+    Avoid changing this property dynamically; rendering an SVG is \e slow compared
+    to an image.
+
+    If the source is a non-scalable image (eg. JPEG), the loaded image will
+    be no greater than this property specifies. For some formats (currently only JPEG),
+    the whole image will never actually be loaded into memory.
+
+    Since QtQuick 1.1 the sourceSize can be cleared to the natural size of the image
+    by setting sourceSize to \c undefined.
+
+    \note \e {Changing this property dynamically causes the image source to be reloaded,
+    potentially even from the network, if it is not in the disk cache.}
+*/
+
+/*!
+    \qmlproperty url QtQuick2::Image::source
+
+    Image can handle any image format supported by Qt, loaded from any URL scheme supported by Qt.
+
+    The URL may be absolute, or relative to the URL of the component.
+
+    \sa QDeclarativeImageProvider
+*/
+
+/*!
+    \qmlproperty bool QtQuick2::Image::asynchronous
+
+    Specifies that images on the local filesystem should be loaded
+    asynchronously in a separate thread.  The default value is
+    false, causing the user interface thread to block while the
+    image is loaded.  Setting \a asynchronous to true is useful where
+    maintaining a responsive user interface is more desirable
+    than having images immediately visible.
+
+    Note that this property is only valid for images read from the
+    local filesystem.  Images loaded via a network resource (e.g. HTTP)
+    are always loaded asynchonously.
+*/
+
+/*!
+    \qmlproperty bool QtQuick2::Image::cache
+    \since Quick 1.1
+
+    Specifies whether the image should be cached. The default value is
+    true. Setting \a cache to false is useful when dealing with large images,
+    to make sure that they aren't cached at the expense of small 'ui element' images.
+*/
+
+/*!
+    \qmlproperty bool QtQuick2::Image::mirror
+    \since Quick 1.1
+
+    This property holds whether the image should be horizontally inverted
+    (effectively displaying a mirrored image).
+
+    The default value is false.
+*/
+
+/*!
+    \qmlproperty enumeration QtQuick2::Image::horizontalAlignment
+    \qmlproperty enumeration QtQuick2::Image::verticalAlignment
+    \since Quick 2.0
+
+    Sets the horizontal and vertical alignment of the image. By default, the image is top-left aligned.
+
+    The valid values for \c horizontalAlignment are \c Image.AlignLeft, \c Image.AlignRight and \c Image.AlignHCenter.
+    The valid values for \c verticalAlignment are \c Image.AlignTop, \c Image.AlignBottom
+    and \c Image.AlignVCenter.
+*/
 void QSGImage::updatePaintedGeometry()
 {
     Q_D(QSGImage);