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 */ 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 *) override; 103 void hideEvent(QHideEvent *) override; 104 void leaveEvent(QEvent *) override; 105 void paintEvent(QPaintEvent *event) override; 106 107 private: 108 std::unique_ptr<class KToolTipWidgetPrivate> const d; 109 110 Q_DISABLE_COPY(KToolTipWidget) 111 }; 112 113 #endif 114