KWidgetsAddons

ktooltipwidget.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 2017 Elvis Angelaccio <[email protected]>
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 <[email protected]>
38  */
39 class KWIDGETSADDONS_EXPORT KToolTipWidget : public QWidget
40 {
41  Q_OBJECT
42  Q_PROPERTY(int hideDelay READ hideDelay WRITE setHideDelay)
43 
44 public:
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 
79 public 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 
94 Q_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 
101 protected:
102  void enterEvent(QEvent *event) override;
103 
104  void hideEvent(QHideEvent *) override;
105  void leaveEvent(QEvent *) override;
106  void paintEvent(QPaintEvent *event) override;
107 
108 private:
109  std::unique_ptr<class KToolTipWidgetPrivate> const d;
110 
112 };
113 
114 #endif
Q_PROPERTY(...)
A tooltip that contains a QWidget.
Q_SLOTSQ_SLOTS
virtual void paintEvent(QPaintEvent *event)
virtual void leaveEvent(QEvent *event)
virtual void hideEvent(QHideEvent *event)
virtual void enterEvent(QEvent *event)
Q_SIGNALSQ_SIGNALS
Q_DISABLE_COPY(Class)
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Sep 28 2023 03:59:33 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.