/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2012 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (qt-info@nokia.com)
**
**
** GNU Free Documentation License
**
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
    \contentspage index.html
    \previouspage creator-qml-application.html
    \page creator-qml-components-example.html
    \nextpage creator-writing-program.html

    \title Using Qt Quick Components

    \note To complete this tutorial, you must install the Qt Quick Components
    for Symbian and the Symbian Anna target as part of the \QSDK. In addition,
    you must install the Qt Quick Components on the test device.

    This tutorial describes how to use \QC to create a small Qt
    application, Battery Status, that uses the System Information
    Mobility API to fetch battery information from the device.

    \image qtcreator-symbian-components-example.png "Mobile example"

    The user interface for the application is designed using Qt Quick Components
    for Symbian. This enforces a platform look and feel for Symbian Anna devices.

    \section1 Creating the Project

    \list 1

        \o  Select \gui{File > New File or Project > Applications > Qt Quick
            Application for Symbian > Choose}.

        \o  In the \gui{Name} field, type \bold {BatteryStatus}.

        \o  In the \gui {Create in} field, enter the path for the project files.
            For example, \c {C:\Qt\examples}, and then click \gui{Next}.

        \o  Select \gui {Symbian Device} and \gui {\QS} targets, and
            then click \gui{Next}.

            \note Targets are listed if you installed the appropriate
            development environment, for example, as part of the \QSDK. You can
            add targets later in the \gui Projects mode.

        \o  Select \gui Next in the following dialogs to use the default
            settings.

            \note \QC contains a default program icon and generates an
            \l{Application UID}, for testing the application on a device. You
            only need to change the icon and UID if you deliver the application
            for public use.

        \o  Review the project settings, and click \gui{Finish} to create the
            project.

    \endlist

    \QC generates the necessary files that contain boiler plate code. The
    wizard creates an application that uses
    \l{http://doc.qt.nokia.com/qt-components-symbian/qt-components-pages-and-navigation-overview.html}
    {page-based application navigation}.

    Modify the files as described in the following sections.

    \section1 Declaring the Qt Mobility API

    To use the Qt Mobility APIs or develop applications for Symbian devices,
    you must modify the .pro file to declare the Qt Mobility APIs that you use.

    This example uses the System Info API, so you must declare it, as
    illustrated by the following code snippet:

    \code

    CONFIG += mobility
    MOBILITY = systeminfo

    \endcode

    Each Mobility API has its corresponding value that you have to add
    as a value of MOBILITY to use the API. For a list of the APIs and the
    corresponding values that you can assign to MOBILITY, see the
    \l {http://doc.qt.nokia.com/qtmobility/quickstart.html}{Quickstart Example}.

    \section1 Adding Import Statements

    The wizard adds the import statements for Qt Quick and the Qt Quick
    Components for Symbian to the MainPage.qml file:

    \snippet examples/batterystatus/qml/BatteryStatus/MainPage.qml 3

    To use the Qt Mobility APIs, you must add the import statements for the
    Qt Mobility APIs that you use. This example uses the System Info API, so you
    must import it, as illustrated by the following code snippet:

    \snippet examples/batterystatus/qml/BatteryStatus/MainPage.qml 4

    Use the values as you can assign to MOBILITY also to construct import
    statements.

    \section1 Creating the Main View

    Qt Creator generates a default QML file that you can modify to create the
    main view of the application. It displays a progress bar and a text label
    that indicate the battery status.

    \list 1

        \o  Click \gui Design to open MainPage.qml in \QMLD.

        \o  In the \gui Navigator pane, select the \gui Text element to edit its
            properties in the \gui Properties pane.

        \o  In the \gui Text field, change the text from \bold {Hello World!}
            to \gui {Battery status: 1%}.

        \o  In the \gui Library view, \gui Items tab, select the
            \gui ProgressBar element, drag and drop it to the canvas, and edit
            its properties.

            \image qtcreator-symbian-components-example-ui.png "Qt Quick Components for Symbian"

            \list 1

                \o  Click \gui {Layout}, and then click the top anchor button.

                \o  In the \gui Target field, select \gui text1, to anchor the
                    progress bar to the bottom of the text field.

                \o In the \gui Margin field, select 20.

                \o  Click the horizontal anchor button, and select \gui text1 in
                    the \gui Target field to anchor the progress bar
                    horizontally to the text field.

                \o  To check that the application can be built and run, select
                    \gui {\QS} as the target and click the
                    \inlineimage qtcreator-run.png
                    button.

            \endlist

    \endlist

    \section1 Fetching Battery Status

    To fetch the battery status, open MainPage.qml in the code editor and add
    some code to it:

    \list 1

        \o  Add an invisible
            \l{http://doc.qt.nokia.com/qtmobility/qml-deviceinfo.html}
            {DeviceInfo element} that sets the
            \l{http://doc.qt.nokia.com/qtmobility/qml-deviceinfo.html}
            {monitorBatteryLevelChanges} property to true. It uses the
            \c monitorBatteryLevelChanges signal to keep up with changes in the
            battery level.

            \snippet examples/batterystatus/qml/BatteryStatus/MainPage.qml 0

        \o  Set an expression as the value of the text property of the Text
            element to display the battery level as a percentage:

            \snippet examples/batterystatus/qml/BatteryStatus/MainPage.qml 1

        \o  Set values for the ProgressBar element to display the battery level
            on the progress bar:

            \snippet examples/batterystatus/qml/BatteryStatus/MainPage.qml 2

    \endlist


    \section1 Compiling and Running Your Program

    Now that you have all the necessary code, select \gui {\QS}
    as the target and click the
    \inlineimage qtcreator-run.png
    button to build your program and run it in \QS.

    In \QS, run the runOutOfBattery.qs example script to see the value
    change in the Battery Status application. Select \gui {Scripting > examples
    > runOutOfBattery.qs > Run Selected Script}.

    \image qtcreator-symbian-components-example-simulated.png "Mobile example in Qt Simulator"

    \section1 Testing on a Symbian Device

    You also need to test the application on real devices. Before you can
    start testing on Symbian devices, you must connect them to the development
    PC by using a USB cable and install the necessary software on them.

    \list 1

        \o  Install Qt libraries, Qt mobile libraries, Qt Quick components for
            Symbian, and a debugging agent on the device. For more information,
            see \l{Connecting Symbian Devices}.

        \o  Start the CODA debugging agent on the device.

        \o  Click the \gui {Target Selector} and select \gui {Symbian Device}.

        \o  Click \gui Run to build the application for the Symbian device.

    \endlist

*/
