/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example tools/customtypesending
    \title Custom Type Sending Example

    The Custom Type Sending example shows how to use a custom type with signals
    and slots.

    \image customtypesending-example.png

    \section1 Overview

    In the \l{Custom Type Example}, we showed how to integrate custom types
    with the meta-object system, enabling them to be stored in QVariant
    objects, written out in debugging information and used in signal-slot
    communication.

    In this example, we demonstrate that the preparations made to the
    \c Message class and its declaration with Q_DECLARE_METATYPE() enable it
    to be used with direct signal-slot connections. We do this by creating
    a \c Window class containing signals and slots whose signatures include
    \c Message arguments.

    \section1 The Window and Message Class Definitions

    We define a simple \c Window class with a signal and public slot that
    allow a \c Message object to be sent via a signal-slot connection:

    \snippet examples/tools/customtypesending/window.h Window class definition

    The window will contain a text editor to show the contents of a message
    and a push button that the user can click to send a message. To facilitate
    this, we also define the \c sendMessage() slot. We also keep a \c Message
    instance in the \c thisMessage private variable which holds the actual
    message to be sent.

    The \c Message class is defined in the following way:
    
    \snippet examples/tools/customtypesending/message.h custom type definition

    The type is declared to the meta-type system with the Q_DECLARE_METATYPE()
    macro:

    \snippet examples/tools/customtypesending/message.h custom type meta-type declaration

    This will make the type available for use in direct signal-slot connections.

    \section1 The Window Class Implementation

    The \c Window constructor sets up a user interface containing a text
    editor and a push button.

    \snippet examples/tools/customtypesending/window.cpp Window constructor

    The button's \l{QPushButton::}{clicked()} signal is connected to the
    window's \c{sendMessage()} slot, which emits the \c{messageSent(Message)}
    signal with the \c Message held by the \c thisMessage variable:

    \snippet examples/tools/customtypesending/window.cpp sending a message

    We implement a slot to allow the message to be received, and this also
    lets us set the message in the window programatically:

    \snippet examples/tools/customtypesending/window.cpp receiving a message

    In this function, we simply assign the new message to \c thisMessage
    and update the text in the editor.

    \section1 Making the Connection

    In the example's \c{main()} function, we perform the connection between
    two instances of the \c Window class:

    \snippet examples/tools/customtypesending/main.cpp main function

    We set the message for the first window and connect the
    \c{messageSent(Message)} signal from each window to the other's
    \c{setMessage(Message)} slot. Since the signals and slots mechanism is only
    concerned with the type, we can simplify the signatures of both the
    signal and slot when we make the connection.

    When the user clicks on the \gui{Send message} button in either window,
    the message shown will be emitted in a signal that the other window will
    receive and display.

    \section1 Further Reading

    Although the custom \c Message type can be used with direct signals and
    slots, an additional registration step needs to be performed if you want
    to use it with queued signal-slot connections. See the
    \l{Queued Custom Type Example} for details.

    More information on using custom types with Qt can be found in the
    \l{Creating Custom Qt Types} document.
*/