/****************************************************************************
**
** 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 declarative-sfw-notes

\title Declarative Service Framework Notes Manager

\bold {Execution}

This example requires the example Notes Manager service to be pre-registered in order 
for the application to obtain the default interface. This can be done by using the 
service framework command line tool to add the corresponding service XML file:

\list
    \o ./servicefw add notesmanagerservice.xml
\endlist

There are 2 ways to run the example:
\list
    \o ./qmlnotes (only method for Symbian)
    \o qmlviewer declarative-sfw-notes.qml
\endlist

The XML files for all example services can be found in the QtMobility build directory
under install/bin/xmldata

\bold {Explanation}

This example demonstrates how to use the \l{notesmanagerplugin}{Notes Manager service plugin}
to implement a notes managing application with QML as the declarative user-interface.  There
is also a non-QML counterpart which demonstrates an identical application using standard Qt
user-interface tools.  See \l{sfw-notes}{Service Framework Notes Manager} for more details.

The QServiceManager and QServiceInterfaceDescriptor API are provided to QML through the use
of a plugin-based system that allows users to describe a service as a QML element called 
\l Service.  The service framework QML plugin also acces to an instance of the service from
within QML so that clients can make metacalls on the service object.

This example demonstrates how QML can be used to completely control the logic of the 
application, using a combination of declarative elements and Javascript code.  To run the 
application refer to the above execution instructions on how to setup and run the example.

There is also another service framework example that demonstrates how to use the QML library 
plugin browse a list of services to select for dialing usage.  See 
\l{declarative-sfw-dialer}{Declarative Service Framework Dialer} for a detailed explanation.

The section below explains how QML can be used to emulate to exact functionality of the
alternate Qt/C++ example.


\bold {QML File}

The very first step is to import our QtMobility Service Framework QML plugin library which
containts the required QML elements:
\snippet declarative-sfw-notes/content-sfw-notes/Main.qml 0

In most cases we will need the service instance to be available to all parts of the QML file,
meaning that we should declare a global variant for the QObject returned from the service
instance. It is also good practice to initialise this value to 0.
\snippet declarative-sfw-notes/content-sfw-notes/Main.qml 1

Now we can initiate our \l Service element with a default interface name and obtain the
service instance to our global object variable in the component on-completion section.
\snippet declarative-sfw-notes/content-sfw-notes/Main.qml 6

Although a default instance is obtained, the application allows for manually specifying
the Service::interfaceName property of the \l Service element to check if there was a 
valid default service at this interface name. Similarly, if there is a valid descriptor 
then the service instance can be obtained and we can call the initialise code of our
notes manager.
\snippet declarative-sfw-notes/content-sfw-notes/Main.qml 2

Connecting signals from our service object requires the following code. Note the use
of the ignoreUnknownSignals property which removes warnings for connecting unknown signals
before QML has obtained its QObject service instance.
\snippet declarative-sfw-notes/content-sfw-notes/Main.qml 7

With a valid reference which points to the service plugin class we can now invoke methods 
directly from the Notes Manager plugin. The example below shows how to obtain a list of
notes and delete one from the notes manager database through QML.
\snippet declarative-sfw-notes/content-sfw-notes/Main.qml 3

The Notes Manager plugin also provides readable functions which return the values of a
single note and can be utilized to display on the UI as follows:
\snippet declarative-sfw-notes/content-sfw-notes/Main.qml 4
\snippet declarative-sfw-notes/content-sfw-notes/Main.qml 5
*/
