Deprecate QSignalMapper

Does not make much sense now that we can connect to lambda functions

[ChangeLog][QtCore][QSignalMapper] QSignalMapper is now marked
as deprecated.

Change-Id: I89135f23fdf16b42142a125eb7c9a86084c90bfc
Reviewed-by: Sze Howe Koh <szehowe.koh@gmail.com>

examples/widgets/mainwindows/mainwindow/mainwindow.cpp

@@ -63,7 +63,6 @@
 #include <QFileDialog>
 #include <QDialogButtonBox>
 #include <QMessageBox>
-#include <QSignalMapper>
 #include <QApplication>
 #include <QPainter>
 #include <QMouseEvent>

src/corelib/doc/snippets/qsignalmapper/buttonwidget.cpp

@@ -49,6 +49,7 @@
 ****************************************************************************/
 
 #include <QtGui>
+#include <QtWidgets>
 
 #include "buttonwidget.h"
 
@@ -74,3 +75,18 @@ ButtonWidget::ButtonWidget(const QStringList &texts, QWidget *parent)
     setLayout(gridLayout);
 }
 //! [2]
+
+//! [3]
+ButtonWidget::ButtonWidget(const QStringList &texts, QWidget *parent)
+    : QWidget(parent)
+{
+    QGridLayout *gridLayout = new QGridLayout;
+    for (int i = 0; i < texts.size(); ++i) {
+        QString text = texts[i];
+        QPushButton *button = new QPushButton(text);
+        connect(button, &QPushButton::clicked, [=] { clicked(text); });
+        gridLayout->addWidget(button, i / 3, i % 3);
+    }
+    setLayout(gridLayout);
+}
+//! [3]

src/corelib/doc/snippets/signalmapper/filereader.cpp

@@ -1,117 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the config.tests of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:BSD$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** BSD License Usage
-** Alternatively, you may use this file under the terms of the BSD license
-** as follows:
-**
-** "Redistribution and use in source and binary forms, with or without
-** modification, are permitted provided that the following conditions are
-** met:
-**   * Redistributions of source code must retain the above copyright
-**     notice, this list of conditions and the following disclaimer.
-**   * Redistributions in binary form must reproduce the above copyright
-**     notice, this list of conditions and the following disclaimer in
-**     the documentation and/or other materials provided with the
-**     distribution.
-**   * Neither the name of The Qt Company Ltd nor the names of its
-**     contributors may be used to endorse or promote products derived
-**     from this software without specific prior written permission.
-**
-**
-** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-#include <QtGui>
-#include "filereader.h"
-
-
-FileReader::FileReader(QWidget *parent)
-    : QWidget(parent)
-{
-    textEdit = new QTextEdit;
-
-    taxFileButton = new QPushButton("Tax File");
-    accountFileButton = new QPushButton("Accounts File");
-    reportFileButton = new QPushButton("Report File");
-
-//! [0]
-    signalMapper = new QSignalMapper(this);
-    signalMapper->setMapping(taxFileButton, QString("taxfile.txt"));
-    signalMapper->setMapping(accountFileButton, QString("accountsfile.txt"));
-    signalMapper->setMapping(reportFileButton, QString("reportfile.txt"));
-
-    connect(taxFileButton, &QPushButton::clicked,
-        signalMapper, &QSignalMapper::map);
-    connect(accountFileButton, &QPushButton::clicked,
-        signalMapper, &QSignalMapper::map);
-    connect(reportFileButton, &QPushButton::clicked,
-        signalMapper, &QSignalMapper::map);
-//! [0]
-
-//! [1]
-    connect(signalMapper, SIGNAL(mapped(QString)),
-        this, SLOT(readFile(QString)));
-//! [1]
-
-/*
-//! [2]
-    //slower due to signature normalization at runtime
-
-    connect(signalMapper, SIGNAL(mapped(QString)),
-        this, SLOT(readFile(QString)));
-//! [2]
-*/
-    QHBoxLayout *buttonLayout = new QHBoxLayout;
-    buttonLayout->addWidget(taxFileButton);
-    buttonLayout->addWidget(accountFileButton);
-    buttonLayout->addWidget(reportFileButton);
-
-    QVBoxLayout *mainLayout = new QVBoxLayout;
-    mainLayout->addWidget(textEdit);
-    mainLayout->addLayout(buttonLayout);
-
-    setLayout(mainLayout);
-}
-
-void FileReader::readFile(const QString &filename)
-{
-    QFile file(filename);
-
-    if (!file.open(QIODevice::ReadOnly)) {
-        QMessageBox::information(this, tr("Unable to open file"),
-            file.errorString());
-        return;
-    }
-
-
-    QTextStream in(&file);
-    textEdit->setPlainText(in.readAll());
-}
-

