En esta página

Señales y ranuras

Introducción

En la programación de interfaces gráficas de usuario (GUI), cuando modificamos un widget, a menudo queremos que se notifique a otro widget. En términos más generales, queremos que los objetos de cualquier tipo puedan comunicarse entre sí. Por ejemplo, si un usuario hace clic en un botón « Close », probablemente queramos que se llame a la función « close()» de la ventana.

Otros kits de herramientas logran este tipo de comunicación mediante las funciones de devolución de llamada. Una función de devolución de llamada es un puntero a una función, por lo que, si quieres que una función de procesamiento te notifique algún evento, pasas un puntero a otra función (la función de devolución de llamada) a la función de procesamiento. A continuación, la función de procesamiento llama a la llamada de retorno cuando sea oportuno. Aunque existen marcos de trabajo exitosos que utilizan este método, las llamadas de retorno pueden resultar poco intuitivas y pueden presentar problemas a la hora de garantizar la corrección de tipos de los argumentos de la llamada de retorno.

Señales y ranuras

En Qt, disponemos de una alternativa a la técnica de las funciones de retorno: utilizamos señales y ranuras. Una señal se emite cuando se produce un evento concreto. Los widgets de Qt tienen muchas señales predefinidas, pero siempre podemos crear subclases de los widgets para añadirles nuestras propias señales. Un slot es una función que se invoca en respuesta a una señal concreta. Los Qt Widgets cuentan con numerosos slots predefinidos, pero es habitual crear subclases de los widgets y añadir tus propios slots para poder gestionar las señales que te interesen.

Relaciones entre objetos

El mecanismo de señales y ranuras es seguro en cuanto a tipos: la firma de una señal debe coincidir con la firma de la ranura receptora. (De hecho, una ranura puede tener una firma más corta que la señal que recibe, ya que puede ignorar argumentos adicionales). Dado que las firmas son compatibles, el compilador puede ayudarnos a detectar discrepancias de tipos al utilizar la sintaxis basada en punteros a funciones. La sintaxis de SIGNAL y SLOT basada en cadenas detectará las discrepancias de tipos en tiempo de ejecución. Las señales y los slots tienen un acoplamiento débil: una clase que emite una señal ni sabe ni le importa qué slots reciben dicha señal. El mecanismo de señales y ranuras de Qt garantiza que, si conectas una señal a una ranura, esta se invocará con los parámetros de la señal en el momento adecuado. Las señales y las ranuras pueden aceptar cualquier número de argumentos de cualquier tipo. Son totalmente seguras en cuanto a tipos.

Todas las clases que heredan de ` QObject ` o de una de sus subclases (por ejemplo, ` QWidget`) pueden contener señales y ranuras. Los objetos emiten señales cuando cambian de estado de una forma que puede resultar interesante para otros objetos. Esto es todo lo que hace el objeto para comunicarse. No sabe ni le importa si hay algo que esté recibiendo las señales que emite. Esto constituye una verdadera encapsulación de la información y garantiza que el objeto pueda utilizarse como un componente de software.

Las ranuras pueden utilizarse para recibir señales, pero también son funciones miembro normales. Al igual que un objeto no sabe si algo recibe sus señales, una ranura no sabe si tiene alguna señal conectada a ella. Esto garantiza que se puedan crear componentes verdaderamente independientes con Qt.

Puedes conectar tantas señales como quieras a una sola ranura, y una señal puede conectarse a tantas ranuras como necesites. Incluso es posible conectar una señal directamente a otra señal. (Esto hará que la segunda señal se emita inmediatamente cada vez que se emita la primera.)

En conjunto, las señales y las ranuras conforman un potente mecanismo de programación de componentes.

Señales

Las señales son emitidas por un objeto cuando su estado interno ha cambiado de alguna manera que pueda resultar de interés para el cliente o el propietario del objeto. Las señales son funciones de acceso público y pueden emitirse desde cualquier lugar, pero recomendamos emitirlas únicamente desde la clase que define la señal y sus subclases.

