Merge lp:~nik90/component-store/add-welcome-wizard into lp:component-store

[Nekhelesh Ramananthan]

Added welcome wizard component

Adds welcome wizard component

=== added directory 'ComponentStore/WelcomeWizard'
=== added file 'ComponentStore/WelcomeWizard/Walkthrough.qml'
--- ComponentStore/WelcomeWizard/Walkthrough.qml	1970-01-01 00:00:00 +0000
+++ ComponentStore/WelcomeWizard/Walkthrough.qml	2015-03-03 14:08:25 +0000
@@ -0,0 +1,116 @@
+import QtQuick 2.3
+import Ubuntu.Components 1.1
+import Ubuntu.Components.ListItems 1.0 as ListItem
+
+Page {
+    id: walkthrough
+
+    // Property to set the app name used in the walkthrough
+    property string appName
+
+    // Property to check if this is the first run or not
+    property bool isFirstRun: true
+
+    // Property to store the slides shown in the walkthrough (Each slide is a component defined in a separate file for simplicity)
+    property list<Component> model
+
+    // Property to set the color of bottom cirle to indicate the user's progress
+    property color completeColor: "green"
+
+    // Property to set the color of the bottom circle to indicate the slide still left to cover
+    property color inCompleteColor: "grey"
+
+    // Property to set the color of the skip welcome wizard text
+    property color skipTextColor: "grey"
+
+    // Property to signal walkthrough completion
+    signal finished
+
+    // ListView to show the slides
+    ListView {
+        id: listView
+        anchors {
+            left: parent.left
+            right: parent.right
+            top: skipLabel.bottom
+            bottom: separator.top
+        }
+
+        model: walkthrough.model
+        snapMode: ListView.SnapOneItem
+        orientation: Qt.Horizontal
+        highlightMoveDuration: UbuntuAnimation.FastDuration
+        highlightRangeMode: ListView.StrictlyEnforceRange
+        highlightFollowsCurrentItem: true
+
+        delegate: Item {
+            width: listView.width
+            height: listView.height
+            clip: true
+
+            Loader {
+                anchors {
+                    fill: parent
+                    margins: units.gu(2)
+                }
+
+                sourceComponent: modelData
+            }
+        }
+    }
+
+    // Label to skip the walkthrough. Only visible on the first slide
+    Label {
+        id: skipLabel
+
+        color: skipTextColor
+        fontSize: "small"
+        width: contentWidth
+        text: listView.currentIndex === 0 ? i18n.tr("Already used %1? <b>Skip the tutorial</b>").arg(appName) : i18n.tr("Skip")
+
+        anchors {
+            top: parent.top
+            left: parent.left
+            margins: units.gu(2)
+        }
+
+        MouseArea {
+            anchors.fill: parent
+            onClicked: walkthrough.finished()
+        }
+    }
+
+    // Separator between walkthrough slides and slide indicator
+    ListItem.ThinDivider {
+        id: separator
+        anchors.bottom: slideIndicator.top
+    }
+
+    // Indicator element to represent the current slide of the walkthrough
+    Row {
+        id: slideIndicator
+        height: units.gu(6)
+        spacing: units.gu(2)
+        anchors {
+            bottom: parent.bottom
+            horizontalCenter: parent.horizontalCenter
+        }
+
+        Repeater {
+            model: walkthrough.model.length
+            delegate: Rectangle {
+                height: width
+                radius: width/2
+                width: units.gu(2)
+                antialiasing: true
+                anchors.verticalCenter: parent.verticalCenter
+                color: listView.currentIndex >= index ? completeColor : inCompleteColor
+                Behavior on color {
+                    ColorAnimation {
+                        duration: UbuntuAnimation.FastDuration
+                    }
+                }
+            }
+        }
+    }
+}
 
=== added file 'ComponentStore/WelcomeWizard/ubuntu_component_store.json'
--- ComponentStore/WelcomeWizard/ubuntu_component_store.json	1970-01-01 00:00:00 +0000
+++ ComponentStore/WelcomeWizard/ubuntu_component_store.json	2015-03-03 14:08:25 +0000
@@ -0,0 +1,6 @@
+{
+    "name": "WelcomeWizard",
+    "description": "This widget adds a welcome wizard to help introduce the app to users.",
+    "version": "1.0",
+    "documentation_url": "http://ubuntu-component-store.readthedocs.org/en/latest/_components/circleimage.html"
+}
 
