1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 2017 Elvis Angelaccio <elvis.angelaccio@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.1-or-later
6*/
7
8#ifndef KTOOLTIPWIDGET_H
9#define KTOOLTIPWIDGET_H
10
11#include <kwidgetsaddons_export.h>
12
13#include <QWidget>
14#include <memory>
15
16/**
17 * @class KToolTipWidget ktooltipwidget.h KToolTipWidget
18 *
19 * @brief A tooltip that contains a QWidget.
20 *
21 * This widget allows to show a tooltip that contains another widget.
22 * If you only need to show text inside the tooltip, just use QWidget::setToolTip();
23 *
24 * To show the tooltip, you need to choose a position on the screen and also pass a
25 * transient parent window (recommended on X11 and required on Wayland).
26 * Use showAt() if you want to show the tooltip from a specific point.
27 * Use showUnder() if you want to show it under a given rectangle.
28 *
29 * You can use a single instance of this class to show as many tooltips as you want.
30 *
31 * The tooltip does not take ownership of the content widget if the latter already
32 * has a parent. While the tooltip is set as parent of the widget (by the layout),
33 * the old parent is restored when the widget is replaced by another widget
34 * and also when the tooltip is deleted.
35 *
36 * @since 5.30
37 * @author Elvis Angelaccio <elvis.angelaccio@kde.org>
38 */
39class KWIDGETSADDONS_EXPORT KToolTipWidget : public QWidget
40{
41 Q_OBJECT
42 Q_PROPERTY(int hideDelay READ hideDelay WRITE setHideDelay)
43
44public:
45 explicit KToolTipWidget(QWidget *parent = nullptr);
46 ~KToolTipWidget() override;
47
48 /**
49 * Show a tooltip containing @p content. The pos() of the tooltip will be @p pos.
50 * You can call this method multiple times over the same KToolTipWidget instance
51 * (previously shown widgets will be removed from the tooltip's layout).
52 *
53 * @param transientParent will be set as the transient parent of the tooltip.
54 * @note The transient parent is required to show the tooltip on Wayland platforms.
55 */
56 void showAt(const QPoint &pos, QWidget *content, QWindow *transientParent);
57
58 /**
59 * Show a tooltip containing @p content centered below @p rect. If there is not
60 * enough space in the screen below @p rect, the tooltip will be shown above
61 * @p rect, if possible, or at the bottom of the screen otherwise.
62 * You can call this method multiple times over the same KToolTipWidget instance
63 * (previously shown widgets will be removed from the tooltip's layout).
64 *
65 * Typically @p rect is the visualRect() of a QAbstractItemView:
66 * @snippet ktooltipwidget_test.cpp show_tooltip_widget
67 *
68 * @param transientParent will be set as the transient parent of the tooltip.
69 * @note The transient parent is required to show the tooltip on Wayland platforms.
70 */
71 void showBelow(const QRect &rect, QWidget *content, QWindow *transientParent);
72
73 /**
74 * @return Delay (in ms) after which hideLater() will hide the tooltip. Default is 500.
75 * @see hideLater(), setHideDelay()
76 */
77 int hideDelay() const;
78
79public Q_SLOTS:
80
81 /**
82 * Hide the tooltip after a delay of hideDelay() ms (to allow interaction with the tooltip's widget).
83 * If hideDelay() is 0, this is equivalent to hide().
84 * @see hideDelay()
85 */
86 void hideLater();
87
88 /**
89 * Set after how many ms hideLater() will hide the tooltip.
90 * @see hideLater(), hideDelay()
91 */
92 void setHideDelay(int delay);
93
94Q_SIGNALS:
95 /**
96 * The tooltip has been hidden and the tooltip's widget is no longer visible.
97 * This signal can be used to delete the tooltip's widget.
98 */
99 void hidden();
100
101protected:
102 void enterEvent(QEnterEvent *event) override;
103 void hideEvent(QHideEvent *) override;
104 void leaveEvent(QEvent *) override;
105 void paintEvent(QPaintEvent *event) override;
106
107private:
108 std::unique_ptr<class KToolTipWidgetPrivate> const d;
109
110 Q_DISABLE_COPY(KToolTipWidget)
111};
112
113#endif
114

source code of kwidgetsaddons/src/ktooltipwidget.h