Doc: add documentation for Photo Viewer example

Change-Id: Iffedd9361bd0475a53c1a8b9567c9cbf5e5d4867
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>

1 files changed, 288 insertions, 3 deletions

diff --git a/examples/quick/demos/photoviewer/doc/src/photoviewer.qdoc b/examples/quick/demos/photoviewer/doc/src/photoviewer.qdoc
index 29c432be3c..ac56cb2b7a 100644
--- a/examples/quick/demos/photoviewer/doc/src/photoviewer.qdoc
+++ b/examples/quick/demos/photoviewer/doc/src/photoviewer.qdoc
@@ -29,13 +29,298 @@
     \title Qt Quick Demo - Photo Viewer
     \ingroup qtquickdemos
     \example demos/photoviewer
-    \brief A photo viewer that displays Flickr feeds.
+    \brief A QML photo viewer that that uses XmlListModel and XmlRole to
+    download Flickr feeds, and Package to display the photos in different views.
+
     \image qtquick-demo-photoviewer-small.png
 
-    \e{Photo Viewer} demonstrates various QML and \l{Qt Quick} features such as
-    displaying custom components.
+    \e{Photo Viewer} demonstrates the following \l{Qt Quick} features:
+
+    \list
+        \li Using custom types to create screens and screen controls.
+        \li Using Qt Quick Controls to create an application window.
+        \li Using the \l Package type with a \l DelegateModel to provide
+            delegates with a shared context to multiple views.
+        \li Using XML list models to download Flickr feeds.
+        \li Using the \l Flipable type to create labels with different text on
+            the front and back.
+        \li Using the PathView, \l Path, PathAttribute, and PathLine types to
+            lay out photos on a path.
+        \li Providing feedback to users while data is loading.
+        \li Localizing applications.
+    \endlist
 
     \include examples-run.qdocinc
 
