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 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 <freyher@yahoo.com> 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. 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, Yes and No 184 * auto *buttonBox = new QDialogButtonBox({QDialogButtonBox::Yes | QDialogButtonBox::No}, this); 185 * 186 * // Assign the text and icon from KStandardGuiItem::yes()/no() to the buttons in the 187 * // button dialog box 188 * KGuiItem::assign(buttonBox->button(QDialogButtonBox::Yes), KStandardGuiItem::yes()); 189 * KGuiItem::assign(buttonBox->button(QDialogButtonBox::No), KStandardGuiItem::no()); 190 * @endcode 191 */ 192 static void assign(QPushButton *button, const KGuiItem &item); 193 194 private: 195 QSharedDataPointer<class KGuiItemPrivate> d; 196 }; 197 198 #endif 199