src/corelib/kernel/qsignalmapper.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 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 QtCore module of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** GNU Lesser General Public License Usage
  11 ** This file may be used under the terms of the GNU Lesser General Public
  12 ** License version 2.1 as published by the Free Software Foundation and
  13 ** appearing in the file LICENSE.LGPL included in the packaging of this
  14 ** file. Please review the following information to ensure the GNU Lesser
  15 ** General Public License version 2.1 requirements will be met:
  16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  17 **
  18 ** In addition, as a special exception, Nokia gives you certain additional
  19 ** rights. These rights are described in the Nokia Qt LGPL Exception
  20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  21 **
  22 ** GNU General Public License Usage
  23 ** Alternatively, this file may be used under the terms of the GNU General
  24 ** Public License version 3.0 as published by the Free Software Foundation
  25 ** and appearing in the file LICENSE.GPL included in the packaging of this
  26 ** file. Please review the following information to ensure the GNU General
  27 ** Public License version 3.0 requirements will be met:
  28 ** http://www.gnu.org/copyleft/gpl.html.
  29 **
  30 ** Other Usage
  31 ** Alternatively, this file may be used in accordance with the terms and
  32 ** conditions contained in a signed written agreement between you and Nokia.
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qsignalmapper.h"
  43 #ifndef QT_NO_SIGNALMAPPER
  44 #include "qhash.h"
  45 #include "qobject_p.h"
  46
  47 QT_BEGIN_NAMESPACE
  48
  49 class QSignalMapperPrivate : public QObjectPrivate
  50 {
  51     Q_DECLARE_PUBLIC(QSignalMapper)
  52 public:
  53     void _q_senderDestroyed() {
  54         Q_Q(QSignalMapper);
  55         q->removeMappings(q->sender());
  56     }
  57     QHash<QObject *, int> intHash;
  58     QHash<QObject *, QString> stringHash;
  59     QHash<QObject *, QWidget*> widgetHash;
  60     QHash<QObject *, QObject*> objectHash;
  61
  62 };
  63
  64
  65 /*!
  66     \class QSignalMapper
  67     \brief The QSignalMapper class bundles signals from identifiable senders.
  68
  69     \ingroup objectmodel
  70
  71
  72     This class collects a set of parameterless signals, and re-emits
  73     them with integer, string or widget parameters corresponding to
  74     the object that sent the signal.
  75
  76     The class supports the mapping of particular strings or integers
  77     with particular objects using setMapping(). The objects' signals
  78     can then be connected to the map() slot which will emit the
  79     mapped() signal with the string or integer associated with the
  80     original signalling object. Mappings can be removed later using
  81     removeMappings().
  82
  83     Example: Suppose we want to create a custom widget that contains
  84     a group of buttons (like a tool palette). One approach is to
  85     connect each button's \c clicked() signal to its own custom slot;
  86     but in this example we want to connect all the buttons to a
  87     single slot and parameterize the slot by the button that was
  88     clicked.
  89
  90     Here's the definition of a simple custom widget that has a single
  91     signal, \c clicked(), which is emitted with the text of the button
  92     that was clicked:
  93
  94     \snippet doc/src/snippets/qsignalmapper/buttonwidget.h 0
  95     \snippet doc/src/snippets/qsignalmapper/buttonwidget.h 1
  96
  97     The only function that we need to implement is the constructor:
  98
  99     \snippet doc/src/snippets/qsignalmapper/buttonwidget.cpp 0
 100     \snippet doc/src/snippets/qsignalmapper/buttonwidget.cpp 1
 101     \snippet doc/src/snippets/qsignalmapper/buttonwidget.cpp 2
 102
 103     A list of texts is passed to the constructor. A signal mapper is
 104     constructed and for each text in the list a QPushButton is
 105     created. We connect each button's \c clicked() signal to the
 106     signal mapper's map() slot, and create a mapping in the signal
 107     mapper from each button to the button's text. Finally we connect
 108     the signal mapper's mapped() signal to the custom widget's \c
 109     clicked() signal. When the user clicks a button, the custom
 110     widget will emit a single \c clicked() signal whose argument is
 111     the text of the button the user clicked.
 112
 113     \sa QObject, QButtonGroup, QActionGroup
 114 */
 115
 116 /*!
 117     Constructs a QSignalMapper with parent \a parent.
 118 */
 119 QSignalMapper::QSignalMapper(QObject* parent)
 120     : QObject(*new QSignalMapperPrivate, parent)
 121 {
 122 }
 123
 124 /*!
 125     Destroys the QSignalMapper.
 126 */
 127 QSignalMapper::~QSignalMapper()
 128 {
 129 }
 130
 131 /*!
 132     Adds a mapping so that when map() is signalled from the given \a
 133     sender, the signal mapped(\a id) is emitted.
 134
 135     There may be at most one integer ID for each sender.
 136
 137     \sa mapping()
 138 */
 139 void QSignalMapper::setMapping(QObject *sender, int id)
 140 {
 141     Q_D(QSignalMapper);
 142     d->intHash.insert(sender, id);
 143     connect(sender, SIGNAL(destroyed()), this, SLOT(_q_senderDestroyed()));
 144 }
 145
 146 /*!
 147     Adds a mapping so that when map() is signalled from the \a sender,
 148     the signal mapped(\a text ) is emitted.
 149
 150     There may be at most one text for each sender.
 151 */
 152 void QSignalMapper::setMapping(QObject *sender, const QString &text)
 153 {
 154     Q_D(QSignalMapper);
 155     d->stringHash.insert(sender, text);
 156     connect(sender, SIGNAL(destroyed()), this, SLOT(_q_senderDestroyed()));
 157 }
 158
 159 /*!
 160     Adds a mapping so that when map() is signalled from the \a sender,
 161     the signal mapped(\a widget ) is emitted.
 162
 163     There may be at most one widget for each sender.
 164 */
 165 void QSignalMapper::setMapping(QObject *sender, QWidget *widget)
 166 {
 167     Q_D(QSignalMapper);
 168     d->widgetHash.insert(sender, widget);
 169     connect(sender, SIGNAL(destroyed()), this, SLOT(_q_senderDestroyed()));
 170 }
 171
 172 /*!
 173     Adds a mapping so that when map() is signalled from the \a sender,
 174     the signal mapped(\a object ) is emitted.
 175
 176     There may be at most one object for each sender.
 177 */
 178 void QSignalMapper::setMapping(QObject *sender, QObject *object)
 179 {
 180     Q_D(QSignalMapper);
 181     d->objectHash.insert(sender, object);
 182     connect(sender, SIGNAL(destroyed()), this, SLOT(_q_senderDestroyed()));
 183 }
 184
 185 /*!
 186     Returns the sender QObject that is associated with the \a id.
 187
 188     \sa setMapping()
 189 */
 190 QObject *QSignalMapper::mapping(int id) const
 191 {
 192     Q_D(const QSignalMapper);
 193     return d->intHash.key(id);
 194 }
 195
 196 /*!
 197     \overload mapping()
 198 */
 199 QObject *QSignalMapper::mapping(const QString &id) const
 200 {
 201     Q_D(const QSignalMapper);
 202     return d->stringHash.key(id);
 203 }
 204
 205 /*!
 206     \overload mapping()
 207
 208     Returns the sender QObject that is associated with the \a widget.
 209 */
 210 QObject *QSignalMapper::mapping(QWidget *widget) const
 211 {
 212     Q_D(const QSignalMapper);
 213     return d->widgetHash.key(widget);
 214 }
 215
 216 /*!
 217     \overload mapping()
 218
 219     Returns the sender QObject that is associated with the \a object.
 220 */
 221 QObject *QSignalMapper::mapping(QObject *object) const
 222 {
 223     Q_D(const QSignalMapper);
 224     return d->objectHash.key(object);
 225 }
 226
 227 /*!
 228     Removes all mappings for \a sender.
 229
 230     This is done automatically when mapped objects are destroyed.
 231 */
 232 void QSignalMapper::removeMappings(QObject *sender)
 233 {
 234     Q_D(QSignalMapper);
 235
 236     d->intHash.remove(sender);
 237     d->stringHash.remove(sender);
 238     d->widgetHash.remove(sender);
 239     d->objectHash.remove(sender);
 240 }
 241
 242 /*!
 243     This slot emits signals based on which object sends signals to it.
 244 */
 245 void QSignalMapper::map() { map(sender()); }
 246
 247 /*!
 248     This slot emits signals based on the \a sender object.
 249 */
 250 void QSignalMapper::map(QObject *sender)
 251 {
 252     Q_D(QSignalMapper);
 253     if (d->intHash.contains(sender))
 254         emit mapped(d->intHash.value(sender));
 255     if (d->stringHash.contains(sender))
 256         emit mapped(d->stringHash.value(sender));
 257     if (d->widgetHash.contains(sender))
 258         emit mapped(d->widgetHash.value(sender));
 259     if (d->objectHash.contains(sender))
 260         emit mapped(d->objectHash.value(sender));
 261 }
 262
 263
 264 /*!
 265     \fn void QSignalMapper::mapped(int i)
 266
 267     This signal is emitted when map() is signalled from an object that
 268     has an integer mapping set. The object's mapped integer is passed
 269     in \a i.
 270
 271     \sa setMapping()
 272 */
 273
 274 /*!
 275     \fn void QSignalMapper::mapped(const QString &text)
 276
 277     This signal is emitted when map() is signalled from an object that
 278     has a string mapping set. The object's mapped string is passed in
 279     \a text.
 280
 281     \sa setMapping()
 282 */
 283
 284 /*!
 285     \fn void QSignalMapper::mapped(QWidget *widget)
 286
 287     This signal is emitted when map() is signalled from an object that
 288     has a widget mapping set. The object's mapped widget is passed in
 289     \a widget.
 290
 291     \sa setMapping()
 292 */
 293
 294 /*!
 295     \fn void QSignalMapper::mapped(QObject *object)
 296
 297     This signal is emitted when map() is signalled from an object that
 298     has an object mapping set. The object provided by the map is passed in
 299     \a object.
 300
 301     \sa setMapping()
 302 */
 303
 304 QT_END_NAMESPACE
 305
 306 #include "moc_qsignalmapper.cpp"
 307
 308 #endif // QT_NO_SIGNALMAPPER
 309