1 files changed, 163 insertions, 0 deletions
diff --git a/doc/src/examples/queuedcustomtype.qdoc b/doc/src/examples/queuedcustomtype.qdoc
new file mode 100644
index 0000000000..3df7e4d6aa
--- /dev/null
+++ b/doc/src/examples/queuedcustomtype.qdoc
@@ -0,0 +1,163 @@
+/****************************************************************************
+**
+** 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 threads/queuedcustomtype
+    \title Queued Custom Type Example
+
+    The Queued Custom Type example shows how to send custom types between
+    threads with queued signals and slots.
+
+    \image queuedcustomtype-example.png
+
+    Contents:
+
+    \tableofcontents
+
+    \section1 Overview
+
+    In the \l{Custom Type Sending Example}, we showed how to use a custom type
+    with signal-slot communication within the same thread.
+
+    In this example, we create a new value class, \c Block, and register it
+    with the meta-object system to enable us to send instances of it between
+    threads using queued signals and slots.
+
+    \section1 The Block Class
+
+    The \c Block class is similar to the \c Message class described in the
+    \l{Custom Type Example}. It provides the default constructor, copy
+    constructor and destructor in the public section of the class that the
+    meta-object system requires. It describes a colored rectangle.
+
+    \snippet examples/threads/queuedcustomtype/block.h custom type definition and meta-type declaration
+
+    We will still need to register it with the meta-object system at
+    run-time by calling the qRegisterMetaType() template function before
+    we make any signal-slot connections that use this type.
+    Even though we do not intend to use the type with QVariant in this example,
+    it is good practice to also declare the new type with Q_DECLARE_METATYPE().
+
+    The implementation of the \c Block class is trivial, so we avoid quoting
+    it here.
+
+    \section1 The Window Class
+
+    We define a simple \c Window class with a public slot that accepts a
+    \c Block object. The rest of the class is concerned with managing the
+    user interface and handling images.
+
+    \snippet examples/threads/queuedcustomtype/window.h Window class definition
+
+    The \c Window class also contains a worker thread, provided by a
+    \c RenderThread object. This will emit signals to send \c Block objects
+    to the window's \c addBlock(Block) slot.
+
+    The parts of the \c Window class that are most relevant are the constructor
+    and the \c addBlock(Block) slot.
+
+    The constructor creates a thread for rendering images, sets up a user
+    interface containing a label and two push buttons that are connected to
+    slots in the same class.
+
+    \snippet examples/threads/queuedcustomtype/window.cpp Window constructor start
+    \snippet examples/threads/queuedcustomtype/window.cpp set up widgets and connections
+    \snippet examples/threads/queuedcustomtype/window.cpp connecting signal with custom type
+
+    In the last of these connections, we connect a signal in the
+    \c RenderThread object to the \c addBlock(Block) slot in the window.
+
+    \dots
+    \snippet examples/threads/queuedcustomtype/window.cpp Window constructor finish
+
+    The rest of the constructor simply sets up the layout of the window.
+
+    The \c addBlock(Block) slot receives blocks from the rendering thread via
+    the signal-slot connection set up in the constructor:
+
+    \snippet examples/threads/queuedcustomtype/window.cpp Adding blocks to the display
+
+    We simply paint these onto the label as they arrive.
+
+    \section1 The RenderThread Class
+
+    The \c RenderThread class processes an image, creating \c Block objects
+    and using the \c sendBlock(Block) signal to send them to other components
+    in the example.
+
+    \snippet examples/threads/queuedcustomtype/renderthread.h RenderThread class definition
+
+    The constructor and destructor are not quoted here. These take care of
+    setting up the thread's internal state and cleaning up when it is destroyed.
+
+    Processing is started with the \c processImage() function, which calls the
+    \c RenderThread class's reimplementation of the QThread::run() function:
+
+    \snippet examples/threads/queuedcustomtype/renderthread.cpp processing the image (start)
+
+    Ignoring the details of the way the image is processed, we see that the
+    signal containing a block is emitted in the usual way:
+
+    \dots
+    \snippet examples/threads/queuedcustomtype/renderthread.cpp processing the image (finish)
+
+    Each signal that is emitted will be queued and delivered later to the
+    window's \c addBlock(Block) slot.
+
+    \section1 Registering the Type
+
+    In the example's \c{main()} function, we perform the registration of the
+    \c Block class as a custom type with the meta-object system by calling the
+    qRegisterMetaType() template function:
+
+    \snippet examples/threads/queuedcustomtype/main.cpp main function
+
+    This call is placed here to ensure that the type is registered before any
+    signal-slot connections are made that use it.
+
+    The rest of the \c{main()} function is concerned with setting a seed for
+    the pseudo-random number generator, creating and showing the window, and
+    setting a default image. See the source code for the implementation of the
+    \c createImage() function.
+
+    \section1 Further Reading
+
+    This example showed how a custom type can be registered with the
+    meta-object system so that it can be used with signal-slot connections
+    between threads. For ordinary communication involving direct signals and
+    slots, it is enough to simply declare the type in the way described in the
+    \l{Custom Type Sending Example}.
+
+    In practice, both the Q_DECLARE_METATYPE() macro and the qRegisterMetaType()
+    template function can be used to register custom types, but
+    qRegisterMetaType() is only required if you need to perform signal-slot
+    communication or need to create and destroy objects of the custom type
+    at run-time.
+
+    More information on using custom types with Qt can be found in the
+    \l{Creating Custom Qt Types} document.
+*/