QTimer Class
La clase QTimer ofrece temporizadores recurrentes y de una sola vez. Más información...
| Encabezado: | #include <QTimer> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| Heredado de: | QObject |
- Lista de todos los miembros, incluidos los heredados
- Miembros obsoletos
- QTimer forma parte de las clases de eventos.
Propiedades
|
|
Funciones públicas
| QTimer(QObject *parent = nullptr) | |
| virtual | ~QTimer() |
| QBindable<bool> | bindableActive() |
| QBindable<int> | bindableInterval() |
| QBindable<bool> | bindableSingleShot() |
| QBindable<Qt::TimerType> | bindableTimerType() |
| QMetaObject::Connection | callOnTimeout(Functor &&slot) |
| QMetaObject::Connection | callOnTimeout(const QObject *context, Functor &&slot, Qt::ConnectionType connectionType = Qt::AutoConnection) |
(since 6.8) Qt::TimerId | id() const |
| int | interval() const |
| std::chrono::milliseconds | intervalAsDuration() const |
| bool | isActive() const |
| bool | isSingleShot() const |
| int | remainingTime() const |
| std::chrono::milliseconds | remainingTimeAsDuration() const |
| void | setInterval(int msec) |
| void | setInterval(std::chrono::milliseconds value) |
| void | setSingleShot(bool singleShot) |
| void | setTimerType(Qt::TimerType atype) |
| void | start(std::chrono::milliseconds interval) |
| int | timerId() const |
| Qt::TimerType | timerType() const |
Ranuras públicas
Señales
| void | timeout() |
Miembros públicos estáticos
| void | singleShot(Duration interval, Functor &&functor) |
| void | singleShot(Duration interval, Qt::TimerType timerType, Functor &&functor) |
| void | singleShot(Duration interval, const QObject *context, Functor &&functor) |
| void | singleShot(Duration interval, Qt::TimerType timerType, const QObject *context, Functor &&functor) |
| void | singleShot(std::chrono::nanoseconds nsec, const QObject *receiver, const char *member) |
| void | singleShot(std::chrono::nanoseconds nsec, Qt::TimerType timerType, const QObject *receiver, const char *member) |
Funciones protegidas reimplementadas
| virtual void | timerEvent(QTimerEvent *e) override |
Descripción detallada
La clase QTimer proporciona una interfaz de programación de alto nivel para temporizadores. Para utilizarla, crea un QTimer, conecta su señal « timeout()» a los slots adecuados y llama a « start()». A partir de ese momento, emitirá la señal « timeout()» a intervalos constantes.
Ejemplo de un temporizador de un segundo (1000 milisegundos) (del ejemplo «Analog Clock» ):
QTimer *timer = new QTimer(this);
connect(timer, &QTimer::timeout, this, QOverload<>::of(&AnalogClock::update));
timer->start(1000);A partir de ese momento, la ranura ` update() ` se invoca cada segundo.
Puedes configurar un temporizador para que expire solo una vez llamando a ` setSingleShot(true)`. También puedes utilizar la función estática ` QTimer::singleShot()` para llamar a una ranura tras un intervalo especificado:
QTimer::singleShot(200, this, &Foo::updateCaption);En aplicaciones multihilo, puedes utilizar QTimer en cualquier hilo que tenga un bucle de eventos. Para iniciar un bucle de eventos desde un hilo que no sea de la interfaz gráfica de usuario, utiliza QThread::exec(). Qt utiliza la función ` thread affinity ` del temporizador para determinar qué hilo emitirá la señal ` timeout()`. Por este motivo, debes iniciar y detener el temporizador en su propio hilo; no es posible iniciar un temporizador desde otro hilo.
Como caso especial, un `QTimer` con un tiempo de espera de 0 se agotará lo antes posible, aunque el orden entre los temporizadores con tiempo de espera cero y otras fuentes de eventos no está especificado. Los temporizadores con tiempo de espera cero se pueden utilizar para realizar algunas tareas sin dejar de ofrecer una interfaz de usuario ágil:
QTimer *timer = new QTimer(this);
connect(timer, &QTimer::timeout, this, &Foo::processOneThing);
timer->start();A partir de ese momento, se llamará repetidamente a ` processOneThing() `. Debe escribirse de tal forma que siempre devuelva un resultado rápidamente (normalmente tras procesar un elemento de datos), de modo que Qt pueda enviar eventos a la interfaz de usuario y detener el temporizador tan pronto como haya completado todo su trabajo. Esta es la forma tradicional de implementar tareas pesadas en aplicaciones GUI, pero dado que el multihilo está cada vez más disponible en más plataformas, esperamos que los objetos QTimer de cero milisegundos sean sustituidos gradualmente por los de « QThread».
Precisión y resolución del temporizador
La precisión de los temporizadores depende del sistema operativo y del hardware subyacentes. La mayoría de las plataformas admiten una resolución de 1 milisegundo, aunque la precisión del temporizador no será igual a esta resolución en muchas situaciones reales.
La precisión también depende del timer type. En el caso de los Qt::PreciseTimer, QTimer intentará mantener la precisión en 1 milisegundo. Además, los temporizadores precisos nunca se agotarán antes de lo esperado.
Para los tipos Qt::CoarseTimer y Qt::VeryCoarseTimer, QTimer puede activarse antes de lo esperado, dentro de los márgenes establecidos para dichos tipos: el 5 % del intervalo para Qt::CoarseTimer y 500 ms para Qt::VeryCoarseTimer.
Todos los tipos de temporizador pueden agotar el tiempo de espera más tarde de lo esperado si el sistema está ocupado o no puede proporcionar la precisión solicitada. En tal caso de sobrepaso del tiempo de espera, Qt emitirá timeout() solo una vez, incluso si han expirado varios tiempos de espera, y luego reanudará el intervalo original.
Alternativas a QTimer
Qt 6.8 introdujo QChronoTimer. La principal diferencia entre ambas clases es que QChronoTimer admite un rango de intervalos más amplio y una mayor precisión (std::chrono::nanoseconds). Para QTimer, el intervalo máximo admitido es de ±24 días, mientras que para QChronoTimer es de ±292 años (menor probabilidad de desbordamiento de enteros con intervalos superiores a std::numeric_limits<int>::max()). Si solo necesitas una resolución de milisegundos y un rango de ±24 días, puedes seguir utilizando QTimer.
Otra alternativa es reimplementar el método QObject::timerEvent() en tu clase (que debe ser una subclase de QObject) y utilizar uno de los siguientes enfoques:
- Utilizar ` QBasicTimer`, una clase de valor ligera que envuelve un identificador de temporizador. Puedes iniciar el temporizador con ` QBasicTimer::start()` y detenerlo con ` QBasicTimer::stop()`. Puedes gestionar el evento en tu método ` timerEvent()` reimplementado.
- timerEventUn método de nivel más bajo consiste en manipular directamente los identificadores de temporizador. Para iniciar el temporizador, llama a ` QObject::startTimer()`, almacenando el identificador devuelto. Para detener el temporizador, llama a ` QObject::killTimer()`. Puedes gestionar el evento en tu implementación de ` QBasicTimer()`. Este enfoque suele ser más engorroso que utilizar ` `.
Una desventaja de utilizar timerEvent() es que algunas características de alto nivel, como los temporizadores de un solo disparo y las señales, no son compatibles.
Algunos sistemas operativos limitan el número de temporizadores que se pueden utilizar; Qt intenta sortear estas limitaciones.
Véase también QBasicTimer, QTimerEvent, QObject::timerEvent(), Temporizadores y Reloj analógico.
Documentación de propiedades
[bindable read-only] active : bool
Nota: Esta propiedad admite enlaces de tipo « QProperty ».
Esta propiedad booleana es « true » si el temporizador está en marcha; en caso contrario, es «false».
Funciones de acceso:
| bool | isActive() const |
[bindable] interval : int
Nota: Esta propiedad admite enlaces de tipo « QProperty ».
Esta propiedad contiene el intervalo de tiempo de espera en milisegundos
El valor por defecto de esta propiedad es 0. Un « QTimer » con un intervalo de tiempo de espera de 0 agotará el tiempo de espera tan pronto como se hayan procesado todos los eventos de la cola de eventos del sistema de ventanas.
Nota: Mantener el bucle de eventos ocupado con un temporizador de valor cero provocará inevitablemente problemas y un comportamiento muy errático de la interfaz de usuario.
Al establecer el intervalo de un temporizador en ejecución, se modificará el intervalo, se llamará a ` stop()` y, a continuación, a ` start()` sobre el temporizador, y se obtendrá un nuevo ` id()`. Si el temporizador no está en ejecución, solo se modificará el intervalo.
A partir de Qt 6.10, establecer un intervalo negativo provocará una advertencia en tiempo de ejecución y el valor se restablecerá a 1 ms. Antes de Qt 6.10, un temporizador de Qt permitía establecer un intervalo negativo, pero se comportaba de forma impredecible (por ejemplo, detenía el temporizador si estaba en marcha o no lo iniciaba en absoluto).
Funciones de acceso:
| int | interval() const |
| void | setInterval(int msec) |
| void | setInterval(std::chrono::milliseconds value) |
Véase también singleShot.
[read-only] remainingTime : int
Esta propiedad contiene el tiempo restante en milisegundos
Devuelve el tiempo restante del temporizador, en milisegundos, hasta que se agote el tiempo de espera. Si el temporizador está inactivo, el valor devuelto será -1. Si el temporizador ha expirado, el valor devuelto será 0.
Funciones de acceso:
| int | remainingTime() const |
Véase también interval.
[bindable] singleShot : bool
Nota: Esta propiedad admite enlaces de tipo « QProperty ».
Esta propiedad indica si el temporizador es de un solo disparo
Un temporizador de un solo disparo se activa solo una vez, mientras que los temporizadores que no son de un solo disparo se activan cada interval milisegundos.
El valor predeterminado de esta propiedad es « false ».
Funciones de acceso:
| bool | isSingleShot() const |
| void | setSingleShot(bool singleShot) |
Véase también interval y singleShot().
[bindable] timerType : Qt::TimerType
Nota: Esta propiedad admite enlaces de tipo « QProperty ».
controla la precisión del temporizador
El valor por defecto de esta propiedad es « Qt::CoarseTimer ».
Funciones de acceso:
| Qt::TimerType | timerType() const |
| void | setTimerType(Qt::TimerType atype) |
Véase también Qt::TimerType.
Documentación de funciones de miembro
[explicit] QTimer::QTimer(QObject *parent = nullptr)
Crea un temporizador con el valor dado « parent ».
[virtual noexcept] QTimer::~QTimer()
Elimina el temporizador.
template <typename Functor> QMetaObject::Connection QTimer::callOnTimeout(Functor &&slot)
Crea una conexión entre la señal « timeout()» del temporizador y « slot ». Devuelve un identificador de la conexión.
Este método se proporciona para mayor comodidad. Es equivalente a llamar a:
Nota: Esta sobrecarga no está disponible cuando se define ` QT_NO_CONTEXTLESS_CONNECT `; en su lugar, utilice la sobrecarga `callOnTimeout()` que toma un objeto de contexto.
Véase también QObject::connect() y timeout().
template <typename Functor> QMetaObject::Connection QTimer::callOnTimeout(const QObject *context, Functor &&slot, Qt::ConnectionType connectionType = Qt::AutoConnection)
Crea una conexión desde la señal ` timeout()` hasta ` slot ` para colocarla en un bucle de eventos específico de ` context`, y devuelve un identificador de la conexión.
Este método se proporciona por comodidad. Equivale a llamar a:
Esta función sobrecarga QTimer::callOnTimeout().
Véase también QObject::connect() y timeout().
[since 6.8] Qt::TimerId QTimer::id() const
Devuelve un objeto ` Qt::TimerId ` que representa el ID del temporizador si este está en marcha; en caso contrario, devuelve un objeto ` Qt::TimerId::Invalid`.
Esta función se introdujo en Qt 6.8.
Véase también ` Qt::TimerId`.
std::chrono::milliseconds QTimer::intervalAsDuration() const
Devuelve el intervalo de este temporizador como un objeto de tipo ` std::chrono::milliseconds `.
Véase también interval.
bool QTimer::isActive() const
Devuelve ` true ` si el temporizador está en marcha; en caso contrario, devuelve ` false`.
Nota: Funcióngetter para la propiedad active.
std::chrono::milliseconds QTimer::remainingTimeAsDuration() const
Devuelve el tiempo restante en este objeto temporizador como un objeto ` std::chrono::milliseconds `. Si este temporizador ha llegado a su fecha de vencimiento o ya ha vencido, el valor devuelto es ` std::chrono::milliseconds::zero()`. Si no se ha podido encontrar el tiempo restante o el temporizador no está en marcha, esta función devuelve una duración negativa.
Véase también remainingTime().
[static] template <typename Duration, typename Functor> void QTimer::singleShot(Duration interval, Functor &&functor)
[static] template <typename Duration, typename Functor> void QTimer::singleShot(Duration interval, Qt::TimerType timerType, Functor &&functor)
[static] template <typename Duration, typename Functor> void QTimer::singleShot(Duration interval, const QObject *context, Functor &&functor)
[static] template <typename Duration, typename Functor> void QTimer::singleShot(Duration interval, Qt::TimerType timerType, const QObject *context, Functor &&functor)
Esta función estática llama a functor tras interval.
Es muy práctico utilizar esta función, ya que evita tener que preocuparse por un timerEvent o crear un objeto local QTimer.
Si se especifica ` context `, entonces ` functor ` solo se llamará si el objeto ` context ` no ha sido destruido antes de que se produzca el intervalo. El functor se ejecutará entonces en el hilo de ` context`. El hilo del contexto debe tener un bucle de eventos de Qt en ejecución.
Si functor es una función miembro de context, la función se llamará sobre el objeto.
El parámetro interval puede ser un int (interpretado como un recuento de milisegundos) o un tipo std::chrono que se convierte implícitamente a nanosegundos.
A partir de Qt 6.10, establecer un intervalo negativo dará lugar a una advertencia en tiempo de ejecución y el valor se restablecerá a 1 ms. Antes de Qt 6.10, un temporizador de Qt permitía establecer un intervalo negativo, pero se comportaba de forma impredecible (por ejemplo, detenía el temporizador si estaba en marcha o no lo iniciaba en absoluto).
Nota: En las versiones de Qt anteriores a la 6.8, las sobrecargas de `chrono` aceptaban `chrono::milliseconds`, no `chrono::nanoseconds`. El compilador realizará la conversión automáticamente, pero puede producirse un desbordamiento en recuentos de milisegundos extremadamente grandes.
Nota: Esta función es reentrante.
Véase también ` start()`.
[static] void QTimer::singleShot(std::chrono::nanoseconds nsec, const QObject *receiver, const char *member)
Esta función estática llama a una ranura tras un intervalo de tiempo determinado.
Es muy práctico utilizar esta función, ya que no es necesario preocuparse por un ` timerEvent ` ni crear un objeto ` QTimer ` local.
El objeto « receiver » es el objeto receptor y el « member » es la ranura. El intervalo de tiempo se especifica en el objeto de duración « nsec ».
A partir de Qt 6.10, establecer un intervalo negativo provocará una advertencia en tiempo de ejecución y el valor se restablecerá a 1 ms. Antes de Qt 6.10, un Qt Timer permitía establecer un intervalo negativo, pero se comportaba de forma impredecible (por ejemplo, detenía el temporizador si estaba en marcha o no lo iniciaba en absoluto).
Nota: En las versiones de Qt anteriores a la 6.8, esta función aceptaba chrono::milliseconds, no chrono::nanoseconds. El compilador realizará la conversión automáticamente, pero puede producirse un desbordamiento en recuentos de milisegundos extremadamente grandes.
Esta es una función sobrecargada.
Nota: Esta función es reentrante.
Véase también start().
[static] void QTimer::singleShot(std::chrono::nanoseconds nsec, Qt::TimerType timerType, const QObject *receiver, const char *member)
Esta función estática llama a una ranura tras un intervalo de tiempo determinado.
Es muy práctico utilizar esta función, ya que evita tener que preocuparse por un ` timerEvent ` o crear un objeto ` QTimer ` local.
El objeto « receiver » es el objeto receptor y el « member » es la ranura. El intervalo de tiempo se especifica en el objeto de duración « nsec ». El « timerType » afecta a la precisión del temporizador.
A partir de Qt 6.10, establecer un intervalo negativo provocará una advertencia en tiempo de ejecución y el valor se restablecerá a 1 ms. Antes de Qt 6.10, un temporizador de Qt permitía establecer un intervalo negativo, pero se comportaba de forma impredecible (por ejemplo, detenía el temporizador si estaba en marcha o no lo iniciaba en absoluto).
Nota: En las versiones de Qt anteriores a la 6.8, esta función aceptaba chrono::milliseconds, no chrono::nanoseconds. El compilador realizará la conversión automáticamente, pero puede producirse un desbordamiento en el caso de recuentos de milisegundos extremadamente grandes.
Esta es una función sobrecargada.
Nota: Esta función es reentrante.
Véase también ` start()`.
[slot] void QTimer::start(int msec)
Inicia o reinicia el temporizador con un intervalo de espera de msec milisegundos.
Esto equivale a:
timer.setInterval(msec);
timer.start();Si el temporizador ya está en marcha, se detendrá stopped y se reiniciará. Esto también modificará su valor de « id()».
Si singleShot es verdadero, el temporizador solo se activará una vez.
A partir de Qt 6.10, establecer un intervalo negativo provocará una advertencia en tiempo de ejecución y el valor se restablecerá a 1 ms. Antes de Qt 6.10, un temporizador de Qt permitía establecer un intervalo negativo, pero se comportaba de forma impredecible (por ejemplo, detenía el temporizador si estaba en marcha o no lo iniciaba en absoluto).
Nota: Mantener el bucle de eventos ocupado con un temporizador de cero provocará sin duda problemas y un comportamiento muy errático de la interfaz de usuario.
Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:
// Connect using qOverload:
connect(sender, &SenderClass::signal,
timer, qOverload(&QTimer::start));
// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
timer, [receiver = timer](int msec) { receiver->start(msec); }); [slot] void QTimer::start()
Inicia o reinicia el temporizador con el tiempo de espera especificado en « interval ».
Si el temporizador ya está en marcha, se « stopped » y se reiniciará. Esto también modificará su propiedad id().
Si singleShot es verdadero, el temporizador solo se activará una vez.
Nota: Mantener el bucle de eventos ocupado con un temporizador de cero provocará inevitablemente problemas y un comportamiento muy errático de la interfaz de usuario.
Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:
// Connect using qOverload:
connect(sender, &SenderClass::signal,
timer, qOverload<>(&QTimer::start));
// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
timer, [receiver = timer]() { receiver->start(); });void QTimer::start(std::chrono::milliseconds interval)
Inicia o reinicia el temporizador con un tiempo de espera de interval milisegundos.
Esto equivale a:
timer.setInterval(interval);
timer.start();Si el temporizador ya está en marcha, se detendrá ( stopped ) y se reiniciará. Esto también modificará su valor « id()».
Si ` singleShot ` es verdadero, el temporizador solo se activará una vez.
A partir de Qt 6.10, establecer un intervalo negativo provocará una advertencia en tiempo de ejecución y el valor se restablecerá a 1 ms. Antes de Qt 6.10, un temporizador Qt permitía establecer un intervalo negativo, pero se comportaba de forma impredecible (por ejemplo, detenía el temporizador si estaba en marcha o no lo iniciaba en absoluto).
Nota: Mantener el bucle de eventos ocupado con un temporizador de cero provocará sin duda problemas y un comportamiento muy errático de la interfaz de usuario.
Esta es una función sobrecargada.
[slot] void QTimer::stop()
Detiene el temporizador.
Véase también start().
[private signal] void QTimer::timeout()
Esta señal se emite cuando se agota el tiempo del temporizador.
Nota: Se trata de una señal privada. Se puede utilizar en conexiones de señales, pero el usuario no puede emitirla.
Véase también interval, start() y stop().
[override virtual protected] void QTimer::timerEvent(QTimerEvent *e)
Reimplementa: ` QObject::timerEvent(QTimerEvent *event)`.
int QTimer::timerId() const
Devuelve el ID del temporizador si este está en marcha; en caso contrario, devuelve -1.
© 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.