Cuando se emite una señal, las ranuras conectadas a ella suelen ejecutarse inmediatamente, igual que una llamada a una función normal. Cuando esto ocurre, el mecanismo de señales y ranuras es totalmente independiente de cualquier bucle de eventos de la interfaz gráfica de usuario. La ejecución del código que sigue a la instrucción « emit » tendrá lugar una vez que todas las ranuras hayan devuelto un resultado. La situación es ligeramente diferente cuando se utiliza ` queued connections`; en tal caso, el código que sigue a la palabra clave ` emit ` continuará inmediatamente, y las ranuras se ejecutarán más tarde.

Si hay varias ranuras conectadas a una misma señal, estas se ejecutarán una tras otra, en el orden en que se hayan conectado, cuando se emita la señal.

Las señales las genera automáticamente el moc y no deben implementarse en el archivo .cpp.

Una nota sobre los argumentos: nuestra experiencia demuestra que las señales y los slots son más reutilizables si no utilizan tipos especiales. Si QScrollBar::valueChanged() utilizara un tipo especial, como el hipotético QScrollBar::Range, solo podría conectarse a slots diseñados específicamente para QScrollBar. Sería imposible conectar entre sí diferentes widgets de entrada.

Slots

Una ranura se invoca cuando se emite una señal conectada a ella. Las ranuras son funciones normales de C++ y pueden invocarse de forma habitual; su única característica especial es que se les pueden conectar señales.

Dado que las ranuras son funciones miembro normales, siguen las reglas habituales de C++ cuando se invocan directamente. Sin embargo, como ranuras, pueden ser invocadas por cualquier componente, independientemente de su nivel de acceso, a través de una conexión señal-ranura. Esto significa que una señal emitida desde una instancia de una clase cualquiera puede provocar que se invoque una ranura privada en una instancia de una clase no relacionada.

También se pueden definir slots como virtuales, lo cual nos ha resultado bastante útil en la práctica.

En comparación con las llamadas de retorno, las señales y los slots son ligeramente más lentos debido a la mayor flexibilidad que ofrecen, aunque la diferencia en aplicaciones reales es insignificante. En general, emitir una señal conectada a varios slots es aproximadamente diez veces más lento que llamar directamente a los receptores mediante llamadas a funciones no virtuales. Esta es la sobrecarga necesaria para localizar el objeto de conexión, iterar de forma segura por todas las conexiones (es decir, comprobar que los receptores posteriores no hayan sido destruidos durante la emisión) y marshalear cualquier parámetro de forma genérica. Aunque diez llamadas a funciones no virtuales puedan parecer muchas, suponen una sobrecarga mucho menor que cualquier operación de tipo « new » o « delete », por ejemplo. En cuanto se realiza una operación con cadenas, vectores o listas que, entre bastidores, requiere « new » o « delete », la sobrecarga de las señales y ranuras solo representa una proporción muy pequeña del coste total de las llamadas a funciones. Lo mismo ocurre cada vez que se realiza una llamada al sistema en un slot o se invocan indirectamente más de diez funciones. La simplicidad y flexibilidad del mecanismo de señales y ranuras compensan con creces esa sobrecarga, que los usuarios ni siquiera notarán.

Ten en cuenta que otras bibliotecas que definen variables denominadas « signals » o « slots » pueden provocar advertencias y errores del compilador al compilarse junto con una aplicación basada en Qt. Para resolver este problema, utiliza ` #undef ` para eliminar el símbolo del preprocesador problemático.

Un pequeño ejemplo

Una declaración mínima de una clase en C++ podría ser la siguiente:

class Counter
{
public:
    Counter() { m_value = 0; }

    int value() const { return m_value; }
    void setValue(int value);

private:
    int m_value;
};

Una pequeña clase basada en ` QObject` podría ser la siguiente:

#include <QObject>

class Counter : public QObject
{
    Q_OBJECT

// Note. The Q_OBJECT macro starts a private section.
// To declare public members, use the 'public:' access modifier.
public:
    Counter() { m_value = 0; }

    int value() const { return m_value; }

public slots:
    void setValue(int value);

signals:
    void valueChanged(int newValue);

private:
    int m_value;
};

La versión basada en ` QObject` tiene el mismo estado interno y proporciona métodos públicos para acceder a dicho estado, pero, además, admite la programación por componentes mediante señales y ranuras. Esta clase puede comunicar al mundo exterior que su estado ha cambiado emitiendo una señal, valueChanged(), y cuenta con una ranura a la que otros objetos pueden enviar señales.

