com.trolltech.qt.core
Class QSignalMapper

java.lang.Object
  extended by com.trolltech.qt.internal.QSignalEmitterInternal
      extended by com.trolltech.qt.QSignalEmitter
          extended by com.trolltech.qt.QtJambiObject
              extended by com.trolltech.qt.core.QObject
                  extended by com.trolltech.qt.core.QSignalMapper
All Implemented Interfaces:
QtJambiInterface

public class QSignalMapper
extends QObject

The QSignalMapper class bundles signals from identifiable senders. This class collects a set of parameterless signals, and re-emits them with integer, string or widget parameters corresponding to the object that sent the signal.

The class supports the mapping of particular strings or integers with particular objects using setMapping(). The objects' signals can then be connected to the map() slot which will emit the mapped() signal with the string or integer associated with the original signalling object. Mappings can be removed later using removeMappings().

Example: Suppose we want to create a custom widget that contains a group of buttons (like a tool palette). One approach is to connect each button's clicked() signal to its own custom slot; but in this example we want to connect all the buttons to a single slot and parameterize the slot by the button that was clicked.

Here's the definition of a simple custom widget that has a single signal, clicked(), which is emitted with the text of the button that was clicked:

class ButtonWidget extends QWidget
{
    ...

    public ButtonWidget(List<String> texts) {...};

    public Signal1<String> clicked = new Qignal1<String>();

    private QSignalMapper signalMapper;

}
The only function that we need to implement is the constructor:
    public buttonwidget(List<String> texts)
    {
        signalMapper = new QSignalMapper(this);

        QGridLayout gridLayout = new QGridLayout();
        for (int i = 0; i < texts.size(); ++i) {
            QPushButton button = new QPushButton(texts.get(i));
            button.clicked.connect(signalMapper, "map()");

            signalMapper.setMapping(button, texts.get(i));
            gridLayout.addWidget(button, i / 3, i % 3);
        }

        signalMapper.mappedString.connect(

                this, "clicked(String)");

        setLayout(gridLayout);
    }
    
A list of texts is passed to the constructor. A signal mapper is constructed and for each text in the list a QPushButton is created. We connect each button's clicked() signal to the signal mapper's map() slot, and create a mapping in the signal mapper from each button to the button's text. Finally we connect the signal mapper's mapped() signal to the custom widget's clicked() signal. When the user clicks a button, the custom widget will emit a single clicked() signal whose argument is the text of the button the user clicked.

See also:
QObject, QButtonGroup, and QActionGroup.


Nested Class Summary
 
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
QSignalEmitter.AbstractSignal, QSignalEmitter.PrivateSignal0, QSignalEmitter.PrivateSignal1, QSignalEmitter.PrivateSignal2, QSignalEmitter.PrivateSignal3, QSignalEmitter.PrivateSignal4, QSignalEmitter.PrivateSignal5, QSignalEmitter.PrivateSignal6, QSignalEmitter.PrivateSignal7, QSignalEmitter.PrivateSignal8, QSignalEmitter.PrivateSignal9, QSignalEmitter.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9
 
Nested classes/interfaces inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
com.trolltech.qt.internal.QSignalEmitterInternal.AbstractSignalInternal
 
Field Summary
 QSignalEmitter.Signal1 mappedInteger
          This signal takes 1 generic argument(s).
 QSignalEmitter.Signal1 mappedQObject
          This signal takes 1 generic argument(s).
 QSignalEmitter.Signal1 mappedString
          This signal takes 1 generic argument(s).
 
Fields inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
currentSender
 
Constructor Summary
QSignalMapper()
          Constructs a QSignalMapper with parent parent.
QSignalMapper(QObject parent)
          Constructs a QSignalMapper with parent parent.
 
Method Summary
 void map()
          This slot emits signals based on which object sends signals to it.
 void map(QObject sender)
          This slot emits signals based on the sender object.
 QObject mapping(int id)
          Returns the sender QObject that is associated with the id.
 QObject mapping(QObject object)
          This function overloads mapping().
 QObject mapping(java.lang.String text)
          Returns the signal sender associated with the string text.
 void removeMappings(QObject sender)
          Removes all mappings for sender.
 void setMapping(QObject sender, int id)
          Adds a mapping so that when map() is signalled from the given sender, the signal mapped(id) is emitted.
 void setMapping(QObject sender, QObject object)
          Adds a mapping so that when map() is signalled from the sender, the signal mapped(object ) is emitted.
 void setMapping(QObject sender, java.lang.String text)
          Adds a mapping so that when map() is signalled from the sender, the signal mapped(text ) is emitted.
 
Methods inherited from class com.trolltech.qt.core.QObject
childEvent, children, connectSlotsByName, customEvent, disposeLater, dumpObjectInfo, dumpObjectTree, dynamicPropertyNames, event, eventFilter, findChild, findChild, findChild, findChildren, findChildren, findChildren, findChildren, indexOfProperty, installEventFilter, isWidgetType, killTimer, moveToThread, objectName, parent, properties, property, removeEventFilter, setObjectName, setParent, setProperty, startTimer, timerEvent, toString, userProperty
 
Methods inherited from class com.trolltech.qt.QtJambiObject
dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr
 
Methods inherited from class com.trolltech.qt.QSignalEmitter
blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread
 
Methods inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
__qt_signalInitialization
 
Methods inherited from class java.lang.Object
clone, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 

Field Detail

mappedQObject

public final QSignalEmitter.Signal1 mappedQObject

This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <com.trolltech.qt.core.QObject(named: i)>:

This signal is emitted when map() is signalled from an object that has an integer mapping set. The object's mapped integer is passed in i.

See also:
setMapping().


mappedString

public final QSignalEmitter.Signal1 mappedString

This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <java.lang.String(named: i)>:

This signal is emitted when map() is signalled from an object that has an integer mapping set. The object's mapped integer is passed in i.

See also:
setMapping().


mappedInteger

public final QSignalEmitter.Signal1 mappedInteger

This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <java.lang.Integer(named: i)>:

This signal is emitted when map() is signalled from an object that has an integer mapping set. The object's mapped integer is passed in i.

See also:
setMapping().

Constructor Detail

QSignalMapper

public QSignalMapper()
Constructs a QSignalMapper with parent parent.


QSignalMapper

public QSignalMapper(QObject parent)
Constructs a QSignalMapper with parent parent.

Method Detail

map

public final void map()
This slot emits signals based on which object sends signals to it.


map

public final void map(QObject sender)
This slot emits signals based on the sender object.


mapping

public final QObject mapping(QObject object)
This function overloads mapping().

Returns the sender QObject that is associated with the object.


mapping

public final QObject mapping(java.lang.String text)
Returns the signal sender associated with the string text.


mapping

public final QObject mapping(int id)
Returns the sender QObject that is associated with the id.

See also:
setMapping().


removeMappings

public final void removeMappings(QObject sender)
Removes all mappings for sender.

This is done automatically when mapped objects are destroyed.


setMapping

public final void setMapping(QObject sender,
                             QObject object)
Adds a mapping so that when map() is signalled from the sender, the signal mapped(object ) is emitted.

There may be at most one object for each sender.


setMapping

public final void setMapping(QObject sender,
                             java.lang.String text)
Adds a mapping so that when map() is signalled from the sender, the signal mapped(text ) is emitted.

There may be at most one text for each sender.


setMapping

public final void setMapping(QObject sender,
                             int id)
Adds a mapping so that when map() is signalled from the given sender, the signal mapped(id) is emitted.

There may be at most one integer ID for each sender.

See also:
mapping().