diff options
Diffstat (limited to 'doc/src/examples/customtypesending.qdoc')
-rw-r--r-- | doc/src/examples/customtypesending.qdoc | 121 |
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. +*/ |