File indexing completed on 2024-05-12 15:57:03
0001 /**************************************************************************** 0002 ** 0003 ** SPDX-FileCopyrightText: 2016 The Qt Company Ltd. 0004 ** Contact: https://www.qt.io/licensing/ 0005 ** 0006 ** This file is part of the QtCore module of the Qt Toolkit. 0007 ** 0008 ** SPDX-License-Identifier: LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only OR LicenseRef-KFQF-Accepted-GPL OR LicenseRef-Qt-Commercial 0009 ** 0010 ****************************************************************************/ 0011 0012 #ifndef KisSignalMapper_H 0013 #define KisSignalMapper_H 0014 0015 #include <QtCore/qobject.h> 0016 #include "kritaglobal_export.h" 0017 0018 #include <QScopedPointer> 0019 0020 /*! 0021 \class KisSignalMapper 0022 \inmodule QtCore 0023 \obsolete The recommended solution is connecting the signal to a lambda. 0024 \brief The KisSignalMapper class bundles signals from identifiable senders. 0025 0026 \ingroup objectmodel 0027 0028 0029 This class collects a set of parameterless signals, and re-emits 0030 them with integer, string or widget parameters corresponding to 0031 the object that sent the signal. 0032 0033 The class supports the mapping of particular strings or integers 0034 with particular objects using setMapping(). The objects' signals 0035 can then be connected to the map() slot which will emit the 0036 mapped() signal with the string or integer associated with the 0037 original signaling object. Mappings can be removed later using 0038 removeMappings(). 0039 0040 Example: Suppose we want to create a custom widget that contains 0041 a group of buttons (like a tool palette). One approach is to 0042 connect each button's \c clicked() signal to its own custom slot; 0043 but in this example we want to connect all the buttons to a 0044 single slot and parameterize the slot by the button that was 0045 clicked. 0046 0047 Here's the definition of a simple custom widget that has a single 0048 signal, \c clicked(), which is emitted with the text of the button 0049 that was clicked: 0050 0051 \snippet KisSignalMapper/buttonwidget.h 0 0052 \snippet KisSignalMapper/buttonwidget.h 1 0053 0054 The only function that we need to implement is the constructor: 0055 0056 \snippet KisSignalMapper/buttonwidget.cpp 0 0057 \snippet KisSignalMapper/buttonwidget.cpp 1 0058 \snippet KisSignalMapper/buttonwidget.cpp 2 0059 0060 A list of texts is passed to the constructor. A signal mapper is 0061 constructed and for each text in the list a QPushButton is 0062 created. We connect each button's \c clicked() signal to the 0063 signal mapper's map() slot, and create a mapping in the signal 0064 mapper from each button to the button's text. Finally we connect 0065 the signal mapper's mapped() signal to the custom widget's \c 0066 clicked() signal. When the user clicks a button, the custom 0067 widget will emit a single \c clicked() signal whose argument is 0068 the text of the button the user clicked. 0069 0070 This class was mostly useful before lambda functions could be used as 0071 slots. The example above can be rewritten simpler without KisSignalMapper 0072 by connecting to a lambda function. 0073 0074 \snippet KisSignalMapper/buttonwidget.cpp 3 0075 0076 \sa QObject, QButtonGroup, QActionGroup 0077 */ 0078 class KRITAGLOBAL_EXPORT KisSignalMapper : public QObject 0079 { 0080 Q_OBJECT 0081 public: 0082 explicit KisSignalMapper(QObject *parent = nullptr); 0083 0084 /*! 0085 Destroys the KisSignalMapper. 0086 */ 0087 ~KisSignalMapper(); 0088 0089 /*! 0090 Adds a mapping so that when map() is signalled from the given \a 0091 sender, the signal mapped(\a id) is emitted. 0092 0093 There may be at most one integer ID for each sender. 0094 0095 \sa mapping() 0096 */ 0097 void setMapping(QObject *sender, int id); 0098 0099 /*! 0100 Adds a mapping so that when map() is signalled from the \a sender, 0101 the signal mapped(\a text ) is emitted. 0102 0103 There may be at most one text for each sender. 0104 */ 0105 void setMapping(QObject *sender, const QString &text); 0106 0107 /*! 0108 Adds a mapping so that when map() is signalled from the \a sender, 0109 the signal mapped(\a widget ) is emitted. 0110 0111 There may be at most one widget for each sender. 0112 */ 0113 void setMapping(QObject *sender, QWidget *widget); 0114 0115 /*! 0116 Adds a mapping so that when map() is signalled from the \a sender, 0117 the signal mapped(\a object ) is emitted. 0118 0119 There may be at most one object for each sender. 0120 */ 0121 void setMapping(QObject *sender, QObject *object); 0122 0123 /*! 0124 Removes all mappings for \a sender. 0125 0126 This is done automatically when mapped objects are destroyed. 0127 0128 \note This does not disconnect any signals. If \a sender is not destroyed 0129 then this will need to be done explicitly if required. 0130 */ 0131 void removeMappings(QObject *sender); 0132 0133 /*! 0134 \overload mapping() 0135 */ 0136 QObject *mapping(int id) const; 0137 0138 /*! 0139 \overload mapping() 0140 0141 Returns the sender QObject that is associated with the \a widget. 0142 */ 0143 QObject *mapping(const QString &text) const; 0144 0145 /*! 0146 \overload mapping() 0147 0148 Returns the sender QObject that is associated with the \a object. 0149 */ 0150 QObject *mapping(QWidget *widget) const; 0151 0152 0153 /*! 0154 Returns the sender QObject that is associated with the \a id. 0155 0156 \sa setMapping() 0157 */ 0158 QObject *mapping(QObject *object) const; 0159 0160 Q_SIGNALS: 0161 /*! 0162 \fn void KisSignalMapper::mapped(int i) 0163 0164 This signal is emitted when map() is signalled from an object that 0165 has an integer mapping set. The object's mapped integer is passed 0166 in \a i. 0167 0168 \sa setMapping() 0169 */ 0170 void mapped(int); 0171 0172 0173 /*! 0174 \fn void KisSignalMapper::mapped(const QString &text) 0175 0176 This signal is emitted when map() is signalled from an object that 0177 has a string mapping set. The object's mapped string is passed in 0178 \a text. 0179 0180 \sa setMapping() 0181 */ 0182 void mapped(const QString &); 0183 0184 /*! 0185 \fn void KisSignalMapper::mapped(QWidget *widget) 0186 0187 This signal is emitted when map() is signalled from an object that 0188 has a widget mapping set. The object's mapped widget is passed in 0189 \a widget. 0190 0191 \sa setMapping() 0192 */ 0193 void mapped(QWidget *); 0194 0195 /*! 0196 \fn void KisSignalMapper::mapped(QObject *object) 0197 0198 This signal is emitted when map() is signalled from an object that 0199 has an object mapping set. The object provided by the map is passed in 0200 \a object. 0201 0202 \sa setMapping() 0203 */ 0204 void mapped(QObject *); 0205 0206 public Q_SLOTS: 0207 /*! 0208 This slot emits signals based on which object sends signals to it. 0209 */ 0210 void map(); 0211 0212 /*! 0213 This slot emits signals based on the \a sender object. 0214 */ 0215 void map(QObject *sender); 0216 0217 private: 0218 0219 class Private; 0220 QScopedPointer<Private> d; 0221 0222 Q_DISABLE_COPY(KisSignalMapper) 0223 Q_PRIVATE_SLOT(d, void _q_senderDestroyed()) 0224 }; 0225 0226 0227 #endif // KisSignalMapper_H