En esta página

El sistema de eventos

En Qt, los eventos son objetos, derivados de la clase abstracta ` QEvent `, que representan sucesos que han tenido lugar bien dentro de una aplicación, bien como resultado de una actividad externa de la que la aplicación debe tener conocimiento. Cualquier instancia de una subclase de ` QObject ` puede recibir y gestionar eventos, pero estos son especialmente relevantes para los widgets. Este documento describe cómo se transmiten y gestionan los eventos en una aplicación típica.

Cómo se transmiten los eventos

Cuando se produce un evento, Qt crea un objeto de evento para representarlo mediante la construcción de una instancia de la subclase adecuada de ` QEvent `, y lo envía a una instancia concreta de ` QObject ` (o una de sus subclases) llamando a su función ` event()`.

Esta función no gestiona el evento en sí; en función del tipo de evento entregado, llama a un controlador de eventos para ese tipo específico de evento y envía una respuesta según si el evento ha sido aceptado o ignorado.

Algunos eventos, como « QMouseEvent » y « QKeyEvent », proceden del sistema de ventanas; otros, como « QTimerEvent », proceden de otras fuentes; y otros, de la propia aplicación.

Tipos de eventos

La mayoría de los tipos de eventos tienen clases especiales, entre las que destacan QResizeEvent, QPaintEvent, QMouseEvent, QKeyEvent y QCloseEvent. Cada clase es una subclase de QEvent y añade funciones específicas del evento. Por ejemplo, QResizeEvent añade size() y oldSize() para permitir que los widgets detecten cómo se han modificado sus dimensiones.

Algunas clases admiten más de un tipo de evento concreto. ` QMouseEvent ` admite pulsaciones de botones del ratón, doble clic, desplazamientos y otras operaciones relacionadas.

Cada evento tiene un tipo asociado, definido en QEvent::Type, y esto puede utilizarse como una fuente práctica de información de tipos en tiempo de ejecución para determinar rápidamente a partir de qué subclase se ha construido un objeto de evento determinado.

Dado que los programas deben reaccionar de formas variadas y complejas, los mecanismos de entrega de eventos de Qt son flexibles. La documentación de ` QCoreApplication::notify()` explica todo el tema de forma concisa; el artículo de Qt Quarterly «Another Look at Events» lo repasa de forma menos concisa. Aquí explicaremos lo suficiente para el 95 % de las aplicaciones.

Manejadores de eventos

La forma habitual de entregar un evento es llamando a una función virtual. Por ejemplo, el evento « QPaintEvent » se entrega llamando a ` QWidget::paintEvent()`. Esta función virtual se encarga de reaccionar adecuadamente, normalmente redibujando el widget. Si no realizas todo el trabajo necesario en tu implementación de la función virtual, es posible que tengas que llamar a la implementación de la clase base.

Por ejemplo, el siguiente código gestiona los clics con el botón izquierdo del ratón en un widget de casilla de selección personalizado, al tiempo que pasa todos los demás clics de botón a la clase base QCheckBox:

void MyCheckBox::mousePressEvent(QMouseEvent *event)
{
    if (event->button() == Qt::LeftButton) {
        // handle left mouse button here
    } else {
        // pass on other buttons to base class
        QCheckBox::mousePressEvent(event);
    }
}

Si deseas sustituir la función de la clase base, debes implementar todo tú mismo. Sin embargo, si solo deseas ampliar la funcionalidad de la clase base, entonces implementas lo que desees y llamas a la clase base para obtener el comportamiento predeterminado en aquellos casos que no desees gestionar.

En ocasiones, no existe una función específica para un evento, o bien dicha función no es suficiente. El ejemplo más habitual tiene que ver con las pulsaciones de la tecla Tab. Normalmente, QWidget intercepta estas pulsaciones para desplazar el foco del teclado, pero algunos widgets necesitan la tecla Tab para su propio funcionamiento.

Estos objetos pueden reimplementar ` QObject::event()` —el controlador de eventos general— y gestionar el evento antes o después del tratamiento habitual, o bien pueden sustituir la función por completo. Un widget muy poco habitual que interprete la tecla Tab y tenga un evento personalizado específico de la aplicación podría contener la siguiente función ` event()`:

bool MyWidget::event(QEvent *event)
{
    if (event->type() == QEvent::KeyPress) {
        QKeyEvent *ke = static_cast<QKeyEvent *>(event);
        if (ke->key() == Qt::Key_Tab) {
            // special tab handling here
            return true;
        }
    } else if (event->type() == MyCustomEventType) {
        MyCustomEvent *myEvent = static_cast<MyCustomEvent *>(event);
        // custom event handling here
        return true;
    }

    return QWidget::event(event);
}

