doc/src/custom-types.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Lesser General Public License Usage
  17 ** Alternatively, this file may be used under the terms of the GNU Lesser
  18 ** General Public License version 2.1 as published by the Free Software
  19 ** Foundation and appearing in the file LICENSE.LGPL included in the
  20 ** packaging of this file.  Please review the following information to
  21 ** ensure the GNU Lesser General Public License version 2.1 requirements
  22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  23 **
  24 ** In addition, as a special exception, Nokia gives you certain additional
  25 ** rights.  These rights are described in the Nokia Qt LGPL Exception
  26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  27 **
  28 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43     \page custom-types.html
  44     \title Creating Custom Qt Types
  45     \ingroup architecture
  46     \brief How to create and register new types with Qt.
  47
  48     \tableofcontents
  49
  50     \section1 Overview
  51
  52     When creating user interfaces with Qt, particularly those with specialized controls and
  53     features, developers sometimes need to create new data types that can be used alongside
  54     or in place of Qt's existing set of value types.
  55
  56     Standard types such as QSize, QColor and QString can all be stored in QVariant objects,
  57     used as the types of properties in QObject-based classes, and emitted in signal-slot
  58     communication.
  59
  60     In this document, we take a custom type and describe how to integrate it into Qt's object
  61     model so that it can be stored in the same way as standard Qt types. We then show how to
  62     register the custom type to allow it to be used in signals and slots connections.
  63
  64     \section1 Creating a Custom Type
  65
  66     Before we begin, we need to ensure that the custom type we are creating meets all the
  67     requirements imposed by QMetaType. In other words, it must provide:
  68
  69     \list
  70     \o a public default constructor,
  71     \o a public copy constructor, and
  72     \o a public destructor.
  73     \endlist
  74
  75     The following \c Message class definition includes these members:
  76
  77     \snippet examples/tools/customtype/message.h custom type definition
  78
  79     The class also provides a constructor for normal use and two public member functions
  80     that are used to obtain the private data.
  81
  82     \section1 Declaring the Type with QMetaType
  83
  84     The \c Message class only needs a suitable implementation in order to be usable.
  85     However, Qt's type system will not be able to understand how to store, retrieve
  86     and serialize instances of this class without some assistance. For example, we
  87     will be unable to store \c Message values in QVariant.
  88
  89     The class in Qt responsible for custom types is QMetaType. To make the type known
  90     to this class, we invoke the Q_DECLARE_METATYPE() macro on the class in the header
  91     file where it is defined:
  92
  93     \snippet examples/tools/customtype/message.h custom type meta-type declaration
  94
  95     This now makes it possible for \c Message values to be stored in QVariant objects
  96     and retrieved later. See the \l{Custom Type Example} for code that demonstrates
  97     this.
  98
  99     The Q_DECLARE_METATYPE() macro also makes it possible for these values to be used as
 100     arguments to signals, but \e{only in direct signal-slot connections}.
 101     To make the custom type generally usable with the signals and slots mechanism, we
 102     need to perform some extra work.
 103
 104     \section1 Creating and Destroying Custom Objects
 105
 106     Although the declaration in the previous section makes the type available for use
 107     in direct signal-slot connections, it cannot be used for queued signal-slot
 108     connections, such as those that are made between objects in different threads.
 109     This is because the meta-object system does not know how to handle creation and
 110     destruction of objects of the custom type at run-time.
 111
 112     To enable creation of objects at run-time, call the qRegisterMetaType() template
 113     function to register it with the meta-object system. This also makes the type
 114     available for queued signal-slot communication as long as you call it before you
 115     make the first connection that uses the type.
 116
 117     The \l{Queued Custom Type Example} declares a \c Block class which is registered
 118     in the \c{main.cpp} file:
 119
 120     \snippet examples/threads/queuedcustomtype/main.cpp main start
 121     \dots
 122     \snippet examples/threads/queuedcustomtype/main.cpp register meta-type for queued communications
 123     \dots
 124     \snippet examples/threads/queuedcustomtype/main.cpp main finish
 125
 126     This type is later used in a signal-slot connection in the \c{window.cpp} file:
 127
 128     \snippet examples/threads/queuedcustomtype/window.cpp Window constructor start
 129     \dots
 130     \snippet examples/threads/queuedcustomtype/window.cpp connecting signal with custom type
 131     \dots
 132     \snippet examples/threads/queuedcustomtype/window.cpp Window constructor finish
 133
 134     If a type is used in a queued connection without being registered, a warning will be
 135     printed at the console; for example:
 136
 137     \code
 138     QObject::connect: Cannot queue arguments of type 'Block'
 139     (Make sure 'Block' is registered using qRegisterMetaType().)
 140     \endcode
 141
 142     \section1 Making the Type Printable
 143
 144     It is often quite useful to make a custom type printable for debugging purposes,
 145     as in the following code:
 146
 147     \snippet examples/tools/customtype/main.cpp printing a custom type
 148
 149     This is achieved by creating a streaming operator for the type, which is often
 150     defined in the header file for that type:
 151
 152     \snippet examples/tools/customtype/message.h custom type streaming operator
 153
 154     The implementation for the \c Message type in the \l{Custom Type Example}
 155     goes to some effort to make the printable representation as readable as
 156     possible:
 157
 158     \snippet examples/tools/customtype/message.cpp custom type streaming operator
 159
 160     The output sent to the debug stream can, of course, be made as simple or as
 161     complicated as you like. Note that the value returned by this function is
 162     the QDebug object itself, though this is often obtained by calling the
 163     maybeSpace() member function of QDebug that pads out the stream with space
 164     characters to make it more readable.
 165
 166     \section1 Further Reading
 167
 168     The Q_DECLARE_METATYPE() macro and qRegisterMetaType() function documentation
 169     contain more detailed information about their uses and limitations.
 170
 171     The \l{Custom Type Example}{Custom Type},
 172     \l{Custom Type Sending Example}{Custom Type Sending}
 173     and \l{Queued Custom Type Example}{Queued Custom Type} examples show how to
 174     implement a custom type with the features outlined in this document.
 175
 176     The \l{Debugging Techniques} document provides an overview of the debugging
 177     mechanisms discussed above.
 178 */