Todas las clases que contengan señales o ranuras deben mencionar « Q_OBJECT » al principio de su declaración. También deben derivar (directa o indirectamente) de « QObject ».

Las ranuras son implementadas por el programador de la aplicación. A continuación se muestra una posible implementación de la ranura « Counter::setValue() »:

void Counter::setValue(int value)
{
    if (value != m_value) {
        m_value = value;
        emit valueChanged(value);
    }
}

La línea ` emit ` emite la señal ` valueChanged() ` desde el objeto, con el nuevo valor como argumento.

En el siguiente fragmento de código, creamos dos objetos ` Counter ` y conectamos la señal ` valueChanged() ` del primer objeto a la ranura ` setValue() ` del segundo objeto mediante ` QObject::connect()`:

    Counter a, b;
    QObject::connect(&a, &Counter::valueChanged,
                     &b, &Counter::setValue);

    a.setValue(12);     // a.value() == 12, b.value() == 12
    b.setValue(48);     // a.value() == 12, b.value() == 48

Al llamar a ` a.setValue(12) `, ` a ` emite una señal ` valueChanged(12) `, que ` b ` recibirá en su ranura ` setValue() `, es decir, se llama a ` b.setValue(12) `. A continuación, ` b ` emite la misma señal ` valueChanged() `, pero como no se ha conectado ninguna ranura a la señal ` valueChanged() ` de ` b`, la señal se ignora.

Ten en cuenta que la función setValue() establece el valor y emite la señal solo si value != m_value. Esto evita bucles infinitos en el caso de conexiones cíclicas (por ejemplo, si b.valueChanged() estuviera conectado a a.setValue()).

Por defecto, cada vez que se establece una conexión se emite una señal; en el caso de conexiones duplicadas, se emiten dos señales. Es posible romper todas estas conexiones con una sola llamada a disconnect(). Si pasas ` Qt::UniqueConnection ` como ` type`, la conexión solo se establecerá si no es un duplicado. Si ya existe un duplicado (la misma señal exactamente en la misma ranura de los mismos objetos), la conexión fallará y `connect` devolverá ` false`.

Este ejemplo ilustra que los objetos pueden trabajar juntos sin necesidad de conocer ninguna información unos de otros. Para ello, basta con que los objetos estén conectados entre sí, lo cual se puede lograr mediante unas sencillas llamadas a la función ` QObject::connect()` o mediante la función de conexiones automáticas de uic.

Un ejemplo real

A continuación se muestra un ejemplo del encabezado de una clase de widget sencilla sin funciones miembro. El objetivo es mostrar cómo se pueden utilizar las señales y las ranuras en tus propias aplicaciones.

#ifndef LCDNUMBER_H
#define LCDNUMBER_H

#include <QFrame>

class LcdNumber : public QFrame
{
    Q_OBJECT

LcdNumber Heredan de ` QObject`, que contiene la mayor parte de los conocimientos sobre señales y ranuras, a través de ` QFrame ` y ` QWidget`. Es algo similar al widget integrado ` QLCDNumber `.

El preprocesador expande la macro Q_OBJECT para declarar varias funciones miembro que son implementadas por moc; si recibes errores del compilador del tipo «referencia indefinida a vtable para LcdNumber », probablemente te hayas olvidado de ejecutar moc o de incluir la salida de moc en el comando de enlace.

public:
    LcdNumber(QWidget *parent = nullptr);

signals:
    void overflow();

Tras el constructor de la clase y los miembros « public », declaramos la clase « signals ». La clase « LcdNumber » emite una señal, « overflow() », cuando se le pide que muestre un valor imposible.

Si no te preocupa el desbordamiento, o sabes que no puede producirse, puedes ignorar la señal « overflow() », es decir, no conectarla a ninguna ranura.

Si, por el contrario, quieres llamar a dos funciones de error diferentes cuando el número se desborde, basta con conectar la señal a dos slots distintos. Qt llamará a ambas (en el orden en que se hayan conectado).

public slots:
    void display(int num);
    void display(double num);
    void display(const QString &str);
    void setHexMode();
    void setDecMode();
    void setOctMode();
    void setBinMode();
    void setSmallDecimalPoint(bool point);
};

