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

source code of kwidgetsaddons/src/kguiitem.h