QSystemTrayIcon Class
La clase QSystemTrayIcon proporciona un icono para una aplicación en la bandeja del sistema. Más información...
| Encabezado: | #include <QSystemTrayIcon> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Heredado de: | QObject |
Tipos públicos
| enum | ActivationReason { Unknown, Context, DoubleClick, Trigger, MiddleClick } |
| enum | MessageIcon { NoIcon, Information, Warning, Critical } |
Propiedades
Funciones públicas
| QSystemTrayIcon(QObject *parent = nullptr) | |
| QSystemTrayIcon(const QIcon &icon, QObject *parent = nullptr) | |
| virtual | ~QSystemTrayIcon() |
| QMenu * | contextMenu() const |
| QRect | geometry() const |
| QIcon | icon() const |
| bool | isVisible() const |
| void | setContextMenu(QMenu *menu) |
| void | setIcon(const QIcon &icon) |
| void | setToolTip(const QString &tip) |
| QString | toolTip() const |
Ranuras públicas
| void | hide() |
| void | setVisible(bool visible) |
| void | show() |
| void | showMessage(const QString &title, const QString &message, QSystemTrayIcon::MessageIcon icon = QSystemTrayIcon::Information, int millisecondsTimeoutHint = 10000) |
| void | showMessage(const QString &title, const QString &message, const QIcon &icon, int millisecondsTimeoutHint = 10000) |
Señales
| void | activated(QSystemTrayIcon::ActivationReason reason) |
| void | messageClicked() |
Miembros públicos estáticos
| bool | isSystemTrayAvailable() |
| bool | supportsMessages() |
Funciones protegidas reimplementadas
| virtual bool | event(QEvent *e) override |
Descripción detallada
Los sistemas operativos modernos suelen ofrecer un área especial en el escritorio, denominada bandeja del sistema o área de notificaciones, donde las aplicaciones que se ejecutan de forma prolongada pueden mostrar iconos y mensajes breves.

