QSystemTrayIcon Class
QSystemTrayIcon 类为系统托盘中的应用程序提供了一个图标。更多
| 头文件： | #include <QSystemTrayIcon> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Widgets)target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake： | QT += widgets |
| 继承： | QObject |
公共类型
| enum | ActivationReason { Unknown, Context, DoubleClick, Trigger, MiddleClick } |
| enum | MessageIcon { NoIcon, Information, Warning, Critical } |
属性
公共功能
| 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 |
公共插槽
| 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) |
信号
| void | activated(QSystemTrayIcon::ActivationReason reason) |
| void | messageClicked() |
静态公共成员
| bool | isSystemTrayAvailable() |
| bool | supportsMessages() |
重新实现的受保护函数
| virtual bool | event(QEvent *e) override |
详细说明
现代操作系统通常会在桌面上提供一个特殊区域，称为系统托盘或通知区域，长期运行的应用程序可在此显示图标和短信息。
QSystemTrayIcon 类可用于以下平台：
- 所有受支持的 Windows 版本。
- 所有实现 D-BusStatusNotifierItem 规范的 Linux 桌面环境，包括 KDE、Gnome、Xfce、LXQt 和 DDE。
- 所有实施freedesktop.org XEmbed 系统托盘规范的 X11 窗口管理器和独立托盘实现。
- 所有支持的 macOS 版本。
要检查用户桌面上是否存在系统托盘，请调用QSystemTrayIcon::isSystemTrayAvailable() 静态函数。
要添加系统托盘条目，请创建一个 QSystemTrayIcon 对象，调用setContextMenu() 为图标提供上下文菜单，然后调用show() 使其在系统托盘中可见。使用showMessage() 可以随时显示状态通知消息（"气球消息"）。
如果在构建系统托盘图标时系统托盘不可用，但后来可用了，QSystemTrayIcon 会自动在系统托盘中为应用程序添加一个条目，如果图标是visible 。
当用户激活图标时，会发出activated() 信号。
只有在 X11 上，当要求提供工具提示时，QSystemTrayIcon 才会接收QEvent::ToolTip 类型的QHelpEvent 信号。此外，QSystemTrayIcon 还会接收QEvent::Wheel 类型的轮子事件。这些在其他平台上都不支持。注：自 GNOME Shell 3.26 版起，并非所有QSystemTrayIcon::ActivationReason 在未安装 shell 扩展的情况下都能被系统支持。
另请参阅 QDesktopServices 、桌面集成和系统托盘图标示例。
成员类型文档
enum QSystemTrayIcon::ActivationReason
该枚举描述了激活系统托盘的原因。
| 常量 | 值 | 说明 |
|---|---|---|
QSystemTrayIcon::Unknown | 0 | 未知原因 |
QSystemTrayIcon::Context | 1 | 请求了系统托盘项的上下文菜单 |
QSystemTrayIcon::DoubleClick | 2 | 双击了系统托盘条目。 |
注意： 在 macOS 上，只有在未设置上下文菜单的情况下才会出现双击，因为菜单会在按下鼠标时打开
| 常量 | 值 | 说明 |
|---|---|---|
QSystemTrayIcon::Trigger | 3 | 系统托盘条目被点击 |
QSystemTrayIcon::MiddleClick | 4 | 用鼠标中键点击了系统托盘条目 |
另请参阅 activated()。
enum QSystemTrayIcon::MessageIcon
该枚举描述了气球信息显示时的图标。
| 常数 | 值 | 说明 |
|---|---|---|
QSystemTrayIcon::NoIcon | 0 | 不显示图标。 |
QSystemTrayIcon::Information | 1 | 显示信息图标。 |
QSystemTrayIcon::Warning | 2 | 显示标准警告图标。 |
QSystemTrayIcon::Critical | 3 | 显示严重警告图标。 |
另请参阅 QMessageBox 。
属性文档
icon : QIcon
该属性用于保存系统托盘图标
在 Windows 系统中，系统托盘图标大小为 16x16；在 X11 系统中，首选大小为 22x22。
访问功能：
| QIcon | icon() const |
| void | setIcon(const QIcon &icon) |
toolTip : QString
该属性用于保存系统托盘条目的工具提示。
在某些系统中，工具提示的长度是有限的。如有必要，工具提示将被截断。
访问功能：
| QString | toolTip() const |
| void | setToolTip(const QString &tip) |
visible : bool
此属性表示系统托盘条目是否可见
将此属性设置为 true 或调用show() 会使系统托盘图标可见；将此属性设置为 false 或调用hide() 会使其隐藏。
访问函数：
| bool | isVisible() const |
| void | setVisible(bool visible) |
成员函数文档
QSystemTrayIcon::QSystemTrayIcon(QObject *parent = nullptr)
用给定的parent 构建一个 QSystemTrayIcon 对象。
图标最初是不可见的。
另请参阅 visible 。
QSystemTrayIcon::QSystemTrayIcon(const QIcon &icon, QObject *parent = nullptr)
用给定的icon 和parent 构建一个 QSystemTrayIcon 对象。
图标最初是不可见的。
另请参阅 visible 。
[virtual noexcept] QSystemTrayIcon::~QSystemTrayIcon()
从系统托盘中删除图标，并释放所有已分配的资源。
[signal] void QSystemTrayIcon::activated(QSystemTrayIcon::ActivationReason reason)
该信号在用户激活系统托盘图标时发出。reason 指定激活原因。QSystemTrayIcon::ActivationReason 列举了各种原因。
另请参阅 QSystemTrayIcon::ActivationReason 。
QMenu *QSystemTrayIcon::contextMenu() const
返回系统托盘条目的当前上下文菜单。
另请参阅 setContextMenu()。
[override virtual protected] bool QSystemTrayIcon::event(QEvent *e)
重实现：QObject::event(QEvent *e)。
QRect QSystemTrayIcon::geometry() const
以屏幕坐标返回系统托盘图标的几何图形。
另请参阅 visible 。
[slot] void QSystemTrayIcon::hide()
隐藏系统托盘条目。
[static] bool QSystemTrayIcon::isSystemTrayAvailable()
如果系统托盘可用，则返回true ；否则返回false 。
如果系统托盘当前不可用，但稍后可用，QSystemTrayIcon ，如果是visible ，则会自动在系统托盘中添加一个条目。
[signal] void QSystemTrayIcon::messageClicked()
当用户点击使用showMessage() 显示的消息时，将发出该信号。
注意： 我们遵循 Microsoft Windows 的行为方式，因此当用户点击显示气球消息的托盘图标时也会发出该信号。
另请参阅 activated()。
void QSystemTrayIcon::setContextMenu(QMenu *menu)
将指定的menu 设置为系统托盘图标的上下文菜单。
当用户单击鼠标按钮请求系统托盘图标的上下文菜单时，菜单将弹出。
注意： 系统托盘图标并不拥有菜单的所有权。您必须确保在适当的时候将其删除，例如，通过适当的父对象创建菜单。
另请参阅 contextMenu()。
[slot] void QSystemTrayIcon::show()
显示系统托盘中的图标。
[slot] void QSystemTrayIcon::showMessage(const QString &title, const QString &message, QSystemTrayIcon::MessageIcon icon = QSystemTrayIcon::Information, int millisecondsTimeoutHint = 10000)
在millisecondsTimeoutHint 中指定的时间内，显示带有给定title 、message 和icon 的条目的气球消息。title 和message 必须是纯文本字符串。
用户可以点击消息；点击时将发出messageClicked() 信号。
请注意，消息的显示取决于系统配置和用户偏好，而且消息可能根本不会显示。因此，不应将其作为提供关键信息的唯一手段。
在 Windows 系统中，当应用程序有焦点时，millisecondsTimeoutHint 通常会被系统忽略。
在 Qt 5.2 中已变成一个槽。
另请参阅 show() 和supportsMessages()。
[slot] void QSystemTrayIcon::showMessage(const QString &title, const QString &message, const QIcon &icon, int millisecondsTimeoutHint = 10000)
该函数重载 showMessage()。
在millisecondsTimeoutHint 中指定的时间内，使用给定的title 、message 和自定义图标icon 显示条目的气球消息。
[static] bool QSystemTrayIcon::supportsMessages()
如果系统托盘支持气球消息，则返回true ；否则返回false 。
另请参阅 showMessage() 。
© 2025 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.
