Kirigami2

ContextualHelpButton.qml
1/*
2 SPDX-FileCopyrightText: 2020 Felix Ernst <fe.a.ernst@gmail.com>
3 SPDX-FileCopyrightText: 2024 Nate Graham <nate@kde.org>
4 SPDX-FileCopyrightText: 2024 ivan tkachenko <me@ratijas.tk>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9import QtQuick
10import QtQuick.Controls as QQC2
11import QtQuick.Layouts
12import org.kde.kirigami as Kirigami
13
14/**
15 * @brief An inline help button that shows a tooltip when clicked.
16 *
17 * Use this component when you want to explain details or usage of a feature of
18 * the UI, but the explanation is too long to fit in an inline label, and too
19 * important to put in a hover tooltip and risk the user missing it.
20 *
21 * @image html ContextualHelpButton.png "Example of ContextualHelpButton usage"
22 *
23 * Example usage:
24 * @code{.qml}
25 * import QtQuick.Controls as QQC2
26 * import QtQuick.Layouts
27 * import org.kde.kirigami as Kirigami
28 *
29 * RowLayout {
30 * spacing: Kirigami.Units.smallSpacing
31 *
32 * QQC2.CheckBox {
33 * text: i18n("Allow screen tearing in fullscreen windows")
34 * }
35 *
36 * Kirigami.ContextualHelpButton {
37 * toolTipText: i18n("With most displays, screen tearing reduces latency at the cost of some visual fidelity at high framerates. Note that not all graphics drivers support this setting.")
38 * }
39 * }
40 *
41 * @endcode
42 */
43
44QQC2.ToolButton {
45 id: root
46
47 property alias toolTipText: toolTip.text
48 property bool toolTipVisible: false
49
50 text: qsTr("Show Contextual Help")
51 icon.name: "help-contextual-symbolic"
52 display: QQC2.ToolButton.IconOnly
53
54 onReleased: {
55 toolTip.delay = toolTipVisible ? Kirigami.Units.toolTipDelay : 0;
56 toolTipVisible = !toolTipVisible;
57 }
58 onActiveFocusChanged: {
59 toolTip.delay = Kirigami.Units.toolTipDelay;
60 toolTipVisible = false;
61 }
62 Layout.maximumHeight: parent?.height ?? -1
63
64 QQC2.ToolTip {
65 id: toolTip
66 visible: root.hovered || root.toolTipVisible
67 onVisibleChanged: {
68 if (!visible && root.toolTipVisible) {
69 root.toolTipVisible = false;
70 delay = Kirigami.Units.toolTipDelay;
71 }
72 }
73 timeout: -1 // Don't disappear while the user might still be reading it!
74 }
75
76 MouseArea {
77 anchors.fill: parent
78 hoverEnabled: true
79 cursorShape: Qt.WhatsThisCursor
80 acceptedButtons: Qt.NoButton
81 }
82}
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 19 2024 11:52:23 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.