La clase QSystemTrayIcon se puede utilizar en las siguientes plataformas:
- Todas las versiones compatibles de Windows.
- Todos los entornos de escritorio de Linux que implementen la especificación StatusNotifierItem de D-Bus, incluidos KDE, Gnome, Xfce, LXQt y DDE.
- Todos los gestores de ventanas e implementaciones independientes de la bandeja para X11 que implementen la especificación de la bandeja del sistema XEmbed de freedesktop.org.
- Todas las versiones compatibles de macOS.
Para comprobar si hay una bandeja del sistema en el escritorio del usuario, llama a la función estática ` QSystemTrayIcon::isSystemTrayAvailable()`.
Para añadir una entrada a la bandeja del sistema, crea un objeto `QSystemTrayIcon`, llama a ` setContextMenu()` para proporcionar un menú contextual al icono y llama a ` show()` para que sea visible en la bandeja del sistema. Los mensajes de notificación de estado («mensajes de globo») se pueden mostrar en cualquier momento utilizando ` showMessage()`.
Si la bandeja del sistema no está disponible cuando se crea un icono de la bandeja del sistema, pero pasa a estarlo más tarde, QSystemTrayIcon añadirá automáticamente una entrada para la aplicación en la bandeja del sistema si el icono está en estado « visible ».
La señal activated() se emite cuando el usuario activa el icono.
Solo en X11, cuando se solicita una descripción emergente, QSystemTrayIcon recibe un ` QHelpEvent ` de tipo ` QEvent::ToolTip`. Además, QSystemTrayIcon recibe eventos de rueda de tipo ` QEvent::Wheel`. Estos no son compatibles con ninguna otra plataforma. Nota: Desde la versión 3.26 de GNOME Shell, el sistema no admite todos los ` QSystemTrayIcon::ActivationReason ` si no se han instalado extensiones del shell.
Véase también QDesktopServices, Integración en el escritorio y Ejemplo de icono de la bandeja del sistema.
Documentación sobre tipos de miembros
enum QSystemTrayIcon::ActivationReason
Esta enumeración describe el motivo por el que se activó la bandeja del sistema.
| Constante | Valor | Descripción |
|---|---|---|
QSystemTrayIcon::Unknown | 0 | Motivo desconocido |
QSystemTrayIcon::Context | 1 | Se ha solicitado el menú contextual de la entrada de la bandeja del sistema |
QSystemTrayIcon::DoubleClick | 2 | Se ha hecho doble clic en el icono de la bandeja del sistema. Nota: En macOS, solo se emitirá un doble clic si no hay ningún menú contextual configurado, ya que el menú se abre al pulsar el ratón. |
QSystemTrayIcon::Trigger | 3 | Se ha hecho clic en el icono de la bandeja del sistema |
QSystemTrayIcon::MiddleClick | 4 | Se ha hecho clic en el icono de la bandeja del sistema con el botón central del ratón |
Véase también activated().
enum QSystemTrayIcon::MessageIcon
Esta enumeración describe el icono que aparece cuando se muestra un mensaje en un globo.
| Constante | Valor | Descripción |
|---|---|---|
QSystemTrayIcon::NoIcon | 0 | No se muestra ningún icono. |
QSystemTrayIcon::Information | 1 | Se muestra un icono de información. |
QSystemTrayIcon::Warning | 2 | Se muestra un icono de advertencia estándar. |
QSystemTrayIcon::Critical | 3 | Se muestra un icono de advertencia crítica. |
Véase también QMessageBox.
Documentación de propiedades
icon : QIcon
Esta propiedad determina el icono de la bandeja del sistema
En Windows, el tamaño del icono de la bandeja del sistema es de 16x16; en X11, el tamaño recomendado es de 22x22. El icono se ajustará al tamaño adecuado según sea necesario.
Funciones de acceso:
| QIcon | icon() const |
| void | setIcon(const QIcon &icon) |
toolTip : QString
Esta propiedad contiene la descripción emergente de la entrada de la bandeja del sistema
En algunos sistemas, la longitud de la descripción emergente está limitada. La descripción emergente se truncará si es necesario.
Funciones de acceso:
| QString | toolTip() const |
| void | setToolTip(const QString &tip) |
visible : bool
Esta propiedad indica si el icono de la bandeja del sistema está visible
Al establecer esta propiedad en «true» o al llamar a show(), el icono de la bandeja del sistema se muestra; al establecerla en «false» o al llamar a hide(), se oculta.
Funciones de acceso:
| bool | isVisible() const |
| void | setVisible(bool visible) |
Documentación de las funciones de miembro
QSystemTrayIcon::QSystemTrayIcon(QObject *parent = nullptr)
Crea un objeto `QSystemTrayIcon` con el ` parent` indicado.
El icono está inicialmente oculto.
Véase también visible.
QSystemTrayIcon::QSystemTrayIcon(const QIcon &icon, QObject *parent = nullptr)
Crea un objeto `QSystemTrayIcon` con los valores ` icon ` y ` parent` indicados.
El icono está inicialmente oculto.
Véase también visible.
[virtual noexcept] QSystemTrayIcon::~QSystemTrayIcon()
Elimina el icono de la bandeja del sistema y libera todos los recursos asignados.
[signal] void QSystemTrayIcon::activated(QSystemTrayIcon::ActivationReason reason)
Esta señal se emite cuando el usuario activa el icono de la bandeja del sistema. reason especifica el motivo de la activación. QSystemTrayIcon::ActivationReason enumera los distintos motivos.
Véase también QSystemTrayIcon::ActivationReason.
QMenu *QSystemTrayIcon::contextMenu() const
Devuelve el menú contextual actual de la entrada de la bandeja del sistema.
Véase también setContextMenu().
[override virtual protected] bool QSystemTrayIcon::event(QEvent *e)
Reimplementa: ` QObject::event(QEvent *e)`.
QRect QSystemTrayIcon::geometry() const
Devuelve la geometría del icono de la bandeja del sistema en coordenadas de pantalla.
Véase también visible.
[slot] void QSystemTrayIcon::hide()
Oculta el icono de la bandeja del sistema.
Véase también show() y visible.
[static] bool QSystemTrayIcon::isSystemTrayAvailable()
Devuelve « true » si la bandeja del sistema está disponible; en caso contrario, devuelve « false ».
Si la bandeja del sistema no está disponible en ese momento, pero pasa a estarlo más tarde, QSystemTrayIcon añadirá automáticamente una entrada en la bandeja del sistema si es visible.
[signal] void QSystemTrayIcon::messageClicked()
Esta señal se emite cuando el usuario hace clic en el mensaje mostrado mediante ` showMessage()`.
Nota: Seguimos el comportamiento de Microsoft Windows, por lo que la señal también se emite cuando el usuario hace clic en un icono de la bandeja con un mensaje de globo de información visible.
Véase también activated().
void QSystemTrayIcon::setContextMenu(QMenu *menu)
Establece el archivo « menu » especificado como menú contextual del icono de la bandeja del sistema.
El menú aparecerá cuando el usuario solicite el menú contextual del icono de la bandeja del sistema haciendo clic con el botón del ratón.
Nota: El icono de la bandeja del sistema no asume la propiedad del menú. Debes asegurarte de que se elimine en el momento adecuado, por ejemplo, creando el menú con un objeto padre adecuado.
Véase también contextMenu().
[slot] void QSystemTrayIcon::show()
Muestra el icono en la bandeja del sistema.
Véase también hide() y visible.
[slot] void QSystemTrayIcon::showMessage(const QString &title, const QString &message, QSystemTrayIcon::MessageIcon icon = QSystemTrayIcon::Information, int millisecondsTimeoutHint = 10000)
Muestra un mensaje emergente para la entrada con los valores indicados en title, message y icon durante el tiempo especificado en millisecondsTimeoutHint. title y message deben ser cadenas de texto sin formato.
El usuario puede hacer clic en el mensaje; cuando esto ocurra, se emitirá la señal messageClicked().
Tenga en cuenta que la visualización de los mensajes depende de la configuración del sistema y de las preferencias del usuario, y que es posible que los mensajes no aparezcan en absoluto. Por lo tanto, no se debe confiar en ellos como único medio para proporcionar información crítica.
En Windows, el sistema suele ignorar la señal ` millisecondsTimeoutHint ` cuando la aplicación tiene el foco.
Se ha convertido en una ranura en Qt 5.2.
Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:
// Connect using qOverload:
connect(sender, &SenderClass::signal,
systemTrayIcon, qOverload(&QSystemTrayIcon::showMessage));
// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
systemTrayIcon, [receiver = systemTrayIcon](const QString &title, const QString &message, QSystemTrayIcon::MessageIcon icon, int millisecondsTimeoutHint) { receiver->showMessage(title, message, icon, millisecondsTimeoutHint); }); Véase también « show()» y « supportsMessages()».
[slot] void QSystemTrayIcon::showMessage(const QString &title, const QString &message, const QIcon &icon, int millisecondsTimeoutHint = 10000)
Muestra un mensaje emergente para la entrada con el texto « title », el enlace « message » y el icono personalizado « icon », durante el tiempo especificado en « millisecondsTimeoutHint ».
Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:
// Connect using qOverload:
connect(sender, &SenderClass::signal,
systemTrayIcon, qOverload(&QSystemTrayIcon::showMessage));
// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
systemTrayIcon, [receiver = systemTrayIcon](const QString &title, const QString &message, const QIcon &icon, int millisecondsTimeoutHint) { receiver->showMessage(title, message, icon, millisecondsTimeoutHint); }); [static] bool QSystemTrayIcon::supportsMessages()
Devuelve ` true ` si la bandeja del sistema admite mensajes emergentes; en caso contrario, devuelve ` false`.
Véase también showMessage().
© 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.