Initial import from the monolithic Qt.

This is the beginning of revision history for this module. If you
want to look at revision history older than this, please refer to the
Qt Git wiki for how to use Git history grafting. At the time of
writing, this wiki is located here:

http://qt.gitorious.org/qt/pages/GitIntroductionWithQt

If you have already performed the grafting and you don't see any
history beyond this commit, try running "git log" with the "--follow"
argument.

Branched from the monolithic repo, Qt master branch, at commit
896db169ea224deb96c59ce8af800d019de63f12

1 files changed, 121 insertions, 0 deletions

diff --git a/doc/src/examples/customtypesending.qdoc b/doc/src/examples/customtypesending.qdoc
new file mode 100644
index 0000000000..ce4f42d727
--- /dev/null
+++ b/doc/src/examples/customtypesending.qdoc
@@ -0,0 +1,121 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $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.
+*/