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

Provided by KDAB

Privacy Policy
Start learning QML with our Intro Training
Find out more

source code of kwidgetsaddons/src/kcontextualhelpbutton.h