如何在Qt中实现支持QWidget的完全通用工具提示？

直接复用Qt原生QToolTip的所有内置逻辑（显示延迟、自动关闭、鼠标跟踪、单例管理），同时实现复杂自定义内容的核心思路是：将自定义Widget渲染为像素图，再通过QToolTip支持的HTML标签嵌入显示。具体步骤如下：

1. 构建自定义内容Widget #

先创建包含所有所需元素（格式化文本、动态图片、表单布局）的只读QWidget，禁用交互并调整好尺寸：

#include <QWidget>
#include <QVBoxLayout>
#include <QFormLayout>
#include <QLabel>
#include <QPixmap>
#include <QPainter>

class CustomToolTip : public QWidget
{
public:
    CustomToolTip(QWidget *parent = nullptr) : QWidget(parent)
    {
        // 禁用窗口特性，仅作为渲染容器
        setWindowFlags(Qt::Widget | Qt::FramelessWindowHint);
        setAttribute(Qt::WA_TranslucentBackground);
        setEnabled(false); // 禁用交互

        // 构建布局和内容
        auto rootLayout = new QVBoxLayout(this);
        rootLayout->setContentsMargins(10, 8, 10, 8);

        // 粗体标题
        auto title = new QLabel("<b>复杂工具提示</b>");
        rootLayout->addWidget(title);

        // 表单式文本项
        auto formLayout = new QFormLayout();
        formLayout->addRow("文件类型:", new QLabel("<b>压缩包</b>"));
        formLayout->addRow("大小:", new QLabel("1.2 GB"));
        formLayout->addRow("创建时间:", new QLabel("2024-05-20 14:30"));
        rootLayout->addLayout(formLayout);

        // 动态生成图片
        QPixmap dynamicPix(120, 80);
        dynamicPix.fill(Qt::white);
        QPainter painter(&dynamicPix);
        painter.setPen(Qt::darkBlue);
        painter.drawRect(5, 5, 110, 70);
        painter.drawText(dynamicPix.rect(), Qt::AlignCenter, "预览图");
        
        auto imageLabel = new QLabel();
        imageLabel->setPixmap(dynamicPix);
        rootLayout->addWidget(imageLabel);

        // 自动调整尺寸以适配内容
        adjustSize();
    }
};

2. 渲染Widget为像素图并通过QToolTip显示 #

在需要触发工具提示的部件中，重写event方法或安装事件过滤器，捕获QEvent::ToolTip事件，将自定义Widget渲染为像素图后转为base64嵌入HTML，再调用QToolTip::showText：

#include <QHelpEvent>
#include <QToolTip>
#include <QBuffer>

bool TargetWidget::event(QEvent *event)
{
    if (event->type() == QEvent::ToolTip)
    {
        auto helpEvent = static_cast<QHelpEvent*>(event);
        
        // 实例化自定义工具提示Widget
        CustomToolTip tipWidget;
        // 渲染Widget到像素图
        QPixmap tipPixmap(tipWidget.size());
        tipWidget.render(&tipPixmap);

        // 将像素图转为base64编码
        QByteArray pixData;
        QBuffer buffer(&pixData);
        buffer.open(QIODevice::WriteOnly);
        tipPixmap.save(&buffer, "PNG");
        QString base64Pix = pixData.toBase64();

        // 构造HTML嵌入图片
        QString tipHtml = QString("<img src=\"data:image/png;base64,%1\">").arg(base64Pix);

        // 调用QToolTip显示，完全复用其内置逻辑
        QToolTip::showText(helpEvent->globalPos(), tipHtml, this);

        // 阻止默认工具提示处理
        return true;
    }
    return QWidget::event(event);
}

方案优势 #

• 完全复用QToolTip的所有核心逻辑：无需自行实现显示延迟计时器、鼠标移动自动关闭、全局单例管理等复杂代码；
• 自定义内容不受Qt HTML子集限制：可以使用任意QWidget布局、动态绘制的图片、格式化文本；
• 无需额外维护窗口生命周期：所有显示/关闭逻辑由QToolTip原生处理。

注意事项 #

• 若自定义Widget内容过大，渲染像素图可能会有轻微性能损耗，但工具提示场景下一般可忽略；
• 确保自定义Widget调用adjustSize()后再渲染，避免内容截断；
• 若需要适配不同DPI环境，可在渲染前设置Widget的设备像素比。

内容的提问来源于stack exchange，提问作者HiFile.app - best file manager