File indexing completed on 2025-02-02 14:20:02
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 2001 Holger Freyther <freyher@yahoo.com> 0004 0005 based on ideas from Martijn and Simon 0006 0007 SPDX-License-Identifier: LGPL-2.0-only 0008 0009 Many thanks to Simon tronical Hausmann 0010 */ 0011 0012 #ifndef kguiitem_h 0013 #define kguiitem_h 0014 0015 #include <kwidgetsaddons_export.h> 0016 0017 #include <QIcon> 0018 #include <QSharedDataPointer> 0019 #include <QString> 0020 0021 class QPushButton; 0022 0023 /** 0024 * @class KGuiItem kguiitem.h KGuiItem 0025 * 0026 * @short An abstract class for setting the text, icon, tooltip and WhatsThis data 0027 * on a GUI item (e.g.\ a QPushButton). 0028 * 0029 * @author Holger Freyther <freyher@yahoo.com> 0030 * @see KStandardGuiItem 0031 */ 0032 0033 class KWIDGETSADDONS_EXPORT KGuiItem 0034 { 0035 public: 0036 /** 0037 * Constructs an empty KGuiItem. You can use the various methods provided by 0038 * this class to set the text, icon... etc. 0039 */ 0040 KGuiItem(); 0041 0042 // This is explicit because it's easy to get subtle bugs otherwise. The 0043 // icon name, tooltip and whatsthis text get changed behind your back if 0044 // you do 'setButtonFoo( "Bar" );' It gives the wrong impression that you 0045 // just change the text. 0046 /** 0047 * Constructs a KGuiItem with the provided arguments. 0048 * 0049 * @param text the text to use with the GUI item 0050 * @param iconName the name of the icon to display next to the text on the item; 0051 * QIcon::fromTheme() is used to get a icon with that name from 0052 * the icon themes available on the system 0053 * @param tooltip the tooltip to use for this item 0054 * @param whatsThis the text to use for the WhatThis help message 0055 */ 0056 explicit KGuiItem(const QString &text, const QString &iconName = QString(), const QString &toolTip = QString(), const QString &whatsThis = QString()); 0057 /** 0058 * Constructs a KGuiItem with the provided arguments. 0059 * 0060 * @param text the text to use with the GUI item 0061 * @param icon the QIcon object used to get an icon to display next to the text 0062 * on this item 0063 * @param tooltip the tooltip to use for this item 0064 * @param whatsThis the text to use for the WhatThis help message 0065 */ 0066 KGuiItem(const QString &text, const QIcon &icon, const QString &toolTip = QString(), const QString &whatsThis = QString()); 0067 0068 /** 0069 * Constructs a copy of @p other. 0070 */ 0071 KGuiItem(const KGuiItem &other); 0072 0073 /** 0074 * Assigns @p other to this KGuiItem object and returns a reference to this object. 0075 */ 0076 KGuiItem &operator=(const KGuiItem &other); 0077 0078 /** 0079 * Destructor. 0080 */ 0081 ~KGuiItem(); 0082 0083 /** 0084 * Sets the text to use for this GUI item. 0085 */ 0086 void setText(const QString &text); 0087 0088 /** 0089 * Returns the text used by this GUI item. 0090 * 0091 * This may contain '&' characters which denote a keyboard accelerator shortcut that 0092 * can be used to invoke the GUI item, e.g. Alt + 'O' for button "&OK". 0093 * (Note that the '&' is not visible to the user). 0094 * 0095 * You can get the plain text without the accelerator denoting character '&', by 0096 * using plainText(). 0097 * 0098 */ 0099 QString text() const; 0100 0101 /** 0102 * Returns the text used by this GUI item after stripping all existing '&' 0103 * characters which denote keyboard accelerators. 0104 * 0105 * @see text() 0106 */ 0107 QString plainText() const; 0108 0109 /** 0110 * Sets the icon to be shown next to the text of this GUI item. 0111 */ 0112 void setIcon(const QIcon &iconset); 0113 0114 /** 0115 * Returns the icon used by this GUI item. 0116 * 0117 * This will return a null QIcon if no icon was previously set for this item. 0118 */ 0119 QIcon icon() const; 0120 0121 /** 0122 * Sets the name of the icon that will be shown next to the text of this 0123 * GUI item. The actual QIcon will be obtained by using QIcon::fromTheme(). 0124 */ 0125 void setIconName(const QString &iconName); 0126 0127 /** 0128 * Returns the name of the icon used by this GUI item. 0129 * 0130 * This will return an empty string if no icon was previously set for this item. 0131 */ 0132 QString iconName() const; 0133 0134 /** 0135 * Returns @c true if this GUI item has an icon set for it and @c false otherwise. 0136 */ 0137 bool hasIcon() const; 0138 0139 /** 0140 * Sets the tooltip text. 0141 */ 0142 void setToolTip(const QString &tooltip); 0143 0144 /** 0145 * Returns the tooltip used for this GUI item. 0146 * 0147 * This will return an empty string if no tooltip was previously set for this item. 0148 */ 0149 QString toolTip() const; 0150 0151 /** 0152 * Sets the WhatThis text. 0153 */ 0154 void setWhatsThis(const QString &whatsThis); 0155 0156 /** 0157 * Returns the WhatThis text used for this GUI item. 0158 * 0159 * This will return an empty string if no WhatThis text was previously set for 0160 * this item. 0161 */ 0162 QString whatsThis() const; 0163 0164 /** 0165 * Toggles the enabled property of this GUI item. 0166 * 0167 * @see QWidget::setEnabled() 0168 */ 0169 void setEnabled(bool enable); 0170 0171 /** 0172 * Returns @c true if this GUI item is enabled and @c false otherwise. 0173 * 0174 * @see QWidget::isEnabled() 0175 */ 0176 bool isEnabled() const; 0177 0178 /** 0179 * A static method that can be used to set the text, icon, tooltip and WhatThis 0180 * properties from @p item on @p button. 0181 * 0182 * @code 0183 * // Create a QDialogButtonBox with two buttons, of Yes and No standard type 0184 * auto *buttonBox = new QDialogButtonBox({QDialogButtonBox::Yes | QDialogButtonBox::No}, this); 0185 * 0186 * // Assign the text and icon from KStandardGuiItem::quit()/continue() to the buttons in the 0187 * // button dialog box 0188 * KGuiItem::assign(buttonBox->button(QDialogButtonBox::Yes), KStandardGuiItem::quit()); 0189 * KGuiItem::assign(buttonBox->button(QDialogButtonBox::No), KStandardGuiItem::continue()); 0190 * @endcode 0191 */ 0192 static void assign(QPushButton *button, const KGuiItem &item); 0193 0194 private: 0195 QSharedDataPointer<class KGuiItemPrivate> d; 0196 }; 0197 0198 #endif