Tenga en cuenta que QWidget::event() sigue llamándose en todos los casos no gestionados, y que el valor de retorno indica si se ha gestionado un evento; un valor de true impide que el evento se reenvíe a otros objetos.

Filtros de eventos

A veces, un objeto necesita examinar —y, posiblemente, interceptar— los eventos que se envían a otro objeto. Por ejemplo, los cuadros de diálogo suelen querer filtrar las pulsaciones de teclas de algunos widgets; por ejemplo, para modificar el manejo de la tecla «Intro».

La función QObject::installEventFilter() permite hacer esto mediante la configuración de un filtro de eventos, lo que hace que un objeto filtro designado reciba los eventos destinados a un objeto de destino en su función QObject::eventFilter(). Un filtro de eventos procesa los eventos antes que el objeto de destino, lo que le permite inspeccionarlos y descartarlos según sea necesario. Un filtro de eventos existente puede eliminarse mediante la función QObject::removeEventFilter().

Cuando se invoca la implementación de eventFilter() del objeto filtro, este puede aceptar o rechazar el evento, y permitir o denegar su procesamiento posterior. Si todos los filtros de eventos permiten que se siga procesando un evento (devolviendo cada uno de ell false), el evento se envía al propio objeto de destino. Si alguno de ellos detiene el procesamiento (devolviendo true), ni el objeto de destino ni ningún filtro de eventos posterior llegan a ver el evento en absoluto.

bool FilterObject::eventFilter(QObject *object, QEvent *event)
{
    if (object == target && event->type() == QEvent::KeyPress) {
        QKeyEvent *keyEvent = static_cast<QKeyEvent *>(event);
        if (keyEvent->key() == Qt::Key_Tab) {
            // Special tab handling
            return true;
        } else
            return false;
    }
    return false;
}

El código anterior muestra otra forma de interceptar los eventos de pulsación de la tecla Tab enviados a un widget de destino concreto. En este caso, el filtro gestiona los eventos relevantes y devuelve true para impedir que se sigan procesando. Se ignoran todos los demás eventos, y el filtro devuelve false para permitir que se envíen al widget de destino, a través de cualquier otro filtro de eventos que esté instalado en él.

También es posible filtrar todos los eventos de toda la aplicación instalando un filtro de eventos en el objeto ` QApplication ` o ` QCoreApplication `. Estos filtros de eventos globales se invocan antes que los filtros específicos de cada objeto. Se trata de una técnica muy potente, pero también ralentiza la entrega de cada uno de los eventos de toda la aplicación; por lo general, es preferible utilizar las otras técnicas descritas.

Envío de eventos

Muchas aplicaciones desean crear y enviar sus propios eventos. Se pueden enviar eventos exactamente de la misma forma que en el bucle de eventos propio de Qt, creando objetos de evento adecuados y enviándolos con ` QCoreApplication::sendEvent()` y ` QCoreApplication::postEvent()`.

sendEvent() procesa el evento de forma inmediata. Cuando devuelve un resultado, los filtros de eventos y/o el propio objeto ya han procesado el evento. Muchas clases de eventos cuentan con una función llamada isAccepted() que indica si el evento fue aceptado o rechazado por el último controlador al que se llamó.

postEvent() envía el evento a una cola para su posterior despacho. La próxima vez que se ejecute el bucle de eventos principal de Qt, este despachará todos los eventos enviados, con algunas optimizaciones. Por ejemplo, si hay varios eventos de cambio de tamaño, se comprimen en uno solo. Lo mismo se aplica a los eventos de dibujo: ` QWidget::update()` llama a ` postEvent()`, lo que elimina el parpadeo y aumenta la velocidad al evitar múltiples redibujados.

postEvent() también se utiliza durante la inicialización de objetos, ya que el evento publicado suele enviarse muy poco después de que finalice la inicialización del objeto. Al implementar un widget, es importante tener en cuenta que los eventos pueden entregarse muy pronto durante su ciclo de vida, por lo que, en su constructor, hay que asegurarse de inicializar las variables miembro desde el principio, antes de que exista la posibilidad de que reciba un evento.

Para crear eventos de un tipo personalizado, es necesario definir un número de evento, que debe ser mayor que QEvent::User, y puede que sea necesario crear una subclase de QEvent para poder pasar información específica sobre el evento personalizado. Consulte la documentación de QEvent para obtener más detalles.

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