Back to Qt.io
Contact Us Blog Download Qt
이 페이지에서

QSignalMapper Class

QSignalMapper 클래스는 식별 가능한 발신자로부터의 신호를 묶어줍니다. 더 보기...

헤더: #include <QSignalMapper>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
상속: QObject

공개 함수

QSignalMapper(QObject *parent = nullptr)
virtual ~QSignalMapper()
QObject *mapping(int id) const
QObject *mapping(QObject *object) const
QObject *mapping(const QString &id) const
void removeMappings(QObject *sender)
void setMapping(QObject *sender, QObject *object)
void setMapping(QObject *sender, const QString &text)
void setMapping(QObject *sender, int id)

공개 슬롯

void map()
void map(QObject *sender)

신호

void mappedInt(int i)
void mappedObject(QObject *object)
void mappedString(const QString &text)

상세 설명

이 클래스는 매개변수가 없는 신호 집합을 수집하여, 신호를 보낸 객체에 해당하는 정수, 문자열 또는 위젯 매개변수와 함께 이를 다시 발신합니다. 대부분의 경우 람다식을 사용하여 슬롯에 사용자 정의 매개변수를 전달할 수 있다는 점에 유의하십시오. 이는 성능 부담이 적을 뿐만 아니라 코드를 단순화해 줍니다.

이 클래스는 ` setMapping()`를 사용하여 특정 문자열, 정수, 객체 및 위젯을 특정 객체에 매핑하는 기능을 지원합니다. 그러면 객체의 신호를 ` map()` 슬롯에 연결할 수 있으며, 이 슬롯은 원래 신호를 보낸 객체와 연관된 값을 가진 신호(` mappedInt()`, ` mappedString()` 또는 ` mappedObject()` 등)를 방출합니다. 매핑은 나중에 ` removeMappings()`를 사용하여 제거할 수 있습니다.

예시: 버튼 그룹(예: 도구 팔레트)을 포함하는 사용자 정의 위젯을 만들려고 한다고 가정해 봅시다. 한 가지 방법은 각 버튼의 clicked() 신호를 해당 버튼 고유의 사용자 정의 슬롯에 연결하는 것이지만, 이 예제에서는 모든 버튼을 단일 슬롯에 연결하고, 클릭된 버튼에 따라 슬롯을 매개변수화하고자 합니다.

다음은 클릭된 버튼의 텍스트와 함께 발신되는 단일 신호인 ` clicked()`를 가진 간단한 사용자 정의 위젯의 정의입니다:

class ButtonWidget : public QWidget
{
    Q_OBJECT

public:
    ButtonWidget(const QStringList &texts, QWidget *parent = nullptr);

signals:
    void clicked(const QString &text);

private:
    QSignalMapper *signalMapper;
};

구현해야 할 유일한 함수는 생성자입니다:

ButtonWidget::ButtonWidget(const QStringList &texts, QWidget *parent)
    : QWidget(parent)
{
    signalMapper = new QSignalMapper(this);

    QGridLayout *gridLayout = new QGridLayout(this);
    for (int i = 0; i < texts.size(); ++i) {
        QPushButton *button = new QPushButton(texts[i]);
        connect(button, &QPushButton::clicked, signalMapper, qOverload<>(&QSignalMapper::map));
        signalMapper->setMapping(button, texts[i]);
        gridLayout->addWidget(button, i / 3, i % 3);
    }

    connect(signalMapper, &QSignalMapper::mappedString,
            this, &ButtonWidget::clicked);
}

텍스트 목록이 생성자에 전달됩니다. 시그널 매퍼가 생성되고, 목록에 있는 각 텍스트에 대해 ` QPushButton `가 생성됩니다. 각 버튼의 ` clicked() ` 시그널을 시그널 매퍼의 ` map()` 슬롯에 연결하고, 시그널 매퍼 내에서 각 버튼을 해당 버튼의 텍스트로 매핑합니다. 마지막으로, 시그널 매퍼의 mappedString() 신호를 사용자 정의 위젯의 clicked() 신호에 연결합니다. 사용자가 버튼을 클릭하면, 사용자 정의 위젯은 사용자가 클릭한 버튼의 텍스트를 인수로 갖는 clicked() 신호를 한 번 방출합니다.

이 클래스는 람다 함수를 슬롯으로 사용할 수 있게 되기 전에는 주로 유용했습니다. 위의 예제는 QSignalMapper를 사용하지 않고 람다 함수에 연결함으로써 더 간단하게 재작성할 수 있습니다.