#endif

Un slot es una función receptora que se utiliza para obtener información sobre los cambios de estado en otros widgets. « LcdNumber » lo utiliza, tal y como indica el código anterior, para establecer el número que se muestra. Dado que « display() » forma parte de la interfaz de la clase con el resto del programa, el slot es público.

Varios de los programas de ejemplo conectan la señal « valueChanged()» de un « QScrollBar » a la slot « display() », de modo que el número de la pantalla LCD muestra continuamente el valor de la barra de desplazamiento.

Ten en cuenta que `display()` está sobrecargada. Las señales y ranuras de Qt te ofrecen conexiones fuertemente tipadas. Son más seguras en tiempo de compilación que las llamadas de retorno tradicionales. Con las llamadas de retorno, necesitarías nombres de función diferentes y un seguimiento manual de los tipos. Sin embargo, con las funciones sobrecargadas, debes especificar qué versión utilizar. La siguiente sección te muestra cómo hacerlo.

Conexión a señales y ranuras sobrecargadas

Cuando las señales o las ranuras están sobrecargadas (tienen varias versiones con parámetros diferentes), es necesario especificar explícitamente a qué versión se desea conectar utilizando la sintaxis de puntero a función. Se puede utilizar ` qOverload()` o ` static_cast ` para eliminar la ambigüedad:

// Connect to the QString overload of QCompleter::activated(const QString &)
connect(completer, qOverload<const QString &>(&QCompleter::activated),
        this, &MyClass::onActivatedText);

// Or select QLCDNumber::display(int) when connecting from QSlider::valueChanged(int)
connect(slider, &QSlider::valueChanged,
        lcd, qOverload<int>(&QLCDNumber::display));

// Using static_cast (more verbose):
connect(completer, static_cast<void(QCompleter::*)(const QString &)>(&QCompleter::activated),
        this, &MyClass::onActivatedText);

// Or using a lambda to call the correct overload:
connect(slider, &QSlider::valueChanged,
        this, [lcd](int value) { lcd->display(value); });

Gestión automática de conexiones

Qt gestiona automáticamente el ciclo de vida de las conexiones entre los tipos derivados de ` QObject`. Cuando se destruye el objeto emisor o el receptor, la conexión se elimina automáticamente, lo que evita que se realicen llamadas a objetos eliminados. Esto se aplica tanto a la sintaxis de puntero a función como a la sintaxis de SIGNAL/SLOT basada en cadenas.

Para las conexiones lambda, se debe proporcionar un objeto de contexto (normalmente ` this`) para garantizar que la lambda se desconecte cuando se destruya el contexto:

connect(button, &QPushButton::clicked, this, [this]{ handleClick(); });

Aunque Qt protege contra el envío de señales a objetos totalmente destruidos, las señales pueden seguir enviándose durante la destrucción del objeto, una vez que el destructor de la clase derivada ha finalizado, pero antes de llegar a ~QObject. Esta limitación se aplica específicamente a las conexiones realizadas con la sintaxis de puntero a función. Puede ocurrir cuando el destructor de una clase base emite señales a las que estaba conectada la clase derivada ya destruida. Considera la posibilidad de desconectar explícitamente dichas señales en los destructores si esto pudiera suponer un problema para tu clase.

Señales y ranuras con argumentos por defecto

Las firmas de las señales y ranuras pueden contener argumentos, y estos pueden tener valores por defecto. Consideremos QObject::destroyed():

void destroyed(QObject* = nullptr);

Cuando se elimina un ` QObject `, emite esta señal ` QObject::destroyed()`. Queremos capturar esta señal en cualquier lugar donde podamos tener una referencia suelta al ` QObject` eliminado, para poder limpiarla. Una firma de slot adecuada podría ser:

void objectDestroyed(QObject* obj = nullptr);

Para conectar la señal al slot, utilizamos QObject::connect(). Hay varias formas de conectar señales y slots. La primera es utilizar punteros a funciones:

connect(sender, &QObject::destroyed, this, &MyObject::objectDestroyed);