+    \section1 Using Custom Types
+
+    In the Photo Viewer app, we use the following custom types that are each
+    defined in a separate .qml file:
+
+    \list
+        \li \c AlbumDelegate.qml
+        \li \c BusyIndicator.qml
+        \li \c Button.qml
+        \li \c EditableButton.qml
+        \li \c PhotoDelegate.qml
+        \li \c ProgressBar.qml
+        \li \c RssModel.qml
+        \li \c Tag.qml
+    \endlist
+
+    To use the custom types, we add an import statement to the main QML file,
+    main.qml, that imports the folder called \c PhotoViewerCore where the types
+    are located:
+
+    \quotefromfile demos/photoviewer/main.qml
+    \skipto PhotoViewerCore
+    \printuntil "
+
+    \section1 Creating the Main Window
+
+    In main.qml, we use the ApplicationWindow Qt Quick Control to create the app
+    main window:
+
+    \printuntil visible
+
+    We use a ListModel type with \l ListElement types to display photo albums:
+
+    \skipto ListModel
+    \printuntil Prague
+    \printuntil }
+
+    List elements are defined like other QML types except that they contain a
+    collection of \e role definitions instead of properties. Roles both define
+    how the data is accessed and include the data itself. For each list element,
+    we use the \c tag role to specify the photos to download.
+
+    A DelegateModel type is used together with the \l Package type to provide
+    delegates to multiple views. The \c model property holds the model providing
+    data for the delegate model and the \c delegate property specifies the
+    template defining each item instantiated by a view:
+
+    \printuntil DelegateModel
+
+    We use a GridView type to lay out the albums as a grid:
+
+    \printuntil }
+
+    The \c model property references the package name \c album that we specify
+    in AlbumDelegate.qml. We use the \l Package type to allow the photos to move
+    between different views. The \l Package contains the named items \c browser,
+    \c fullscreen, and \c album:
+
+    \quotefromfile demos/photoviewer/PhotoViewerCore/AlbumDelegate.qml
+    \skipto Package
+    \printuntil albumWrapper
+
+    The named items are used as the delegates by the views that reference the
+    special DelegateModel::parts property to select the model that provides
+    the chosen delegate.
+
+    We use a ListView type to lay out albums in other views:
+
+    \quotefromfile demos/photoviewer/main.qml
+    \skipto ListView
+    \printuntil }
+    \skipto ListView
+    \printuntil }
+
+    \section1 Displaying Photos
+
+    We use the PhotoDelegate custom type that is specified in PhotoDelegate.qml
+    to display photos. We use a \l Package type to lay out the photos either in
+    a stack, list, or a grid:
+
+    \quotefromfile demos/photoviewer/PhotoViewerCore/PhotoDelegate.qml
+    \skipto Package
+    \printuntil gridItem
+
+    The photos are rotated at random angles by using the \c Math.random()
+    JavaScript method:
+
+    \printuntil stackItem
+
+    We use a BorderImage type to create borders for the images:
+
+    \printuntil border.left
+    \printuntil }
+
+    \section1 Downloading Flickr Feeds
+
+    In AlbumDelegate.qml, we use the DelegateModel to provide the
+    PhotoDelegate delegate to the RssModel model:
+
+    \quotefromfile demos/photoviewer/PhotoViewerCore/AlbumDelegate.qml
+    \skipto DelegateModel
+    \printuntil RssModel
+    \printuntil }
+
+    In RssModel.qml, we use an XmlListModel type as a data source for
+    \l Package objects to download photos from the selected feeds:
+
+    \quotefromfile demos/photoviewer/PhotoViewerCore/RssModel.qml
+    \skipto XmlListModel
+    \printuntil encodeTags
+
+    We use the \c tags custom property to specify which photos to download. The
+    \c encodeTags custom function uses the \c encodeURIComponent JavaScript
+    method to ensure that the requests to the server are correctly formatted.
+
+    We use the \c source property to fetch photos that have the specified tags
+    attached from public Flickr feeds:
+
+    \printuntil namespaceDeclarations
+
+    The \c query property specifies that the XmlListModel generates a model item
+    for each feed entry.
+
+    The \c namespaceDeclarations property specifies that the requested document
+    uses the namespace \c{http://www.w3.org/2005/Atom}, which is declared as the
+    default namespace.
+
+    We use the XmlRole type to specify the model item attributes. Each model
+    item has the \c title, \c content, and \c hq attributes that match the
+    values of the corresponding feed entry:
+
+    \printuntil hq
+
+    \section1 Creating Flipable Labels
+
+    When users select the \b Edit button, the album labels are flipped from
+    their front side to their back side and the text on them changes from album
+    name to \b Remove.
+
+    In AlbumDelegate.qml, we use the Tag custom type to specify the text to
+    display on the front and back sides of album labels:
+
+    \quotefromfile demos/photoviewer/PhotoViewerCore/AlbumDelegate.qml
+    \skipto Tag
+    \printuntil onBackClicked
+    \printuntil }
+
+    The \c onTagChanged signal handler is used to change the tag based on
+    which the model is populated. The \c onBackClicked signal handler is used to
+    remove the album.
+
+    In Tag.qml, we use a \l Flipable type with custom properties and signals to
+    create the labels:
+
+    \quotefromfile demos/photoviewer/PhotoViewerCore/Tag.qml
+    \skipto Flipable
+    \printuntil tagChanged
+
+    The \c front property holds the EditableButton custom type that enables
+    users to edit the label text:
+
+    \printuntil onLabelChanged
+    \printuntil }
+
+    The \c back property holds the \c Button custom type that is used to remove
+    the album:
+
+    \printuntil onClicked
+    \printuntil }
+
+    \section1 Laying out Photos on a Path
+
+    In AlbumDelegate.qml, we use a PathView type to lay out the photos provided
+    by the \c visualModel.parts.stack model on a path that has the form of a
+    stack:
+
+    \quotefromfile demos/photoviewer/PhotoViewerCore/AlbumDelegate.qml
+    \skipto PathView
+    \printuntil 0.0
+    \printuntil }
+    \printuntil }
+
+    The \c path property holds the \l Path type that defines the path used by
+    the PathView. The PathAttribute types are used to set a range of
+    \c 0 to \c 9999 for the \c z attribute. This way, the path creates a stack
+    of album photos. Because each PhotoDelegate is slightly rotated at a random
+    angle, this results in a realistic-looking stack of photos.
+
+    \section1 Providing Feedback to Users
+
+    We use a busy indicator and a progress bar to indicate activity while
+    Flickr feeds and photos are being loaded.
+
+    In AlbumDelegate.qml, we use the \c BusyIndicator custom type and the
+    \c on custom property to display a rotating image while the Flickr feed is
+    being loaded:
+
+    \quotefromfile demos/photoviewer/PhotoViewerCore/AlbumDelegate.qml
+    \skipto BusyIndicator
+    \printuntil rssModel
+    \printuntil }
+
+    In PhotoDelegate.qml, we use them to indicate activity while a photo is
+    being loaded:
+
+    \quotefromfile demos/photoviewer/PhotoViewerCore/PhotoDelegate.qml
+    \skipto BusyIndicator
+    \printuntil }
+
+    We define the \c BusyIndicator type in \c BusyIndicator.qml. We use an
+    \l Image type to display an image and apply a NumberAnimation to its
+    \c rotation property to rotate the image in an infinite loop:
+
+    \quotefromfile demos/photoviewer/PhotoViewerCore/BusyIndicator.qml
+    \skipto Image
+    \printuntil }
+    \printuntil }
+
+    In your apps, you can also use the BusyIndicator type from the
+    \l {Qt Quick Controls} module.
+
+    In main.qml, we use the \c ProgressBar custom type to indicate progress
+    while a high quality version of a photo is being opened on full screen:
+
+    \quotefromfile demos/photoviewer/main.qml
+    \skipto ProgressBar
+    \printuntil }
+
+    We define the \c ProgressBar type in \c ProgressBar.qml. We use a
+    \l Rectangle type to create the progress bar and apply a NumberAnimation to
+    its \c opacity property to change the color of the bar from black to white
+    as data loading proceeds:
+
+    \quotefromfile demos/photoviewer/PhotoViewerCore/ProgressBar.qml
+    \skipto Item
+    \printuntil /^\}/
+
+    In your apps, you can also use the ProgressBar type from the
+    \l {Qt Quick Controls} module.
+
+    \section1 Localizing Applications
+
+    The example application is translated into German and French. The translated
+    strings are loaded at runtime according to the current locale.
+
+    We use a \l Column type in main.qml to position buttons for adding and
+    editing albums and exiting the application:
+
+    \quotefromfile demos/photoviewer/main.qml
+    \skipto Column
+    \printuntil quit()
+    \printuntil }
+    \printuntil }
+
+    We use the \l qsTr() command to mark the button labels translatable.
+
+    We use the \l lupdate tool to generate the translation source files and
+    the \l lrelease tool to convert the translated strings to the QM files used
+    by the application at runtime. These files are stored in the \c i18n
+    directory.
+
+    To make the application aware of the translations, we add code to the
+    \c main() function in the main.cpp file. The code creates a \l QTranslator
+    object, loads a translation according to the current locale at runtime, and
+    installs the translator object into the application:
+
+    \quotefromfile demos/photoviewer/main.cpp
+    \skipto main
+    \printuntil app.installTranslator
+
     \sa {QML Applications}
 */