File indexing completed on 2025-02-16 13:11:52
0001 /* 0002 This file is part of the KDE project 0003 SPDX-FileCopyrightText: 2017 Elvis Angelaccio <elvis.angelaccio@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.1-or-later 0006 */ 0007 0008 #ifndef KTOOLTIPWIDGET_H 0009 #define KTOOLTIPWIDGET_H 0010 0011 #include <kwidgetsaddons_export.h> 0012 0013 #include <QWidget> 0014 #include <memory> 0015 0016 /** 0017 * @class KToolTipWidget ktooltipwidget.h KToolTipWidget 0018 * 0019 * @brief A tooltip that contains a QWidget. 0020 * 0021 * This widget allows to show a tooltip that contains another widget. 0022 * If you only need to show text inside the tooltip, just use QWidget::setToolTip(); 0023 * 0024 * To show the tooltip, you need to choose a position on the screen and also pass a 0025 * transient parent window (recommended on X11 and required on Wayland). 0026 * Use showAt() if you want to show the tooltip from a specific point. 0027 * Use showUnder() if you want to show it under a given rectangle. 0028 * 0029 * You can use a single instance of this class to show as many tooltips as you want. 0030 * 0031 * The tooltip does not take ownership of the content widget if the latter already 0032 * has a parent. While the tooltip is set as parent of the widget (by the layout), 0033 * the old parent is restored when the widget is replaced by another widget 0034 * and also when the tooltip is deleted. 0035 * 0036 * @since 5.30 0037 * @author Elvis Angelaccio <elvis.angelaccio@kde.org> 0038 */ 0039 class KWIDGETSADDONS_EXPORT KToolTipWidget : public QWidget 0040 { 0041 Q_OBJECT 0042 Q_PROPERTY(int hideDelay READ hideDelay WRITE setHideDelay) 0043 0044 public: 0045 explicit KToolTipWidget(QWidget *parent = nullptr); 0046 ~KToolTipWidget() override; 0047 0048 /** 0049 * Show a tooltip containing @p content. The pos() of the tooltip will be @p pos. 0050 * You can call this method multiple times over the same KToolTipWidget instance 0051 * (previously shown widgets will be removed from the tooltip's layout). 0052 * 0053 * @param transientParent will be set as the transient parent of the tooltip. 0054 * @note The transient parent is required to show the tooltip on Wayland platforms. 0055 */ 0056 void showAt(const QPoint &pos, QWidget *content, QWindow *transientParent); 0057 0058 /** 0059 * Show a tooltip containing @p content centered below @p rect. If there is not 0060 * enough space in the screen below @p rect, the tooltip will be shown above 0061 * @p rect, if possible, or at the bottom of the screen otherwise. 0062 * You can call this method multiple times over the same KToolTipWidget instance 0063 * (previously shown widgets will be removed from the tooltip's layout). 0064 * 0065 * Typically @p rect is the visualRect() of a QAbstractItemView: 0066 * @snippet ktooltipwidget_test.cpp show_tooltip_widget 0067 * 0068 * @param transientParent will be set as the transient parent of the tooltip. 0069 * @note The transient parent is required to show the tooltip on Wayland platforms. 0070 */ 0071 void showBelow(const QRect &rect, QWidget *content, QWindow *transientParent); 0072 0073 /** 0074 * @return Delay (in ms) after which hideLater() will hide the tooltip. Default is 500. 0075 * @see hideLater(), setHideDelay() 0076 */ 0077 int hideDelay() const; 0078 0079 public Q_SLOTS: 0080 0081 /** 0082 * Hide the tooltip after a delay of hideDelay() ms (to allow interaction with the tooltip's widget). 0083 * If hideDelay() is 0, this is equivalent to hide(). 0084 * @see hideDelay() 0085 */ 0086 void hideLater(); 0087 0088 /** 0089 * Set after how many ms hideLater() will hide the tooltip. 0090 * @see hideLater(), hideDelay() 0091 */ 0092 void setHideDelay(int delay); 0093 0094 Q_SIGNALS: 0095 /** 0096 * The tooltip has been hidden and the tooltip's widget is no longer visible. 0097 * This signal can be used to delete the tooltip's widget. 0098 */ 0099 void hidden(); 0100 0101 protected: 0102 void enterEvent(QEvent *event) override; 0103 0104 void hideEvent(QHideEvent *) override; 0105 void leaveEvent(QEvent *) override; 0106 void paintEvent(QPaintEvent *event) override; 0107 0108 private: 0109 std::unique_ptr<class KToolTipWidgetPrivate> const d; 0110 0111 Q_DISABLE_COPY(KToolTipWidget) 0112 }; 0113 0114 #endif