/****************************************************************************
**
** 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 samplephonebook
    \title Sample Phonebook Example

    \tableofcontents

    \section1 Phone Book

    This example shows how to write a simple phonebook with the \l{Contacts}{Contacts API}.

    \section2 Motivation
    This application was written to provide an example to developers of how to use the QtContacts and
    QtVersit APIs.

    It provides an example of how to use the QtMobility libraries to:
    \list
    \o select a backend for persistent storage
    \o list the stored contacts
    \o add contacts
    \o edit contacts
    \o use filters to find contacts matching certain criteria
    \o import and export contact lists as vCards\reg *
    \endlist

    [*] \i{vCard is a registered trademark of the Internet Mail Consortium}

    \section2 Use Case
    Most people have a need to store information (such as addresses, telephone numbers and email addresses)
    of people that they know.  This sample application provides a simple phone book that allows users
    to store certain pieces of information about their contacts, and save them to the contacts database of
    their device.

    \section2 Interface
    The application is designed to work on desktop and mobile platforms with
    minimal differences in code between the platforms.  The interface is
    organized into a paged view, showing the \i {Contact List} by default.
    Contacts can be added, edited or deleted using the buttons at the bottom
    of the contact list.
    To search for a contact in the list, a filter can be applied using the
    \i {Apply Filter} item in the \i Contacts menu.

    Here we see the \i {Contact List} with some names added.

    \image sample-phonebook-1.png

    When adding a new contact a new page is shown, with a \i{Set Picture}
    button to import an image. It is a good idea to use smaller images if
    you intend to export the contacts to a file later.

    \image sample-phonebook-2.png

    From the main menu, \i{Contacts}, you can select \i{Apply Filter}. This
    will display a new page which enables the user to specify filter criteria.
    In the screenshot below, we are selecting based on the first two characters
    of the Name,

    \image sample-phonebook-3.png

    which gives us a subset of the list of contacts.

    \image sample-phonebook-4.png

    To reset this, just select \i{Clear Filter} from the \i {Contacts} menu.

    The contact list can also be imported and exported to the vCard format
    through the \i {Import Contacts} and \i {Export Contacts} items in the
    \i Contacts menu.  This functionality can be used to populate the
    list from another device or application.

    \section2 Known Issues
    The example is not intended to be feature complete.  Only a very limited subset of detail types are
    supported by the application.  It exercises only a very small portion of the Qt Contacts API. 

    In particular:
    \list
        \o The example only exercises the synchronous API of QtContacts.  For most real applications, the
           asynchronous API is the preferred interface to use as it does not block the GUI while a query
           is made to the contacts backend.
        \o Detail subtypes and contexts are not supported by the interface.
        \o Duplicate contacts are not filtered out - importing the same contact twice results in two
           identical contacts appearing in the list.  In a real application, more complex synchronization
           code may be required.
        \o Contact groups are not supported.  The QtContacts API supports two methods of grouping contacts.
           One way is to use contacts of type \l{QContactType::TypeGroup}{TypeGroup}, along with the
           \l{QContactRelationship::HasMember}{HasMember} QContactRelationship.  The other way is to use
           the QContactTag detail by giving related contacts the same tag.  A real application may support
           grouping via one or both of these methods.
    \endlist

    This application has the following known issues on Harmattan:
    \list
        \o You cannot edit contacts because tapping QLineEdit widget does not open the virtual keyboard.
           See \l{https://bugreports.qt.nokia.com/browse/QTBUG-23144}{QTBUG-23144}
        \o You cannot set a thumbnail image for contacts. See \l{https://bugreports.qt.nokia.com/browse/QTMOBILITY-1992}{QTMOBILITY-1992}

*/