src/corelib/doc/src/objectmodel/signalsandslots.qdoc

@@ -395,24 +395,12 @@
     signal, Qt provides the QObject::sender() function, which returns
     a pointer to the object that sent the signal.
 
-    The QSignalMapper class is provided for situations where many
-    signals are connected to the same slot and the slot needs to
-    handle each signal differently.
+    Lambda expressions are a convenient way to pass custom arguments to a slot:
 
-    Suppose you have three push buttons that determine which file you
-    will open: "Tax File", "Accounts File", or "Report File".
-
-    In order to open the correct file, you use QSignalMapper::setMapping() to
-    map all the QPushButton::clicked() signals to a QSignalMapper object. Then you connect
-    the file's QPushButton::clicked() signal to the QSignalMapper::map() slot.
-
-    \snippet signalmapper/filereader.cpp 0
-
-    Then, you connect the \l{QSignalMapper::}{mapped()} signal to
-    \c{readFile()} where a different file will be opened, depending on
-    which push button is pressed.
-
-    \snippet signalmapper/filereader.cpp 1
+    \code
+    connect(action, &QAction::triggered, engine,
+            [=]() { engine->processAction(action->text()); });
+    \endcode
 
     \sa {Meta-Object System}, {Qt's Property System}
 

src/corelib/kernel/qobject.cpp

@@ -2339,7 +2339,7 @@ static void err_info_about_objects(const char * func,
     a thread different from this object's thread. Do not use this
     function in this type of scenario.
 
-    \sa senderSignalIndex(), QSignalMapper
+    \sa senderSignalIndex()
 */
 
 QObject *QObject::sender() const

src/corelib/kernel/qsignalmapper.cpp

@@ -58,10 +58,10 @@ public:
 
 };
 
-
 /*!
     \class QSignalMapper
     \inmodule QtCore
+    \obsolete
     \brief The QSignalMapper class bundles signals from identifiable senders.
 
     \ingroup objectmodel
@@ -108,6 +108,12 @@ public:
     widget will emit a single \c clicked() signal whose argument is
     the text of the button the user clicked.
 
+    This class was mostly useful before lambda functions could be used as
+    slots. The example above can be rewritten simpler without QSignalMapper
+    by connecting to a lambda function.
+
+    \snippet qsignalmapper/buttonwidget.cpp 3
+
     \sa QObject, QButtonGroup, QActionGroup
 */
 

src/corelib/kernel/qsignalmapper.h

@@ -42,6 +42,8 @@
 
 #include <QtCore/qobject.h>
 
+#if QT_DEPRECATED_SINCE(5, 10)
+
 QT_BEGIN_NAMESPACE
 
 class QSignalMapperPrivate;
@@ -51,7 +53,7 @@ class Q_CORE_EXPORT QSignalMapper : public QObject
     Q_OBJECT
     Q_DECLARE_PRIVATE(QSignalMapper)
 public:
-    explicit QSignalMapper(QObject *parent = Q_NULLPTR);
+    QT_DEPRECATED explicit QSignalMapper(QObject *parent = nullptr);
     ~QSignalMapper();
 
     void setMapping(QObject *sender, int id);
@@ -82,4 +84,6 @@ private:
 
 QT_END_NAMESPACE
 
+#endif
+
 #endif // QSIGNALMAPPER_H