1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2001 Holger Freyther <freyher@yahoo.com>
4
5 based on ideas from Martijn and Simon
6
7 SPDX-License-Identifier: LGPL-2.0-only
8
9 Many thanks to Simon tronical Hausmann
10*/
11
12#ifndef kguiitem_h
13#define kguiitem_h
14
15#include <kwidgetsaddons_export.h>
16
17#include <QIcon>
18#include <QSharedDataPointer>
19#include <QString>
20
21class QPushButton;
22
23/*!
24 * \class KGuiItem
25 * \inmodule KWidgetsAddons
26 *
27 * \brief An abstract class for setting the text, icon, tooltip and WhatsThis data
28 * on a GUI item (e.g.\ a QPushButton).
29 *
30 * \sa KStandardGuiItem
31 */
32class KWIDGETSADDONS_EXPORT KGuiItem
33{
34public:
35 /*!
36 * Constructs an empty KGuiItem. You can use the various methods provided by
37 * this class to set the text, icon... etc.
38 */
39 KGuiItem();
40
41 // This is explicit because it's easy to get subtle bugs otherwise. The
42 // icon name, tooltip and whatsthis text get changed behind your back if
43 // you do 'setButtonFoo( "Bar" );' It gives the wrong impression that you
44 // just change the text.
45 /*!
46 * Constructs a KGuiItem with the provided arguments.
47 *
48 * \a text the text to use with the GUI item
49 *
50 * \a iconName the name of the icon to display next to the text on the item;
51 * QIcon::fromTheme() is used to get a icon with that name from
52 * the icon themes available on the system
53 *
54 * \a tooltip the tooltip to use for this item
55 *
56 * \a whatsThis the text to use for the WhatThis help message
57 */
58 explicit KGuiItem(const QString &text, const QString &iconName = QString(), const QString &toolTip = QString(), const QString &whatsThis = QString());
59
60 /*!
61 * Constructs a KGuiItem with the provided arguments.
62 *
63 * \a text the text to use with the GUI item
64 *
65 * \a icon the QIcon object used to get an icon to display next to the text
66 * on this item
67 *
68 * \a toolTip the tooltip to use for this item
69 *
70 * \a whatsThis the text to use for the WhatThis help message
71 */
72 KGuiItem(const QString &text, const QIcon &icon, const QString &toolTip = QString(), const QString &whatsThis = QString());
73
74 KGuiItem(const KGuiItem &other);
75
76 KGuiItem &operator=(const KGuiItem &other);
77
78 ~KGuiItem();
79
80 /*!
81 * Sets the text to use for this GUI item.
82 */
83 void setText(const QString &text);
84
85 /*!
86 * Returns the text used by this GUI item.
87 *
88 * This may contain '&' characters which denote a keyboard accelerator shortcut that
89 * can be used to invoke the GUI item, e.g. Alt + 'O' for button "&OK".
90 * (Note that the '&' is not visible to the user).
91 *
92 * You can get the plain text without the accelerator denoting character '&', by
93 * using plainText().
94 *
95 */
96 QString text() const;
97
98 /*!
99 * Returns the text used by this GUI item after stripping all existing '&'
100 * characters which denote keyboard accelerators.
101 *
102 * \sa text()
103 */
104 QString plainText() const;
105
106 /*!
107 * Sets the icon to be shown next to the text of this GUI item.
108 */
109 void setIcon(const QIcon &iconset);
110
111 /*!
112 * Returns the icon used by this GUI item.
113 *
114 * This will return a null QIcon if no icon was previously set for this item.
115 */
116 QIcon icon() const;
117
118 /*!
119 * Sets the name of the icon that will be shown next to the text of this
120 * GUI item. The actual QIcon will be obtained by using QIcon::fromTheme().
121 */
122 void setIconName(const QString &iconName);
123
124 /*!
125 * Returns the name of the icon used by this GUI item.
126 *
127 * This will return an empty string if no icon was previously set for this item.
128 */
129 QString iconName() const;
130
131 /*!
132 * Returns \c true if this GUI item has an icon set for it and \c false otherwise.
133 */
134 bool hasIcon() const;
135
136 /*!
137 * Sets the tooltip text.
138 */
139 void setToolTip(const QString &tooltip);
140
141 /*!
142 * Returns the tooltip used for this GUI item.
143 *
144 * This will return an empty string if no tooltip was previously set for this item.
145 */
146 QString toolTip() const;
147
148 /*!
149 * Sets the WhatThis text.
150 */
151 void setWhatsThis(const QString &whatsThis);
152
153 /*!
154 * Returns the WhatThis text used for this GUI item.
155 *
156 * This will return an empty string if no WhatThis text was previously set for
157 * this item.
158 */
159 QString whatsThis() const;
160
161 /*!
162 * Toggles the enabled property of this GUI item.
163 *
164 * \sa QWidget::setEnabled()
165 */
166 void setEnabled(bool enable);
167
168 /*!
169 * Returns \c true if this GUI item is enabled and \c false otherwise.
170 *
171 * \sa QWidget::isEnabled()
172 */
173 bool isEnabled() const;
174
175 /*!
176 * A static method that can be used to set the text, icon, tooltip and WhatThis
177 * properties from \a item on \a button.
178 *
179 * \code
180 * // Create a QDialogButtonBox with two buttons, of Yes and No standard type
181 * auto *buttonBox = new QDialogButtonBox({QDialogButtonBox::Yes | QDialogButtonBox::No}, this);
182 *
183 * // Assign the text and icon from KStandardGuiItem::quit()/continue() to the buttons in the
184 * // button dialog box
185 * KGuiItem::assign(buttonBox->button(QDialogButtonBox::Yes), KStandardGuiItem::quit());
186 * KGuiItem::assign(buttonBox->button(QDialogButtonBox::No), KStandardGuiItem::continue());
187 * \endcode
188 */
189 static void assign(QPushButton *button, const KGuiItem &item);
190
191private:
192 QSharedDataPointer<class KGuiItemPrivate> d;
193};
194
195#endif
196

source code of kwidgetsaddons/src/kguiitem.h