ButtonWidget::ButtonWidget(const QStringList &texts, QWidget *parent)
    : QWidget(parent)
{
    QGridLayout *gridLayout = new QGridLayout(this);
    for (int i = 0; i < texts.size(); ++i) {
        QString text = texts[i];
        QPushButton *button = new QPushButton(text);
        connect(button, &QPushButton::clicked, [this, text] { clicked(text); });
        gridLayout->addWidget(button, i / 3, i % 3);
    }
}

QObject, QButtonGroup 및 QActionGroup도 참조하십시오 .

멤버 함수 문서

[explicit] QSignalMapper::QSignalMapper(QObject *parent = nullptr)

parent 를 부모로 하는 QSignalMapper를 생성합니다.

[virtual noexcept] QSignalMapper::~QSignalMapper()

QSignalMapper 를 삭제합니다.

[slot] void QSignalMapper::map()

이 슬롯은 어떤 객체가 신호를 보내느냐에 따라 신호를 발신합니다.

참고: 이 슬롯은 오버로드되어 있습니다. 이 슬롯에 연결하려면: 

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        signalMapper, qOverload<>(&QSignalMapper::map));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        signalMapper, [receiver = signalMapper]() { receiver->map(); });
더 많은 예제와 접근 방식에 대해서는 ‘오버로드된 슬롯에 연결하기’를 참조하십시오.

[slot] void QSignalMapper::map(QObject *sender)

이 슬롯은 ` sender ` 객체를 기반으로 신호를 발산합니다.

참고: 이 슬롯은 오버로드되어 있습니다. 이 슬롯에 연결하려면: 

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        signalMapper, qOverload(&QSignalMapper::map));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        signalMapper, [receiver = signalMapper](QObject *sender) { receiver->map(sender); });
더 많은 예제와 접근 방식에 대해서는 오버로드된 슬롯에 연결하기를 참조하십시오.

[signal] void QSignalMapper::mappedInt(int i)

이 신호는 정수 매핑이 설정된 객체에서 ` map()`가 호출될 때 발생합니다. 객체의 매핑된 정수 값은 ` i`에 전달됩니다.

setMapping()도 참조하십시오 .

[signal] void QSignalMapper::mappedObject(QObject *object)

이 신호는 객체 매핑이 설정된 객체에서 ` map()`가 호출될 때 발생합니다. 매핑에 의해 제공된 객체는 ` object`로 전달됩니다.

setMapping()도 참조하십시오 .

[signal] void QSignalMapper::mappedString(const QString &text)

이 신호는 문자열 매핑이 설정된 객체에서 ` map()`가 호출될 때 발생합니다. 객체의 매핑된 문자열은 ` text`에 전달됩니다.

setMapping()도 참조하십시오 .

QObject *QSignalMapper::mapping(int id) const

id 와 연관된 발신자 QObject 를 반환합니다.

setMapping()도 참조하십시오 .

QObject *QSignalMapper::mapping(QObject *object) const

object 와 연결된 발신자 QObject 를 반환합니다.

이 함수는 ` QSignalMapper::mapping()`를 오버로드합니다.

QObject *QSignalMapper::mapping(const QString &id) const

이 함수는 ` QSignalMapper::mapping()`를 오버로드합니다.

void QSignalMapper::removeMappings(QObject *sender)

sender 에 대한 모든 매핑을 제거합니다.

매핑된 객체가 소멸될 때 이 작업은 자동으로 수행됩니다.

참고: 이 작업은 어떤 신호도 분리하지 않습니다. sender 가 소멸되지 않은 경우, 필요한 경우 이 작업을 명시적으로 수행해야 합니다.

void QSignalMapper::setMapping(QObject *sender, QObject *object)

sender 에서 map() 신호가 전송되면, mappedObject(object ) 신호가 발신되도록 매핑을 추가합니다.

각 발신자에 대해 최대 하나의 객체만 존재할 수 있습니다.

mapping()도 참조하십시오 .

void QSignalMapper::setMapping(QObject *sender, const QString &text)

sender 에서 map() 신호가 전송될 때, mappedString(text ) 신호가 발신되도록 매핑을 추가합니다.

각 발신자당 텍스트는 최대 하나만 있을 수 있습니다.

void QSignalMapper::setMapping(QObject *sender, int id)

지정된 sender 에서 map() 신호가 전송되면, mappedInt(id) 신호가 발신되도록 매핑을 추가합니다.

각 발신자마다 정수 ID는 최대 하나만 가질 수 있습니다.

mapping()도 참조하십시오 .

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.