From 6641214214213f079176b81e9a98d63cf21bfd3c Mon Sep 17 00:00:00 2001
From: Leena Miettinen <riitta-leena.miettinen@digia.com>
Date: Fri, 19 Sep 2014 15:00:11 +0200
Subject: Doc: Add docs for Clocks example
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Change-Id: I626376ae2a169f7d892e86309754633e9ed6a6e9
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>
---
 examples/quick/demos/clocks/doc/src/clocks.qdoc | 92 ++++++++++++++++++++++++-
 1 file changed, 89 insertions(+), 3 deletions(-)

(limited to 'examples')

diff --git a/examples/quick/demos/clocks/doc/src/clocks.qdoc b/examples/quick/demos/clocks/doc/src/clocks.qdoc
index b57894c5d3..1118984a7d 100644
--- a/examples/quick/demos/clocks/doc/src/clocks.qdoc
+++ b/examples/quick/demos/clocks/doc/src/clocks.qdoc
@@ -29,13 +29,99 @@
     \title Qt Quick Demo - Clocks
     \ingroup qtquickdemos
     \example demos/clocks
-    \brief A QML application that shows the current time in different cities.
+    \brief A QML clock application that demonstrates using a ListView type to
+    display data generated by a ListModel and a SpringAnimation type to animate
+    images.
     \image qtquick-demo-clocks-small.png
 
-    \e Clocks demonstrates various QML and \l{Qt Quick} features such as
-    displaying custom components.
+    \e Clocks demonstrates using a ListView type to display data generated by a
+    ListModel. The delegate used by the model is specified as a custom QML type
+    that is specified in the Clock.qml file.
+
+    JavaScript methods are used to fetch the current time in several cities in
+    different time zones and QML types are used to display the time on a clock
+    face with animated clock hands.
 
     \include examples-run.qdocinc
 
+    \section1 Displaying Data Generated by List Models
+
+    In the clocks.qml file, we use a \l Rectangle type to create the application
+    main window:
+
+    \quotefromfile demos/clocks/clocks.qml
+    \skipto Rectangle
+    \printuntil color
+
+    We use a ListView type to display a list of the items provided by a
+    ListModel type:
+
+    \printuntil Los Angeles
+    \printuntil }
+    \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 cityName role to specify the name of a
+    city and the \c timeShift role to specify a time zone as a positive or
+    negative offset from UTC (coordinated universal time).
+
+    The Clock custom type is used as the ListView's \c delegate, defining the
+    visual appearance of list items. To use the Clock type, we add an import
+    statement that imports the folder called \c content where the type is
+    located:
+
+    \quotefromfile demos/clocks/clocks.qml
+    \skipto content
+    \printuntil "
+
+    We use an \l Image type to display arrows that indicate whether users can
+    flick the view to see more clocks on the left or right:
+
+    \quotefromfile demos/clocks/clocks.qml
+    \skipto Image
+    \printuntil /^\}/
+
+    We use the \c opacity property to hide the arrows when the list view is
+    located at the beginning or end of the x axis.
+
+    In Clock.qml, we define a \c timeChanged() function in which we use
+    methods from the JavaScript \c Date object to fetch the current time in
+    UTC and to adjust it to the correct time zone:
+
+   \quotefromfile demos/clocks/content/Clock.qml
+    \skipto timeChanged
+    \printuntil }
+
+    We use a \l Timer type to update the time at intervals of 100 milliseconds:
+
+    \printuntil }
+
+    We use \l Image types within an \l Item type to display the time on an
+    analog clock face. Different images are used for daytime and nighttime
+    hours:
+
+    \printuntil clock-night.png
+
+    A \l Rotation transform applied to \l Image types provides a way to rotate
+    the clock hands. The \c origin property holds the point that stays fixed
+    relative to the parent as the rest of the item rotates. The \c angle
+    property determines the angle to rotate the hands in degrees clockwise.
+
+    \printuntil center.png
+    \printuntil }
+
+    We use a \l Behavior type on the \c angle property to apply a
+    SpringAnimation when the time changes. The \c spring and \c damping
+    properties enable the spring-like motion of the clock hands, and a
+    \c modulus of \c 360 makes the animation target values wrap around at a
+    full circle.
+
+    We use a \l Text type to display the city name below the clock:
+
+    \printuntil }
+
     \sa {QML Applications}
 */
-- 
cgit v1.2.3