/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** 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.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\example quickstart

\title Quickstart guide

The following steps outline how to make a simple
"hello world" like application that uses Qt Mobility.
It is assumed that Qt Mobility has been
successfully built and environment variables have been set
as per \l {Installation Guide}.

One can start using QtMobility with 3 simple steps.
\list 1
    \o Include the appropriate headers
    \o Use the QTM_USE_NAMESPACE macro (defined in qmobilityglobal.h but implicitly included from any QtMobility header)
    \o Declare the usage of QtMobility
       and appropriate API(s) in the project(.pro) file
\endlist

Steps 1 and 2 are shown in the example below:
\snippet quickstart/main.cpp 0

This example uses the QSystemInfo headers to print out the
system's current country code.  All the domain APIs are wrapped
within a Qt Mobility namespace and thus developers
need to use the QTM_USE_NAMESPACE macro.

In step 3, to specify that our project is using
System Information we declare in the project file:

\snippet quickstart/quickstart.pro 0

The project file states that the application uses Qt Mobility and that it requires the
System Information API. By adding \c mobility to \c CONFIG qmake finds
the \c {mobility.prf} file in \c{$QTDIR/mkspecs/features} and includes it when
processing the current project file. \c{mobility.prf} is generated when running
the QtMobility configure script and points qmake to the relevant include and prefix
paths and ensures that deployment and package dependencies are set. The \c MOBILITY variable itself is part of \c {mobility.prf} and is used to
determine the QtMobility library the current project should link to (in this example the SystemInfo library).

Each QtMobility API has its corresponding value which has to be added to \c MOBILITY. The subsequent table lists the APIs and the
corresponding values that can be assigned to \c MOBILITY.

\table
\header
    \o Domain
    \o Value
\row
    \o \l {Bearer Management}
    \o bearer
\row
    \o \l {Contacts}
    \o contacts
\row
    \o \l {Location}
    \o location
\row
    \o \l {Multimedia}
    \o multimedia
\row
    \o \l {Messaging}
    \o messaging
\row
    \o \l {Publish And Subscribe}
    \o publishsubscribe
\row
    \o \l {Qt Service Framework} {Service Framework}
    \o serviceframework
\row
    \o \l {Sensor}{Sensors}
    \o sensors
\row
    \o \l {System Information}
    \o systeminfo
\row
    \o \l {Versit}{Versit}
    \o versit
\row
    \o \l {Document Gallery}
    \o gallery
\row
    \o \l {Organizer}
    \o organizer
\row
    \o \l {Feedback}{Tactile Feedback}
    \o feedback
\endtable

In addition the Mobility version and installed modules can be checked from within qmake project files. The associated module name for such tests is the same as above:

\code
    load(mobilityconfig)
    contains(MOBILITY_VERSION, 1.1.1) {
        message(Mobility 1.1.1 detected)
    }
    contains(MOBILITY_CONFIG, contacts) {
        message(Contacts API available)
        CONFIG+=mobility
        MOBILITY+=contacts
    } else {
        message(Contacts API not available)
    }
\endcode

When developing on Symbian we will also need to add the required capabilites to the project file in order to satisfy the Symbian security model.
This can be achieved with a line such as the following:

\code
    TARGET.CAPABILITY = CAPABILITY_A CABAPILITY_B
\endcode

CAPABILITY_A and CAPABILITY_B are place holders for the appropriate Symbian
capabilities. A complete list of all Symbian capabilities and their availability
to application developers can be found in the
\l {http://wiki.forum.nokia.com/index.php/Capabilities}{Forum Nokia Symbian capability documentation}.

The subsequent table provides an overview of possibily required security tokens for each QtMobility library.
Note that not all tokens are always required when using a particular API. The exact list depends
on which parts of an API is utilized by an application.

\table
\header
    \o Domain
    \o Symbian Capabilities
    \o Harmattan Tokens (\l{http://www.developer.nokia.com/Community/Wiki/Harmattan:Developer_Library/Developing_for_Harmattan/Harmattan_security/Security_guide}{Aegis})
\row
    \o \l {Bearer Management}
    \o ReadUserData NetworkServices (NetworkControl for QNetworkSession::stop())
    \o No token requirements known at this stage.
\row
    \o \l {Connectivity}{Connectivity - NFC}
    \o LocalServices
    \o No token requirements known at this stage.
\row
    \o \l {Connectivity}{Connectivity - Bluetooth} 
    \o LocalServices NetworkServices (ReadDeviceData WriteDeviceData for Pairing control)
    \o No token requirements known at this stage.
\row
    \o \l {Contacts}
    \o ReadUserData WriteUserData
    \o TrackerReadAccess TrackerWriteAccess GRP::metadata-users
\row
    \o \l {Location}
    \o Location LocalServices ReadUserData WriteUserData ReadDeviceData WriteDeviceData NetworkServices
    \o Location TrackerReadAccess TrackerWriteAccess
\row
    \o \l {Multimedia}
    \o UserEnvironment ReadUserData WriteUserData ReadDeviceData WriteDeviceData
    \o GRP::video GRP::pulse-access
\row
    \o \l {Messaging}
    \o LocalServices ReadUserData WriteUserData NetworkServices UserEnvironment ReadDeviceData WriteDeviceData
    \o Cellular TrackerReadAccess TrackerWriteAccess
\row
    \o \l {Publish And Subscribe}
    \o Capability depends on P&S value being read/written. API itself doesn't require any capability.
    \o No token requirements known at this stage.
\row
    \o \l {Qt Service Framework} {Service Framework}
    \o No capabilities requried by itself, the plugins may have capability requirements.
    \o No token requirements known at this stage.
\row
    \o \l {Sensor}
    \o ReadDeviceData
    \o No token requirements known at this stage.
\row
    \o \l {System Information}
    \o LocalServices ReadUserData WriteUserData NetworkServices UserEnvironment Location ReadDeviceData
    \o mce::TKLockControl mce::DeviceModeControl
\row
    \o \l {Versit}
    \o No additional capabilities required.
    \o No token requirements known at this stage.
\row
    \o \l {Document Gallery}
    \o ReadDeviceData WriteDeviceData
    \o TrackerReadAccess TrackerWriteAccess
\row
    \o \l {Organizer}
    \o ReadUserData WriteUserData
    \o TrackerReadAccess TrackerWriteAccess GRP::calendar GRP::metadata-users
\row
    \o \l {Feedback}{Tactile Feedback}
    \o No capabilities at this stage.
    \o No token requirements known at this stage.
\endtable

The complete list of all Symbian capabilities and how they can be obtained can
be found at \l {http://wiki.forum.nokia.com/index.php/Capabilities}{Forum Nokia Symbian capability documentation}.

And we're done.  If you are using the command line simply
enter:
\code
    qmake
    make //or nmake on Windows
\endcode

to generate the executable which can then be run.

If you are developing for Symbian, to make a debug build for the emulator run:
\code
    qmake
    make debug-winscw
\endcode
This assumes that qmake is in your %PATH% and Qt has been built for the emulator already.


To make a release build and SIS package for a device run:
\code
    qmake
    make release-gcce
    make sis
\endcode

For further details on how to build applications for
Symbian see \l {http://qt.nokia.com/doc/4.6/symbian-with-qt-introduction.html}
{The Symbian Platform - Introduction to Qt} and \l {http://wiki.forum.nokia.com/index.php/Category:Qt_for_Symbian}
{Qt for Symbian}
*/