Back to Qt.io
Contact Us Blog Download Qt

QToolTip Class

QToolTip 类为任何 widget 提供工具提示（气球帮助）。更多

Header： #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 的工具提示属性，因此对于大多数交互式 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"));

通过使用QHelpEvent 类型的QEvent::ToolTip ，也可以为部件的不同区域显示不同的工具提示。在 widget 的event() 函数中拦截帮助事件，然后调用QToolTip::showText() 并显示想要显示的文本。

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

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

如果您在调用QToolTip::hideText() 或QToolTip::showText() 时使用的是空字符串，作为ToolTip 事件的结果，您还应在事件上调用ignore() 以表示您不想启动任何特定的工具提示模式。

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

默认工具提示的颜色和字体可以通过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()

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

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