← Back to branch summary

~ubuntu-branches/ubuntu/wily/qtbase-opensource-src/wily

« back to all changes in this revision

Viewing changes to doc/src/examples/customtypesending.qdoc

  • Committer: Package Import Robot
  • Author(s): Timo Jyrinki
  • Date: 2013-02-05 12:46:17 UTC
  • Revision ID: package-import@ubuntu.com-20130205124617-c8jouts182j002fx
Tags: upstream-5.0.1+dfsg
Import upstream version 5.0.1+dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/examples/customtypesending.qdoc
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
 
4
** Contact: http://www.qt-project.org/legal
 
5
**
 
6
** This file is part of the documentation of the Qt Toolkit.
 
7
**
 
8
** $QT_BEGIN_LICENSE:FDL$
 
9
** Commercial License Usage
 
10
** Licensees holding valid commercial Qt licenses may use this file in
 
11
** accordance with the commercial license agreement provided with the
 
12
** Software or, alternatively, in accordance with the terms contained in
 
13
** a written agreement between you and Digia.  For licensing terms and
 
14
** conditions see http://qt.digia.com/licensing.  For further information
 
15
** use the contact form at http://qt.digia.com/contact-us.
 
16
**
 
17
** GNU Free Documentation License Usage
 
18
** Alternatively, this file may be used under the terms of the GNU Free
 
19
** Documentation License version 1.3 as published by the Free Software
 
20
** Foundation and appearing in the file included in the packaging of
 
21
** this file.  Please review the following information to ensure
 
22
** the GNU Free Documentation License version 1.3 requirements
 
23
** will be met: http://www.gnu.org/copyleft/fdl.html.
 
24
** $QT_END_LICENSE$
 
25
**
 
26
****************************************************************************/
 
27
 
 
28
/*!
 
29
    \example tools/customtypesending
 
30
    \title Custom Type Sending Example
 
31
 
 
32
    The Custom Type Sending example shows how to use a custom type with signals
 
33
    and slots.
 
34
 
 
35
    \image customtypesending-example.png
 
36
 
 
37
    \section1 Overview
 
38
 
 
39
    In the \l{Custom Type Example}, we showed how to integrate custom types
 
40
    with the meta-object system, enabling them to be stored in QVariant
 
41
    objects, written out in debugging information and used in signal-slot
 
42
    communication.
 
43
 
 
44
    In this example, we demonstrate that the preparations made to the
 
45
    \c Message class and its declaration with Q_DECLARE_METATYPE() enable it
 
46
    to be used with direct signal-slot connections. We do this by creating
 
47
    a \c Window class containing signals and slots whose signatures include
 
48
    \c Message arguments.
 
49
 
 
50
    \section1 The Window and Message Class Definitions
 
51
 
 
52
    We define a simple \c Window class with a signal and public slot that
 
53
    allow a \c Message object to be sent via a signal-slot connection:
 
54
 
 
55
    \snippet examples/tools/customtypesending/window.h Window class definition
 
56
 
 
57
    The window will contain a text editor to show the contents of a message
 
58
    and a push button that the user can click to send a message. To facilitate
 
59
    this, we also define the \c sendMessage() slot. We also keep a \c Message
 
60
    instance in the \c thisMessage private variable which holds the actual
 
61
    message to be sent.
 
62
 
 
63
    The \c Message class is defined in the following way:
 
64
    
 
65
    \snippet examples/tools/customtypesending/message.h custom type definition
 
66
 
 
67
    The type is declared to the meta-type system with the Q_DECLARE_METATYPE()
 
68
    macro:
 
69
 
 
70
    \snippet examples/tools/customtypesending/message.h custom type meta-type declaration
 
71
 
 
72
    This will make the type available for use in direct signal-slot connections.
 
73
 
 
74
    \section1 The Window Class Implementation
 
75
 
 
76
    The \c Window constructor sets up a user interface containing a text
 
77
    editor and a push button.
 
78
 
 
79
    \snippet examples/tools/customtypesending/window.cpp Window constructor
 
80
 
 
81
    The button's \l{QPushButton::}{clicked()} signal is connected to the
 
82
    window's \c{sendMessage()} slot, which emits the \c{messageSent(Message)}
 
83
    signal with the \c Message held by the \c thisMessage variable:
 
84
 
 
85
    \snippet examples/tools/customtypesending/window.cpp sending a message
 
86
 
 
87
    We implement a slot to allow the message to be received, and this also
 
88
    lets us set the message in the window programatically:
 
89
 
 
90
    \snippet examples/tools/customtypesending/window.cpp receiving a message
 
91
 
 
92
    In this function, we simply assign the new message to \c thisMessage
 
93
    and update the text in the editor.
 
94
 
 
95
    \section1 Making the Connection
 
96
 
 
97
    In the example's \c{main()} function, we perform the connection between
 
98
    two instances of the \c Window class:
 
99
 
 
100
    \snippet examples/tools/customtypesending/main.cpp main function
 
101
 
 
102
    We set the message for the first window and connect the
 
103
    \c{messageSent(Message)} signal from each window to the other's
 
104
    \c{setMessage(Message)} slot. Since the signals and slots mechanism is only
 
105
    concerned with the type, we can simplify the signatures of both the
 
106
    signal and slot when we make the connection.
 
107
 
 
108
    When the user clicks on the \uicontrol{Send message} button in either window,
 
109
    the message shown will be emitted in a signal that the other window will
 
110
    receive and display.
 
111
 
 
112
    \section1 Further Reading
 
113
 
 
114
    Although the custom \c Message type can be used with direct signals and
 
115
    slots, an additional registration step needs to be performed if you want
 
116
    to use it with queued signal-slot connections. See the
 
117
    \l{Queued Custom Type Example} for details.
 
118
 
 
119
    More information on using custom types with Qt can be found in the
 
120
    \l{Creating Custom Qt Types} document.
 
121
*/