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
18 *
19 * \brief A tooltip that contains a QWidget.
20 *
21 * This widget allows to show a tooltip that contains another widget.
22 *
23 * If you only need to show text inside the tooltip, just use QWidget::setToolTip();
24 *
25 * To show the tooltip, you need to choose a position on the screen and also pass a
26 * transient parent window (recommended on X11 and required on Wayland).
27 * Use showAt() if you want to show the tooltip from a specific point.
28 * Use showUnder() if you want to show it under a given rectangle.
29 *
30 * You can use a single instance of this class to show as many tooltips as you want.
31 *
32 * The tooltip does not take ownership of the content widget if the latter already
33 * has a parent. While the tooltip is set as parent of the widget (by the layout),
34 * the old parent is restored when the widget is replaced by another widget
35 * and also when the tooltip is deleted.
36 *
37 * \since 5.30
38 */
39class KWIDGETSADDONS_EXPORT KToolTipWidget : public QWidget
40{
41 Q_OBJECT
42
43 /*!
44 * \property KToolTipWidget::hideDelay
45 */
46 Q_PROPERTY(int hideDelay READ hideDelay WRITE setHideDelay)
47
48public:
49 /*!
50 *
51 */
52 explicit KToolTipWidget(QWidget *parent = nullptr);
53 ~KToolTipWidget() override;
54
55 /*!
56 * Show a tooltip containing \a content. The pos() of the tooltip will be \a pos.
57 *
58 * You can call this method multiple times over the same KToolTipWidget instance
59 * (previously shown widgets will be removed from the tooltip's layout).
60 *
61 * \a transientParent will be set as the transient parent of the tooltip.
62 *
63 * \note The transient parent is required to show the tooltip on Wayland platforms.
64 */
65 void showAt(const QPoint &pos, QWidget *content, QWindow *transientParent);
66
67 /*!
68 * Show a tooltip containing \a content centered below \a rect. If there is not
69 * enough space in the screen below \a rect, the tooltip will be shown above
70 * \a rect, if possible, or at the bottom of the screen otherwise.
71 * You can call this method multiple times over the same KToolTipWidget instance
72 * (previously shown widgets will be removed from the tooltip's layout).
73 *
74 * Typically \a rect is the visualRect() of a QAbstractItemView:
75 *
76 * TODO qdoc
77 * @snippet ktooltipwidget_test.cpp show_tooltip_widget
78 *
79 * \a transientParent will be set as the transient parent of the tooltip.
80 *
81 * \note The transient parent is required to show the tooltip on Wayland platforms.
82 */
83 void showBelow(const QRect &rect, QWidget *content, QWindow *transientParent);
84
85 /*!
86 * Returns the delay (in ms) after which hideLater() will hide the tooltip.
87 *
88 * Default is 500.
89 * \sa hideLater(), setHideDelay()
90 */
91 int hideDelay() const;
92
93public Q_SLOTS:
94
95 /*!
96 * Hide the tooltip after a delay of hideDelay() ms (to allow interaction with the tooltip's widget).
97 *
98 * If hideDelay() is 0, this is equivalent to hide().
99 * \sa hideDelay()
100 */
101 void hideLater();
102
103 /*!
104 * Set after how many ms hideLater() will hide the tooltip.
105 * \sa hideLater(), hideDelay()
106 */
107 void setHideDelay(int delay);
108
109Q_SIGNALS:
110 /*!
111 * The tooltip has been hidden and the tooltip's widget is no longer visible.
112 *
113 * This signal can be used to delete the tooltip's widget.
114 */
115 void hidden();
116
117protected:
118 void enterEvent(QEnterEvent *event) override;
119 void hideEvent(QHideEvent *) override;
120 void leaveEvent(QEvent *) override;
121 void paintEvent(QPaintEvent *event) override;
122
123private:
124 std::unique_ptr<class KToolTipWidgetPrivate> const d;
125
126 Q_DISABLE_COPY(KToolTipWidget)
127};
128
129#endif
130

source code of kwidgetsaddons/src/ktooltipwidget.h