From e204b33f54d07df555b48ca10003789bd2c3b715 Mon Sep 17 00:00:00 2001 From: Olivier Goffart Date: Thu, 10 Nov 2011 12:17:53 +0100 Subject: Document the new connection syntax It is already documented in the QObject API documentation, but Also update the overview Change-Id: I92f44a50222738530928e3f4e6e463b3210d3a29 Reviewed-by: Bradley T. Hughes --- doc/src/core/objectmodel/signalsandslots.qdoc | 51 ++++++++++++++-------- doc/src/snippets/signalmapper/filereader.cpp | 12 ++--- .../snippets/signalsandslots/signalsandslots.cpp | 4 +- 3 files changed, 42 insertions(+), 25 deletions(-) (limited to 'doc/src') diff --git a/doc/src/core/objectmodel/signalsandslots.qdoc b/doc/src/core/objectmodel/signalsandslots.qdoc index 2f8646ea1c..175f7e1b07 100644 --- a/doc/src/core/objectmodel/signalsandslots.qdoc +++ b/doc/src/core/objectmodel/signalsandslots.qdoc @@ -195,8 +195,9 @@ Signals are emitted by an object when its internal state has changed in some way that might be interesting to the object's client or owner. - Only the class that defines a signal and its subclasses can emit the - signal. + Signals are public access functions and can be emitted from anywhere, + but we recommend to only emit them from the class that defines the + signal and its subclasses. When a signal is emitted, the slots connected to it are usually executed immediately, just like a normal function call. When this @@ -253,15 +254,10 @@ string, vector or list operation that behind the scene requires \c new or \c delete, the signals and slots overhead is only responsible for a very small proportion of the complete function - call costs. - - The same is true whenever you do a system call in a slot; or - indirectly call more than ten functions. On an i586-500, you can - emit around 2,000,000 signals per second connected to one - receiver, or around 1,200,000 per second connected to two - receivers. The simplicity and flexibility of the signals and - slots mechanism is well worth the overhead, which your users - won't even notice. + call costs. The same is true whenever you do a system call in a slot; + or indirectly call more than ten functions. + The simplicity and flexibility of the signals and slots mechanism is + well worth the overhead, which your users won't even notice. Note that other libraries that define variables called \c signals or \c slots may cause compiler warnings and errors when compiled @@ -381,8 +377,30 @@ void objectDestroyed(QObject* obj = 0); \endcode - To connect the signal to the slot, we use QObject::connect() and - the \c{SIGNAL()} and \c{SLOT()} macros. The rule about whether to + To connect the signal to the slot, we use QObject::connect(). + There are several ways to connect signal and slots. The first is to use + function pointers: + \code + connect(sender, &QObject::destroyed, this, &MyObject::objectDestroyed); + \endcode + + There are several advantages to using connect() with function pointers. + First, it allows the compiler to check that the signal's arguments are + compatible with the slot's arguments. Arguments can also be implicitly + converted by the compiler, if needed. + + You can also connect to functors or C++11 lamdas: + + \code + connect(sender, &QObject::destroyed, [=](){ this->m_objects.remove(sender); }); + \endcode + + Note that if your compiler does not support C++11 variadic templates, + this syntax only works if the signal and slot have 3 arguments or less. + + The other way to connect a signal to a slot is to use QObject::connect() + and the \c{SIGNAL} and \c{SLOT} macros. + The rule about whether to include arguments or not in the \c{SIGNAL()} and \c{SLOT()} macros, if the arguments have default values, is that the signature passed to the \c{SIGNAL()} macro must \e not have fewer @@ -402,6 +420,9 @@ ...because the slot will be expecting a QObject that the signal will not send. This connection will report a runtime error. + Note that signal and slot arguments are not checked by the compiler when + using this QObject::connect() overload. + \section1 Advanced Signals and Slots Usage For cases where you may require information on the sender of the @@ -427,10 +448,6 @@ \snippet doc/src/snippets/signalmapper/filereader.cpp 1 - \note The following code will compile and run, but due to signature normalization, the code will be slower. - - \snippet doc/src/snippets/signalmapper/filereader.cpp 2 - \sa {Meta-Object System}, {Qt's Property System} \target 3rd Party Signals and Slots diff --git a/doc/src/snippets/signalmapper/filereader.cpp b/doc/src/snippets/signalmapper/filereader.cpp index d7be2e854b..49b69055c5 100644 --- a/doc/src/snippets/signalmapper/filereader.cpp +++ b/doc/src/snippets/signalmapper/filereader.cpp @@ -57,12 +57,12 @@ FileReader::FileReader(QWidget *parent) signalMapper->setMapping(accountFileButton, QString("accountsfile.txt")); signalMapper->setMapping(reportFileButton, QString("reportfile.txt")); - connect(taxFileButton, SIGNAL(clicked()), - signalMapper, SLOT (map())); - connect(accountFileButton, SIGNAL(clicked()), - signalMapper, SLOT (map())); - connect(reportFileButton, SIGNAL(clicked()), - signalMapper, SLOT (map())); + connect(taxFileButton, &QPushButton::clicked, + signalMapper, &QSignalMapper::map); + connect(accountFileButton, &QPushButton::clicked, + signalMapper, &QSignalMapper::map); + connect(reportFileButton, &QPushButton::clicked, + signalMapper, &QSignalMapper::map); //! [0] //! [1] diff --git a/doc/src/snippets/signalsandslots/signalsandslots.cpp b/doc/src/snippets/signalsandslots/signalsandslots.cpp index 42622322ed..19a8b4d5cd 100644 --- a/doc/src/snippets/signalsandslots/signalsandslots.cpp +++ b/doc/src/snippets/signalsandslots/signalsandslots.cpp @@ -57,8 +57,8 @@ int main() //! [1] Counter a, b; //! [1] //! [2] - QObject::connect(&a, SIGNAL(valueChanged(int)), - &b, SLOT(setValue(int))); + QObject::connect(&a, &Counter::valueChanged, + &b, &Counter::setValue); //! [2] //! [3] -- cgit v1.2.3