/****************************************************************************
**
** 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 writemessage
    \title 'Write Message' Example



    This example demonstrates using the QtMobility Messaging API to
    create and send a simple message.

    \image writemessage-example.png

    The writemessage application provides an interface allowing the user to
    compose a simple message and send that message to one or more
    recipients.  The type of message that is sent will depend on the
    messaging account that the user selects for transmission.

    In order to know what type of message to create, our application
    requires that the user select an account to transmit with.  We create
    a listing to present the user a choice, by populating a combo box
    with the names of the available accounts:

    \snippet    ../../examples/writemessage/messagesender.cpp accounts-listing

    We create a mapping of the account name to the most capable type of message
    that can be transmitted via that account.  When an account is selected,
    we will adjust our UI to disable the message elements that cannot be
    transmitted using the associated message type.  For example, an SMS
    message cannot transmit attachments or a subject line.

    \snippet    ../../examples/writemessage/messagesender.cpp account-selected

    When the user presses the Send button, we create a message that contains
    the information they have provided.  First of all, we create a message
    object to transmit, and associate it with the account and message type
    that correspond to the user's account selection:

    \snippet    ../../examples/writemessage/messagesender.cpp associate-account

    Next, we process the recipient address or addresses that were provided.
    For each whitespace-separated element, we create an address object that
    has that element as the recipient, with the address type determined by
    the type of message we are constructing.

    \snippet    ../../examples/writemessage/messagesender.cpp set-recipients

    Next, we set the subject of the message (if the message can contain a subject)
    and set the text of the message.

    \snippet    ../../examples/writemessage/messagesender.cpp set-properties

    If the message can contain attachments, we add them as a list of file paths
    to be appended to the message:

    \snippet    ../../examples/writemessage/messagesender.cpp add-attachments

    Now that we have created our message, we use the QMessageService::send()
    operation to request that the message be stored in the system and transmitted:

    \snippet    ../../examples/writemessage/messagesender.cpp send-message

    To determine whether our transmission is successful, we wait for changes
    to the \l{QMessageService::state()}{state} of the QMessageService object.
    When the state changes to the FinishedState, we need to check whether
    the request was successful or not:

    \snippet    ../../examples/writemessage/messagesender.cpp handle-response

*/