Back to Qt.io
Contact Us Blog Download Qt
本页内容

QToolTip Class

QToolTip 类为任何控件提供工具提示（气泡帮助）。更多内容...

头文件： #include <QToolTip>
CMake： find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake： QT += widgets

静态公共成员

QFont font()
void hideText()
bool isVisible()
QPalette palette()
void setFont(const QFont &font)
void setPalette(const QPalette &palette)
void showText(const QPoint &pos, const QString &text, QWidget *w = nullptr, const QRect &rect = {}, int msecDisplayTime = -1)
QString text()

详细说明

提示是一段简短的文本，用于提醒用户该控件的功能。它以醒目的黑底黄字配色方案，绘制在指定位置的正下方。提示可以是任何经过rich text 格式化的字符串。

除非通过<p style='white-space:pre'> 另行指定，否则工具提示中显示的富文本会默认进行换行。

通过QAction 创建的UI元素使用QAction 的tooltip属性，因此对于大多数交互式UI元素而言，设置该属性是提供工具提示的最简单方法。

QAction *openAction = new QAction(tr("&Open..."));
openAction->setToolTip(tr("Open an existing file"));

fileMenu = menuBar()->addMenu(tr("&File"));
fileToolBar = addToolBar(tr("&File"));

fileMenu->addAction(openAction);
fileToolBar->addAction(openAction);

对于任何其他小部件，设置小部件工具提示最简单、最常见的方法是调用其QWidget::setToolTip() 函数。

searchBar = new SearchBar;
searchBar->setToolTip(tr("Search in the current document"));

此外，还可以通过使用类型为QEvent::ToolTip 的QHelpEvent 来为小部件的不同区域显示不同的工具提示。在小部件的event()函数中拦截help事件，并使用要显示的文本调用QToolTip::showText()。

bool Window::event(QEvent *event)
{
    if (event->type() == QEvent::ToolTip) {
        auto *helpEvent = static_cast<QHelpEvent *>(event);
        if (Element *element = elementAt(helpEvent->pos())) {
            QToolTip::showText(helpEvent->globalPos(), element->toolTip(), this);
        } else {
            QToolTip::hideText();
            event->ignore();
        }

        return true;
    }
    return QWidget::event(event);
}

如果您在触发ToolTip 事件后，调用QToolTip::hideText() 或QToolTip::showText() 并传入空字符串，则还应针对该事件调用ignore()，以表明您不希望启动任何与工具提示相关的模式。

请注意，若要在项目视图中显示工具提示，模型/视图架构提供了设置项目工具提示的功能；例如，QTableWidgetItem::setToolTip() 函数。但是，若要在项目视图中提供自定义工具提示，则必须在QAbstractItemView::viewportEvent() 函数中拦截 help 事件并自行处理。

可以通过setPalette() 和setFont() 自定义默认工具提示的颜色和字体。当工具提示当前显示时，isVisible() 返回true ，而text() 返回当前可见的文本。

注意：工具 提示使用QPalette 中的非活动颜色组，因为工具提示不是活动窗口。

另请参阅 QWidget::toolTip 和QAction::toolTip 。

成员函数文档

[static] QFont QToolTip::font()

返回用于渲染工具提示的字体。

另请参阅 ` setFont()`。

[static] void QToolTip::hideText()

隐藏工具提示。这与使用空字符串调用showText()的效果相同。

另请参阅 showText()。

[static] bool QToolTip::isVisible()

如果当前显示了工具提示，则返回true 。

另请参阅 showText()。

[static] QPalette QToolTip::palette()

返回用于渲染工具提示的调色板。

注意：工具 提示使用 `QPalette` 中的非活动颜色组，因为工具提示并非活动窗口。

另请参阅 setPalette()。

[static] void QToolTip::setFont(const QFont &font)

设置用于渲染工具提示的font 。

另请参阅 font()。

[static] void QToolTip::setPalette(const QPalette &palette)

设置用于渲染工具提示的palette 。

注意：工具 提示使用QPalette 中的非活动颜色组，因为工具提示不是活动窗口。

另请参阅 palette()。

[static] void QToolTip::showText(const QPoint &pos, const QString &text, QWidget *w = nullptr, const QRect &rect = {}, int msecDisplayTime = -1)

显示工具提示text ，并将全局位置pos 设为焦点点。工具提示将以该焦点点为基准，根据平台特性偏移一定距离后显示。

如果您指定了一个非空的矩形区域，则当光标移出该区域时，提示信息将立即隐藏。

rect 采用您通过w 指定的控件坐标系。若rect 不为空，则必须指定一个控件。否则，该参数可设为nullptr ，但该值仅用于在多显示器系统中确定相应的屏幕。

msecDisplayTime 参数指定工具提示的显示时长（单位为毫秒）。默认值为-1时，显示时长取决于文本的长度。

如果 `text ` 为空，则工具提示将被隐藏。如果文本与当前显示的工具提示相同，则提示不会移动。您可以通过先使用空文本隐藏提示，然后在新的位置显示新提示，来强制移动。

[static] QString QToolTip::text()

如果工具提示可见，则返回工具提示文本；如果工具提示不可见，则返回空字符串。

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