=== added file 'GallerySRC/Slide1.qml'
--- GallerySRC/Slide1.qml	1970-01-01 00:00:00 +0000
+++ GallerySRC/Slide1.qml	2015-03-03 14:08:25 +0000
@@ -0,0 +1,54 @@
+import QtQuick 2.3
+import Ubuntu.Components 1.1
+
+// Slide 1
+Component {
+    id: slide1
+    Item {
+        id: slide1Container
+
+        UbuntuShape {
+            anchors {
+                bottom: textColumn.top
+                bottomMargin: units.gu(4)
+                horizontalCenter: parent.horizontalCenter
+            }
+
+            image: Image {
+                smooth: true
+                antialiasing: true
+                fillMode: Image.PreserveAspectFit
+                source: Qt.resolvedUrl("assets/flashback.png")
+            }
+        }
+
+        Column {
+            id: textColumn
+
+            anchors.centerIn: parent
+
+            Label {
+                text: "Welcome to"
+                fontSize: "x-large"
+                height: contentHeight
+                anchors.horizontalCenter: parent.horizontalCenter
+            }
+            Label {
+                text: "Component Store Gallery"
+                font.bold: true
+                height: contentHeight
+                font.pixelSize: units.dp(50)
+                anchors.horizontalCenter: parent.horizontalCenter
+            }
+        }
+
+        Label {
+            id: swipeText
+            text: "Swipe left to continue"
+            horizontalAlignment: Text.AlignHCenter
+            anchors.bottom: parent.bottom
+            anchors.bottomMargin: units.gu(2)
+            anchors.horizontalCenter: parent.horizontalCenter
+        }
+    }
+}
 
=== added file 'GallerySRC/Slide2.qml'
--- GallerySRC/Slide2.qml	1970-01-01 00:00:00 +0000
+++ GallerySRC/Slide2.qml	2015-03-03 14:08:25 +0000
@@ -0,0 +1,42 @@
+import QtQuick 2.3
+import Ubuntu.Components 1.1
+
+// Slide 2
+Component {
+    id: slide2
+    Item {
+        id: slide2Container
+
+        Column {
+            id: mainColumn
+            spacing: units.gu(4)
+            anchors.fill: parent
+
+            Label {
+                id: introductionText
+                text: "Component Store Gallery"
+                font.bold: true
+                fontSize: "x-large"
+                anchors.horizontalCenter: parent.horizontalCenter
+            }
+
+            Image {
+                id: centerImage
+                height: parent.height - bodyText.contentHeight - introductionText.height - 4*mainColumn.spacing
+                fillMode: Image.PreserveAspectFit
+                anchors.horizontalCenter: parent.horizontalCenter
+                source: Qt.resolvedUrl("assets/flashback.png")
+            }
+
+            Label {
+                id: bodyText
+                anchors.left: parent.left
+                anchors.right: parent.right
+                wrapMode: Text.WordWrap
+                font.pixelSize: units.dp(17)
+                horizontalAlignment: Text.AlignHCenter
+                text: "Component Store Gallery is a frontend app to the component store and provides a demo of all the components in the store. \n\nUbuntu Touch's first component store!"
+            }
+        }
+    }
+}
 
