1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 2021 Felix Ernst <fe.a.ernst@gmail.com>
4
5 SPDX-License-Identifier: LGPL-2.1-or-later OR BSD-2-Clause
6*/
7
8#ifndef KTOOLTIPHELPER_H
9#define KTOOLTIPHELPER_H
10
11#include <kxmlgui_export.h>
12
13#include <QObject>
14
15#include <memory>
16
17class KToolTipHelperPrivate;
18
19/**
20 * @class KToolTipHelper ktooltiphelper.h KToolTipHelper
21 *
22 * @short An event filter used to enhance tooltips
23 *
24 * Example:
25 * Without this class, a tooltip of a QToolButton of a "New" action will read something like
26 * "New File". Using this class, the tooltip can be enhanced to read something like
27 * "New File (Ctrl+N)" and in the next line smaller "Press Shift for help.".
28 * Pressing Shift will open the "What's This" context help for that widget. If a hyperlink in
29 * that help is clicked, the corresponding event will also be filtered by this class and open
30 * the linked location.
31 *
32 * The extra text added to tooltips is only shown when available and where it makes sense. If a
33 * QToolButton has no associated shortcut and an empty QWidget::whatsThis(), this class won't
34 * tamper with the requested tooltip at all.
35 *
36 * This class also activates tooltips for actions in QMenus but only when it makes sense like when
37 * the tooltip isn't equal to the already displayed text.
38 *
39 * If you want the "Press Shift for help." line to be displayed for a widget that has whatsThis()
40 * but no toolTip() take a look at KToolTipHelper::whatsThisHintOnly().
41 *
42 * The enhanced tooltips can be enabled at any time after the QApplication was constructed with
43 * \code
44 * qApp->installEventFilter(KToolTipHelper::instance());
45 * \endcode
46 * Therefore, to de-activate them you can call
47 * \code
48 * qApp->removeEventFilter(KToolTipHelper::instance());
49 * \endcode
50 * any time later.
51 *
52 * If you want KToolTipHelper to not tamper with certain QEvents, e.g. you want to handle some
53 * tooltips differently or you want to change what happens when a QWhatsThisClickedEvent is
54 * processed, first remove KToolTipHelper as an event filter just like in the line of code above.
55 * Then create your own custom EventFilter that handles those QEvents differently and for all
56 * cases that you don't want to handle differently call
57 * \code
58 * return KToolTipHelper::instance()->eventFilter(watched, event);
59 * \endcode
60 *
61 * KMainWindow will have this EventFilter installed by default from framework version 5.84 onward
62 * so if you want to opt out of that, remove the EventFilter in the constructor of your MainWindow
63 * class inheriting from KMainWindow.
64 *
65 * @see QToolTip
66 * @since 5.84
67 */
68class KXMLGUI_EXPORT KToolTipHelper : public QObject
69{
70 Q_OBJECT
71 Q_DISABLE_COPY(KToolTipHelper)
72
73public:
74 static KToolTipHelper *instance();
75
76 /**
77 * Filters QEvent::ToolTip if an enhanced tooltip is available for the widget.
78 * Filters the QEvent::KeyPress that is used to expand an expandable tooltip.
79 * Filters QEvent::WhatsThisClicked so hyperlinks in whatsThis() texts work.
80 *
81 * @see QObject::eventFilter()
82 * @see QHelpEvent
83 */
84 virtual bool eventFilter(QObject *watched, QEvent *event) override;
85
86 /**
87 * Use this to have a widget show "Press Shift for help." as its tooltip.
88 * \code
89 * widget->setToolTip(KToolTipHelper::whatsThisHintOnly());
90 * \endcode
91 * KToolTipHelper won't show that tooltip if the widget's whatsThis() is empty.
92 *
93 * @return a QString that is interpreted by this class to show the expected tooltip.
94 */
95 static const QString whatsThisHintOnly();
96
97private:
98 KXMLGUI_NO_EXPORT explicit KToolTipHelper(QObject *parent);
99
100 KXMLGUI_NO_EXPORT ~KToolTipHelper() override;
101
102private:
103 std::unique_ptr<KToolTipHelperPrivate> const d;
104
105 friend class KToolTipHelperPrivate;
106};
107
108#endif // KTOOLTIPHELPER_H
109

source code of kxmlgui/src/ktooltiphelper.h