El uso de ` QObject::connect()` con punteros a funciones presenta varias ventajas. En primer lugar, permite al compilador comprobar que los argumentos de la señal son compatibles con los del slot. Además, el compilador puede convertir implícitamente los argumentos si es necesario.

También puedes conectarlas a funtores o lambdas de C++11:

connect(sender, &QObject::destroyed, this, [=](){ this->m_objects.remove(sender); });

En ambos casos, proporcionamos ` this ` como contexto en la llamada a `connect()`. El objeto de contexto proporciona información sobre en qué hilo debe ejecutarse el receptor. Esto es importante, ya que proporcionar el contexto garantiza que el receptor se ejecute en el hilo de contexto.

La lambda se desconectará cuando se destruya el emisor o el contexto. Debes asegurarte de que cualquier objeto utilizado dentro del functor siga activo cuando se emita la señal.

La otra forma de conectar una señal a una ranura es utilizar ` QObject::connect()` y las macros ` SIGNAL ` y ` SLOT `. La regla sobre si se deben incluir o no argumentos en las macros ` SIGNAL() ` y ` SLOT() `, si los argumentos tienen valores por defecto, es que la firma pasada a la macro ` SIGNAL() ` no debe tener menos argumentos que la firma pasada a la macro ` SLOT() `.

Todas estas opciones funcionarían:

connect(sender, SIGNAL(destroyed(QObject*)), this, SLOT(objectDestroyed(Qbject*)));
connect(sender, SIGNAL(destroyed(QObject*)), this, SLOT(objectDestroyed()));
connect(sender, SIGNAL(destroyed()), this, SLOT(objectDestroyed()));

Pero esto no funcionará:

connect(sender, SIGNAL(destroyed()), this, SLOT(objectDestroyed(QObject*)));

...porque el slot esperará un « QObject » que la señal no enviará. Esta conexión generará un error en tiempo de ejecución.

Ten en cuenta que el compilador no comprueba los argumentos de la señal y la ranura cuando se utiliza esta sobrecarga de QObject::connect().

Uso avanzado de señales y ranuras

Para aquellos casos en los que se necesite información sobre el emisor de la señal, Qt proporciona la función ` QObject::sender()`, que devuelve un puntero al objeto que envió la señal.

Las expresiones lambda son una forma práctica de pasar argumentos personalizados a una slot:

connect(action, &QAction::triggered, engine,
        [=]() { engine->processAction(action->text()); });

Uso de Qt con señales y slots de terceros

Es posible utilizar Qt con un mecanismo de señales y ranuras de terceros. Incluso puedes utilizar ambos mecanismos en el mismo proyecto. Para ello, escribe lo siguiente en tu archivo de proyecto CMake:

target_compile_definitions(my_app PRIVATE QT_NO_KEYWORDS)

En un archivo de proyecto qmake (.pro), debes escribir:

CONFIG += no_keywords

Esto indica a Qt que no defina las palabras clave moc « signals », « slots » y « emit », ya que estos nombres serán utilizados por una biblioteca de terceros, como por ejemplo Boost. A continuación, para seguir utilizando las señales y ranuras de Qt con el indicador « no_keywords », basta con sustituir todas las apariciones de las palabras clave moc de Qt en tus fuentes por las macros de Qt correspondientes: Q_SIGNALS (o Q_SIGNAL), Q_SLOTS (o Q_SLOT) y Q_EMIT.

Señales y ranuras en bibliotecas basadas en Qt

La API pública de las bibliotecas basadas en Qt debe utilizar las palabras clave « Q_SIGNALS » y « Q_SLOTS » en lugar de « signals » y « slots ». De lo contrario, resulta difícil utilizar dicha biblioteca en un proyecto que defina « QT_NO_KEYWORDS ».

Para aplicar esta restricción, el creador de la biblioteca puede establecer la definición del preprocesador QT_NO_SIGNALS_SLOTS_KEYWORDS al compilar la biblioteca.

Esta definición excluye las señales y las ranuras sin afectar a la posibilidad de utilizar otras palabras clave específicas de Qt en la implementación de la biblioteca.

Véase también QLCDNumber, QObject::connect(), el sistema de metaobjetos y el sistema de propiedades de Qt.

© 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.