=== added file 'GallerySRC/WelcomeWizardWidget.qml'
--- GallerySRC/WelcomeWizardWidget.qml	1970-01-01 00:00:00 +0000
+++ GallerySRC/WelcomeWizardWidget.qml	2015-03-03 14:08:25 +0000
@@ -0,0 +1,41 @@
+import QtQuick 2.0
+import Ubuntu.Components 1.1
+import "../ComponentStore/WelcomeWizard"
+
+TemplateWidgetPage {
+    id: welcomeWizardWidget
+
+    title: "Welcome Wizard"
+    author: "Nekhelesh Ramananthan, Michael Spencer"
+    email: "[e-mail]"
+    license: "GNU General Public License v3.0"
+    description: "This widget adds a welcome wizard which helps showcase the \
+app features to the user."
+
+    Component {
+        id: pageComponent
+        Walkthrough {
+            id: walkthrough
+
+            appName: "Component Store Gallery"
+
+            onFinished: {
+                console.log("Welcome Wizard Complete!")
+                stack.pop()
+            }
+
+            model: [
+                Slide1{},
+                Slide2{}
+            ]
+        }
+    }
+
+    content: Button {
+        text: "Preview Welcome Wizard Component"
+        color: "Green"
+        height: units.gu(6)
+        onClicked: stack.push(pageComponent)
+        anchors.centerIn: parent
+    }
+}
 
=== modified file 'GallerySRC/WidgetsModel.qml'
--- GallerySRC/WidgetsModel.qml	2014-11-15 13:52:44 +0000
+++ GallerySRC/WidgetsModel.qml	2015-03-03 14:08:25 +0000
@@ -32,4 +32,9 @@
         label: "Radial Bottom Edge"
         source: "GallerySRC/RadialBottomEdgeWidget.qml"
     }
+
+    ListElement {
+        label: "Welcome Wizard"
+        source: "GallerySRC/WelcomeWizardWidget.qml"
+    }
 }
 
=== modified file 'docs/_components/listitemwithactions.rst'
--- docs/_components/listitemwithactions.rst	2014-11-15 14:59:11 +0000
+++ docs/_components/listitemwithactions.rst	2015-03-03 14:08:25 +0000
@@ -116,7 +116,7 @@
         
         Label {
             id: subTitle
-            text: "SubTitle
+            text: "SubTitle"
         }
     }
 
 
