Welcome Wizard
==============

+----------+----------------------------------------+
| Author   | Nekhelesh Ramananthan, Michael Spencer |
+----------+-------------+--------------------------+
| License  | BSD License                            |
+----------+----------------------------------------+
| Contact  | nik90@ubuntu.com                       |
+----------+----------------------------------------+
| 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()
    }