Doc: add docs for Widget Gallery example

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

1 files changed, 235 insertions, 2 deletions

diff --git a/src/controls/doc/src/qtquickcontrols-examples.qdoc b/src/controls/doc/src/qtquickcontrols-examples.qdoc
index 1a838e0e..4f1ab219 100644
--- a/src/controls/doc/src/qtquickcontrols-examples.qdoc
+++ b/src/controls/doc/src/qtquickcontrols-examples.qdoc
@@ -139,10 +139,243 @@
     \brief Demonstrates UI controls for a touch interface
     \image qtquickcontrols-example-touch.png
 
-    This example shows how to implement a UI suitable
-    for touch input using \l{Qt Quick Controls}.
+    \e {Touch Gallery} demonstrates how to implement a UI suitable for touch
+    input using the following \l{Qt Quick Controls}:
+
+    \list
+        \li \l ApplicationWindow
+        \li \l Button
+        \li \l ProgressBar
+        \li \l ScrollView
+        \li \l Slider
+        \li \l StackView
+        \li \l Switch
+        \li \l Tab
+        \li \l TabView
+        \li \l TextField
+    \endlist
+
+    The appearance of the controls is customized by using
+    \l {Qt Quick Controls Styles}.
 
     \include examples-run.qdocinc
+
+    \section1 Creating the Main Page
+
+    In the main.qml file, we use a \l Rectangle type within the
+    \l ApplicationWindow type to create the main page of the application:
+
+    \quotefromfile touch/main.qml
+    \skipto ApplicationWindow
+    \printuntil }
+
+    To use the Qt Quick Controls, we must import them:
+
+    \code
+    import QtQuick.Controls 1.2
+    \endcode
+
+    The \c toolBar property of the application window holds a BorderImage type
+    that we use to create a separator between the application name and a list of
+    additional pages:
+
+    \quotefromfile touch/main.qml
+    \skipto toolBar
+    \printuntil height
+
+    We use an \l Image type in a \l Rectangle type to create a back button. We
+    use the \c onClicked signal handler to call the StackView \c pop() function
+    that pops off the page when users tap the button:
+
+    \printuntil pop()
+    \printuntil }
+    \printuntil }
+
+    We use the \c opacity property to hide the back button on the main page.
+
+    We use a \l Text type to display the application name:
+
+    \printuntil text:
+    \printuntil }
+
+    The \c x position of the \l Text type is bound to the position and width of
+    the back button, and animated using a \l Behavior.
+
+    We use a ListModel type that contains ListElement definitions to define
+    titles and source files for the other pages in the application:
+
+    \skipto ListModel
+    \printuntil ListPage
+    \printuntil }
+    \printuntil }
+
+    \section1 Navigating in the Application
+
+    We implement a stack-based navigation model to link the application pages
+    together. Items are pushed onto the stack as users navigate deeper into the
+    application, and popped off again when they return to the main page.
+
+    In main.qml, we add a \l StackView type as a child of the application
+    window:
+
+    \skipto StackView
+    \printuntil }
+
+    The stack is used by invoking its navigation methods. To load the first item
+    in the stack view, we assign it to \c initialItem:
+
+    \printuntil \printuntil /^\}/
+
+    We use a ListView type to display a list of the items provided by
+    \c pageModel. The \c AndroidDelegate custom type defines each item
+    instantiated by the view.
+
+    \section1 Creating Push Buttons and Switches
+
+    In ButtonPage.qml we use the \l Button type to create two buttons that
+    change color when users tap them and one that pops off the page and returns
+    the user to the main page:
+
+    \quotefromfile touch/content/ButtonPage.qml
+    \skipto Button
+    \printuntil stackView
+    \printuntil }
+
+    We use a \l Switch type to create two switches that users can turn on and
+    off. They are placed within a \l Row type to lay them out horizontally:
+
+    \printuntil switchStyle
+    \printuntil switchStyle
+    \printuntil }
+    \printuntil }
+
+    A \l ButtonStyle type creates a custom appearance for the buttons:
+
+    \skipto Component
+    \printuntil }
+
+    To use Qt Quick Controls Styles, we must import them:
+
+    \code
+    import QtQuick.Controls.Styles 1.1
+    \endcode
+
+    A \l SwitchStyle type creates a custom appearance for the switches:
+
+    \quotefromfile touch/content/ButtonPage.qml
+    \skipuntil Component
+    \skipto Component
+    \printuntil /^\}/
+
+    The \c groove property holds the background groove of the switch and the
+    \c handle property defines the switch handle.
+
+    \section1 Creating Sliders
+
+    In SliderPage.qml, we use a \l Slider type to create three horizontal
+    sliders that are placed within a \l Column type to lay them out in a column:
+
+    \quotefromfile touch/content/SliderPage.qml
+    \skipto Column
+    \printuntil 1.0
+    \printuntil }
+    \printuntil }
+
+    The \c value property holds the initial handle position on the slider.
+
+    A SliderStyle type creates a custom appearance for the sliders:
+
+    \printuntil /^\}/
+
+    The \c handle property defines the slider handle and the \c groove property
+    holds the background groove of the slider.
+
+    \section1 Indicating Progress
+
+    In ProgressBar.qml, we use a ProgressBar type to create three progress bars:
+
+    \quotefromfile touch/content/ProgressBarPage.qml
+    \skipto Column
+    \printuntil 1
+    \printuntil 400
+    \printuntil }
+
+    We use a NumberAnimation type with a SequentialAnimation type to run two
+    number animations in a sequence. We apply the animations on the \c progress
+    custom property to animate the current value on the progress bars:
+
+    \quotefromfile touch/content/ProgressBarPage.qml
+    \skipto progress
+    \printuntil }
+    \printuntil }
+
+    A ProgressBarStyle type creates a custom appearance for the progress bars:
+
+    \quotefromfile touch/content/ProgressBarPage.qml
+    \skipto Component
+    \printuntil /^\}/
+
+    \section1 Creating Tabs
+
+    In TabBarPage.qml, we use a TabView type with a \l Tab type to provide a
+    tab-based navigation model for our application. We use tabs to display the
+    ButtonPage, SliderPage, and ProgressBarPage on separate tab pages:
+
+    \quotefromfile touch/content/TabBarPage.qml
+    \skipto TabView
+    \printuntil ProgressBarPage
+    \printuntil }
+
+    A TabViewStyle type creates a custom appearance for the tabs:
+
+    \skipto Component
+    \printuntil /^\}/
+
+    \section1 Creating Text Input Fields
+
+    In the TextInputPage.qml, we use a TextField type to create an input field
+    and a read-only text field:
+
+    \quotefromfile touch/content/TextInputPage.qml
+    \skipto Column
+    \printuntil true
+    \printuntil }
+    \printuntil }
+
+    A TextFieldStyle creates a custom appearance for the text fields:
+
+    \printuntil /^\}/
+
+    We use a BorderImage type with an image to create borders for the fields.
+
+    \section1 Creating Scrolling Lists
+
+    In ListPage.qml, we use a ScrollView type to provide a scrolling page with a
+    vertical scoll bar:
+
+    \quotefromfile touch/content/ListPage.qml
+    \skipto ScrollView
+    \printuntil true
+
+    We use a ListView type to display a list of 100 items by specifying an
+    \l{Models and Views in Qt Quick#Integers as Models}{integer} as the value of
+    the \c model property. We reuse the \c AndroidDelegate custom type here to
+    define each item instantiated by the view. The \c text property adds the
+    string \c {Item #} to each list item:
+
+    \printuntil }
+    \printuntil }
+
+    A ScrollViewStyle type creates a custom appearance for the scroll view:
+
+    \printuntil /^\}/
+
+    The \c transientScrollBars property is set to \c true to make the scroll
+    bars appear when the content is scrolled and disappear when they are no
+    longer needed.
+
+    The \c handle property controls the appearance of the scroll bar handle and
+    the \c scrollBarBackground property that of the background.
 */
 
 /*!