=== added file 'docs/_components/welcomewizard.rst'
--- docs/_components/welcomewizard.rst	1970-01-01 00:00:00 +0000
+++ docs/_components/welcomewizard.rst	2015-03-03 14:08:25 +0000
@@ -0,0 +1,218 @@
+Welcome Wizard
+==============
+
++----------+----------------------------------------+
+| Author   | Nekhelesh Ramananthan, Michael Spencer |
++----------+-------------+--------------------------+
+| License  | BSD License                            |
++----------+----------------------------------------+
+| Contact  | [e-mail]                       |
++----------+----------------------------------------+
+| Framework| ubuntu-sdk-14.10                       |
++----------+----------------------------------------+
+
+This component shows users a welcome wizard which can be used to introduce
+and showcase the features of the app to guide the user. The API of this
+component is rather simple and provides a lot of freedom to the developer
+to present his content.
+
+It is recommended to put the Walkthrough{} component inside a qml Component{}
+since it is not run frequently. Walkthrough derives from a Page. So push it
+into a pagestack to show the welcome wizard as shown below in the example.
+
+Example:
+
+MainView.qml
+
+.. code-block:: qml
+
+    MainView
+    {
+        Component {
+            id: pageComponent
+            Walkthrough {
+                id: walkthrough
+
+                appName: "Component Store Gallery"
+
+                onFinished: {
+                    console.log("Welcome Wizard Complete!")
+                    // Here perhaps save isFirstRun variable to the disk
+                    stack.pop()
+                }
+
+                model: [
+                    Slide1{},
+                    Slide2{}
+                ]
+            }
+        }
+        
+        component.onCompleted: pagestack.push(pageComponent)
+    }
+    
+Slide1.qml
+        
+.. code-block:: qml
+
+    import QtQuick 2.3
+    import Ubuntu.Components 1.1
+
+    // Slide 1
+    Component {
+        id: slide1
+        Item {
+            id: slide1Container
+
+            UbuntuShape {
+                anchors {
+                    bottom: textColumn.top
+                    bottomMargin: units.gu(4)
+                    horizontalCenter: parent.horizontalCenter
+                } 
+
+                image: Image {
+                    smooth: true
+                    antialiasing: true
+                    fillMode: Image.PreserveAspectFit
+                    source: Qt.resolvedUrl("assets/flashback.png")
+                }
+            }
+
+            Column {
+                id: textColumn
+
+                anchors.centerIn: parent
+
+                Label {
+                    text: "Welcome to"
+                    fontSize: "x-large"
+                    height: contentHeight
+                    anchors.horizontalCenter: parent.horizontalCenter
+                }
+                Label {
+                    text: "Component Store Gallery"
+                    font.bold: true
+                    height: contentHeight
+                    font.pixelSize: units.dp(50)
+                    anchors.horizontalCenter: parent.horizontalCenter
+                }
+            }
+
+            Label {
+                id: swipeText
+                text: "Swipe left to continue"
+                horizontalAlignment: Text.AlignHCenter
+                anchors.bottom: parent.bottom
+                anchors.bottomMargin: units.gu(2)
+                anchors.horizontalCenter: parent.horizontalCenter
+            }
+        }
+    }
+
+.. image:: ../_images/welcomewizard.png
+   :align: center
+   
+Properties
+----------
+
+- :ref:`appName`: string
+- :ref:`isFirstRun`: boolean
+- :ref:`model`: Item<list>
+- :ref:`completeColor`: color
+- :ref:`inCompleteColor`: color
+- :ref:`skipTextColor`: color
+
+Signals
+-------
+
+- :ref:`finished()`
+
+Property Documentation
+----------------------
+
+.. _appName:
+
+appName
+^^^^^^^
+
+Name of the application that is shown in some parts of the welcome wizard.
+
+.. _isFirstRun:
+
+isFirstRun
+^^^^^^^^^^
+
+Boolean property to determine if the welcome wizard was run for the first time
+or not. It is recommended to store this variable to the disk using U1dB or Qt.labs.settings 
+to remember the welcome wizard run state.
+
+.. _model:
+
+model
+^^^^^
+
+This property stores the welcome wizards slides that are shown to the user. 
+Create your content and store them in separate files per slide. So if you
+have 3 slides in your welcome wizard, you could define them as Slide1.qml,
+Slide2.qml and Slide3.qml and then reference them as,
+
+.. code-block:: qml
+
+    model: [
+        Slide1{},
+        Slide2{},
+        Slide3{}
+    ]
+    
+The slides should only contain the content you want to show. Everything else like the
+dots, divider, title etc are handled by the welcome wizard component itself. Think of these
+slides as delegates in a listview which only house the content itself.
+
+.. _completeColor:
+
+completeColor
+^^^^^^^^^^^^^
+
+This property sets the color of the bottom circle to indicate the progress of the user. By
+default it is green.
+
+.. _inCompleteColor:
+
+inCompleteColor
+^^^^^^^^^^^^^^^
+
+This property sets the color of the bottom circle to indicate the slides left in the wizard.
+By default it is grey.
+
+.. _skipTextColor:
+
+skipTextColor
+^^^^^^^^^^^^^
+
+This property sets the color of the skip text shown at the top of the welcome wizard.
+
+Signal Documentation
+--------------------
+
+.. _finished():
+
+finished()
+^^^^^^^^^^
+
+This signal is fired automatically when the user press the skip button. It can also be made
+to fire manually to exit the welcome wizard. You can perform exit tasks when this signal is fired
+like updating the :ref:`isFirstRun` variable and storing to disk etc.
+
+.. code-block:: qml
+
+    Button {
+        id: continueButton
+        color: "Green"
+        height: units.gu(5)
+        width: units.gu(25)
+        text: "Exit Welcome Wizard"
+        anchors.horizontalCenter: parent.horizontalCenter
+        onClicked: finished()
+    }
+
 
=== added file 'docs/_images/welcomewizard.png'
 Binary files docs/_images/welcomewizard.png	1970-01-01 00:00:00 +0000 and docs/_images/welcomewizard.png	2015-03-03 14:08:25 +0000 differ
=== modified file 'docs/index.rst'
--- docs/index.rst	2014-11-15 14:50:47 +0000
+++ docs/index.rst	2015-03-03 14:08:25 +0000
@@ -54,3 +54,4 @@
    _components/listitemwithactions
    _components/pagewithbottomedge
    _components/radialbottomedge
+   _components/welcomewizard