KWidgetsAddons

kguiitem.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2001 Holger Freyther <[email protected]>
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 
21 class 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 <[email protected]>
30  * @see KStandardGuiItem
31  */
32 
33 class KWIDGETSADDONS_EXPORT KGuiItem
34 {
35 public:
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; this may contain '&' characters which
90  * denote a keyboard accelerator shortcut that can be used to invoke the GUI item,
91  * e.g. Alt + 'O' for button "&OK". (Note that the '&' is not visible to the user).
92  *
93  * You can get the plain text without the accelerator denoting character '&', by
94  * using plainText().
95  *
96  */
97  QString text() const;
98 
99  /**
100  * Returns the text used by this GUI item after stripping all existing '&'
101  * characters which denote keyboard accelerators.
102  *
103  * @see text()
104  */
105  QString plainText() const;
106 
107  /**
108  * Sets the icon to be shown next to the text of this GUI item.
109  */
110  void setIcon(const QIcon &iconset);
111 
112  /**
113  * Returns the icon used by this GUI item.
114  *
115  * This will return a null QIcon if no icon was previously set for this item.
116  */
117  QIcon icon() const;
118 
119  /**
120  * Sets the name of the icon that will be shown next to the text of this
121  * GUI item. The actual QIcon will be obtained by using QIcon::fromTheme().
122  */
123  void setIconName(const QString &iconName);
124 
125  /**
126  * Returns the name of the icon used by this GUI item.
127  *
128  * This will return an empty string if no icon was previously set for this item.
129  */
130  QString iconName() const;
131 
132  /**
133  * Returns @c true if this GUI item has an icon set for it and @c false otherwise.
134  */
135  bool hasIcon() const;
136 
137  /**
138  * Sets the tooltip text.
139  */
140  void setToolTip(const QString &tooltip);
141 
142  /**
143  * Returns the tooltip used for this GUI item.
144  *
145  * This will return an empty string if no tooltip was previously set for this item.
146  */
147  QString toolTip() const;
148 
149  /**
150  * Sets the WhatThis text.
151  */
152  void setWhatsThis(const QString &whatsThis);
153 
154  /**
155  * Returns the WhatThis text used for this GUI item.
156  *
157  * This will return an empty string if no WhatThis text was previously set for
158  * this item.
159  */
160  QString whatsThis() const;
161 
162  /**
163  * Toggles the enabled property of this GUI item.
164  *
165  * @see QWidget::setEnabled()
166  */
167  void setEnabled(bool enable);
168 
169  /**
170  * Returns @c true if this GUI item is enabled and @c false otherwise.
171  *
172  * @see QWidget::isEnabled()
173  */
174  bool isEnabled() const;
175 
176  /**
177  * A static method that can be used to set the text, icon, tooltip and WhatThis
178  * properties from @p item on @p button.
179  *
180  * @code
181  * // Create a QDialogButtonBox with two buttons, Yes and No
182  * auto *buttonBox = new QDialogButtonBox({QDialogButtonBox::Yes | QDialogButtonBox::No}, this);
183  *
184  * // Assing the text and icon from KStandardGuiItem::yes()/no() to the buttons in the
185  * // button dialog box
186  * KGuiItem::assign(buttonBox->button(QDialogButtonBox::Yes), KStandardGuiItem::yes());
187  * KGuiItem::assign(buttonBox->button(QDialogButtonBox::No), KStandardGuiItem::no());
188  * @endcode
189  */
190  static void assign(QPushButton *button, const KGuiItem &item);
191 
192 private:
194 };
195 
196 #endif
An abstract class for setting the text, icon, tooltip and WhatsThis data on a GUI item (e...
Definition: kguiitem.h:33
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue May 11 2021 22:44:00 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.