1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 2024 Felix Ernst <felixernst@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
6*/
7
8#ifndef KCONTEXTUALHELPBUTTON_H
9#define KCONTEXTUALHELPBUTTON_H
10
11#include <kwidgetsaddons_export.h>
12
13#include <QToolButton>
14
15#include <memory>
16
17/*!
18 * \class KContextualHelpButton
19 * \inmodule KWidgetsAddons
20 *
21 * \brief An icon-only button for showing contextually relevant help or explanations.
22 *
23 * KContextualHelpButton allows hiding text of any length behind a small icon-only button. Hovering over the button with a mouse cursor or pressing the button
24 * will show the text. It can contain images and links. It is accessible by keyboard and to screen readers.
25 *
26 * When to Use
27 *
28 * Sometimes users require help or an explanation, even experts. This help should be readily available exactly where and when a user needs it.
29 * A KContextualHelpButton makes clear that inline help is available without really cluttering up the user interface. In that sense it is superior to setting
30 * tooltips which are completely invisible until invoked and therefore easy to miss. Especially for touch users the KContextualHelpButton is preferable.
31 *
32 * When Not to Use
33 *
34 * If the text is important for the user to understand and can be kept very short, place it inline below the control it affects.
35 * If there is no room to put this KContextualHelpButton, use QWidget::setToolTip() for shorter texts and QWidget::SetWhatsThis() for longer text or text that
36 * should contain hyperlinks. If your software is not already using the KXmlGui framework, consider using KToolTipHelper from KXmlGui to make the whatsThis()
37 * help more discoverable.
38 *
39 * How to Use
40 *
41 * The most simple way is creating it like any other button and then setting the help text:
42 *
43 * \code
44 * auto contextualHelpButton = new KContextualHelpButton{this};
45 * contextualHelpButton->setContextualHelpText(xi18nc("@info", "<para>A nicely formatted help text. Notice the 'para' tags at the side!</para>"));
46 * \endcode
47 *
48 * The most common use of this component might be on settings pages which oftentimes use a QFormLayout.
49 * Here is an example on how to use it next to a QCheckBox. Unfortunately we need to make the KContextualHelpButton aware of the QCheckBox here or it will
50 * increase the height of the row in the QFormLayout which might look bad.
51 * The help text in this example contains an image and a working hyperlink:
52 *
53 * \code
54 * auto formLayout = new QFormLayout(this);
55 * auto checkBox = new QCheckBox(i18nc("@option:check", "Check this box"), this);
56 * auto contextualHelpButton = new KContextualHelpButton{
57 * xi18nc("@info",
58 * "<para>A help text containing an icon <img src=':/icon.png'> and a <a href=\"http://www.kde.org\">link</a>.</para>"),
59 * checkBox,
60 * this};
61 * auto rowLayout = new QHBoxLayout{this};
62 * rowLayout->addWidget(checkBox);
63 * rowLayout->addWidget(contextualHelpButton);
64 * formLayout->addRow(i18nc("@title:group", "Row label:"), rowLayout);
65 * \endcode
66 *
67 * This class is meant to be kept somewhat consistent with the QML equivalent which is also called ContextualHelpButton.
68 *
69 * \since 6.2
70 */
71class KWIDGETSADDONS_EXPORT KContextualHelpButton : public QToolButton
72{
73 Q_OBJECT
74 /*!
75 * \value KContextualHelpButton::contextualHelpText
76 */
77 Q_PROPERTY(QString contextualHelpText READ contextualHelpText WRITE setContextualHelpText NOTIFY contextualHelpTextChanged)
78
79public:
80 /*!
81 * \a contextualHelpText The text to show when hovering or clicking this button. Consider formatting this nicely using xi18nc().
82 *
83 * \a heightHintWidget The KContextualHelpButton will report the \a heightHintWidget 's sizeHint().height() as its own sizeHint().height().
84 * This is useful to make sure that adding this KContextualHelpButton to a layout will not increase the layout's total height.
85 *
86 * \a parent The parent widget that gets ownership over the lifetime of this KContextualHelpButton.
87 */
88 explicit KContextualHelpButton(const QString &contextualHelpText, const QWidget *heightHintWidget, QWidget *parent);
89
90 /*! \sa KContextualHelpButton::ContextualHelpButton() */
91 explicit KContextualHelpButton(QWidget *parent = nullptr);
92
93 ~KContextualHelpButton() override;
94
95 /*!
96 * Sets the text to show when hovering or pressing this button. Consider formatting the text nicely using xi18nc().
97 */
98 void setContextualHelpText(const QString &contextualHelpText);
99
100 /*!
101 * Returns the help text which is shown when hovering or pressing this button.
102 */
103 QString contextualHelpText() const;
104
105 /*!
106 * The KContextualHelpButton will report the \a heightHintWidget 's sizeHint().height() as its own sizeHint().height().
107 * This is useful to make sure that adding this KContextualHelpButton to a layout will not increase the layout's total height.
108 */
109 void setHeightHintWidget(const QWidget *heightHintWidget);
110
111 /*! \sa setHeightHintWidget() */
112 const QWidget *heightHintWidget() const;
113
114 QSize sizeHint() const override;
115
116Q_SIGNALS:
117 void contextualHelpTextChanged(const QString &newContextualHelpText);
118
119private:
120 std::unique_ptr<class KContextualHelpButtonPrivate> const d_ptr;
121};
122
123#endif // KCONTEXTUALHELPBUTTON_H
124

source code of kwidgetsaddons/src/kcontextualhelpbutton.h