/****************************************************************************

**

** 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$

** 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$

**

****************************************************************************/

/*!

\page queuedcustomtype

\example queuedcustomtype

\title Queued Custom Type Example

\section1 Description

The Queued Custom Type example shows how to send custom types between

threads with queued signals and slots.

\image queuedcustomtype-example.png

\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 queuedcustomtype/src/block.hpp 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 Renderer Class

We define a simple \c Renderer class with a private slot that accepts a

\c Block object. The rest of the class is concerned with managing the

user interface and handling images.

\snippet queuedcustomtype/src/renderer.hpp Renderer class definition

The \c Renderer class also contains a worker thread, provided by a

\c RenderThread object. This will emit signals to send \c Block objects

to the renderer's \c addBlock(Block) slot.

The parts of the \c Renderer class that are most relevant are the constructor

and the \c addBlock(Block) slot.

The constructor creates a thread for rendering images.

\snippet queuedcustomtype/src/renderer.cpp Renderer constructor start

\snippet queuedcustomtype/src/renderer.cpp set up widgets and connections

\snippet queuedcustomtype/src/renderer.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 renderer.

The \c addBlock(Block) slot receives blocks from the rendering thread via

the signal-slot connection set up in the constructor:

\snippet queuedcustomtype/src/renderer.cpp Adding blocks to the display

We simply create the pixel Container on the canvas container 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 queuedcustomtype/src/renderthread.hpp 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 queuedcustomtype/src/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 queuedcustomtype/src/renderthread.cpp processing the image (finish)

Each signal that is emitted will be queued and delivered later to the

renderer'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 queuedcustomtype/src/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.

\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.

*/