File indexing completed on 2025-02-16 13:11:52
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 2007-2009 Urs Wolfer <uwolfer@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef KTITLEWIDGET_H 0009 #define KTITLEWIDGET_H 0010 0011 #include <kwidgetsaddons_export.h> 0012 0013 #include <QWidget> 0014 #include <memory> 0015 0016 /** 0017 * @class KTitleWidget ktitlewidget.h KTitleWidget 0018 * 0019 * @short Standard title widget. 0020 * 0021 * This class provides a widget often used for dialog titles. 0022 * \image html ktitlewidget.png "KTitleWidget with title and icon" 0023 * 0024 * KTitleWidget uses the general application font at 1.4 times its size to 0025 * style the text. This is a visual change from 4.x. 0026 * 0027 * @section Usage 0028 * KTitleWidget is very simple to use. You can either use its default text 0029 * (and pixmap) properties or display your own widgets in the title widget. 0030 * 0031 * A title text with a right-aligned pixmap: 0032 * @code 0033 KTitleWidget *titleWidget = new KTitleWidget(this); 0034 titleWidget->setText(i18n("Title")); 0035 titleWidget->setIcon(QIcon::fromTheme("screen")); 0036 * @endcode 0037 * 0038 * Use it with an own widget: 0039 * @code 0040 KTitleWidget *checkboxTitleWidget = new KTitleWidget(this); 0041 0042 QWidget *checkBoxTitleMainWidget = new QWidget(this); 0043 QVBoxLayout *titleLayout = new QVBoxLayout(checkBoxTitleMainWidget); 0044 titleLayout->setContentsMargins(6, 6, 6, 6); 0045 0046 QCheckBox *checkBox = new QCheckBox("Text Checkbox", checkBoxTitleMainWidget); 0047 titleLayout->addWidget(checkBox); 0048 0049 checkboxTitleWidget->setWidget(checkBoxTitleMainWidget); 0050 * @endcode 0051 * 0052 * @see KPageView 0053 * @author Urs Wolfer \<uwolfer @ kde.org\> 0054 */ 0055 class KWIDGETSADDONS_EXPORT KTitleWidget : public QWidget 0056 { 0057 Q_OBJECT 0058 Q_PROPERTY(QString text READ text WRITE setText) 0059 Q_PROPERTY(QString comment READ comment WRITE setComment) 0060 /// @since 5.72 0061 Q_PROPERTY(QIcon icon READ icon WRITE setIcon) 0062 /// @since 5.72 0063 Q_PROPERTY(QSize iconSize READ iconSize WRITE setIconSize) 0064 #if KWIDGETSADDONS_BUILD_DEPRECATED_SINCE(5, 72) 0065 /// @deprecated Since 5.72, use property icon instead 0066 Q_PROPERTY(QPixmap pixmap READ pixmap WRITE setPixmap) 0067 #endif 0068 Q_PROPERTY(int autoHideTimeout READ autoHideTimeout WRITE setAutoHideTimeout) 0069 0070 public: 0071 /** 0072 * Possible title pixmap alignments. 0073 * 0074 * @li ImageLeft: Display the pixmap left 0075 * @li ImageRight: Display the pixmap right (default) 0076 */ 0077 enum ImageAlignment { 0078 ImageLeft, /**< Display the pixmap on the left */ 0079 ImageRight, /**< Display the pixmap on the right */ 0080 }; 0081 Q_ENUM(ImageAlignment) 0082 0083 /** 0084 * Comment message types 0085 */ 0086 enum MessageType { 0087 PlainMessage, /**< Normal comment */ 0088 InfoMessage, /**< Information the user should be alerted to */ 0089 WarningMessage, /**< A warning the user should be alerted to */ 0090 ErrorMessage, /**< An error message */ 0091 }; 0092 0093 /** 0094 * Constructs a title widget. 0095 */ 0096 explicit KTitleWidget(QWidget *parent = nullptr); 0097 0098 ~KTitleWidget() override; 0099 0100 /** 0101 * @param widget Widget displayed on the title widget. 0102 */ 0103 void setWidget(QWidget *widget); 0104 0105 /** 0106 * @return the text displayed in the title 0107 * @see setText() 0108 */ 0109 QString text() const; 0110 0111 /** 0112 * @return the text displayed in the comment below the title, if any 0113 * @see setComment() 0114 */ 0115 QString comment() const; 0116 0117 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 72) 0118 /** 0119 * @return the pixmap displayed in the title 0120 * @see setPixmap() 0121 * @deprecated Since 5.72, use icon() 0122 */ 0123 KWIDGETSADDONS_DEPRECATED_VERSION(5, 72, "Use KTitleWidget::icon()") 0124 const QPixmap *pixmap() const; 0125 #endif 0126 0127 /** 0128 * @return the icon displayed in the title 0129 * @see setIcon() 0130 * 0131 * @since 5.72 0132 */ 0133 QIcon icon() const; 0134 0135 /** 0136 * @return the size of the icon displayed in the title 0137 * @see setIconSize() 0138 * 0139 * @since 5.72 0140 */ 0141 QSize iconSize() const; 0142 0143 /** 0144 * Sets this label's buddy to buddy. 0145 * When the user presses the shortcut key indicated by the label in this 0146 * title widget, the keyboard focus is transferred to the label's buddy 0147 * widget. 0148 * @param buddy the widget to activate when the shortcut key is activated 0149 */ 0150 void setBuddy(QWidget *buddy); 0151 0152 /** 0153 * Get the current timeout value in milliseconds 0154 * @return timeout value in msecs 0155 */ 0156 int autoHideTimeout() const; 0157 0158 /** 0159 * @return The level of this title: it influences the font size following the guidelines in 0160 * the <a href="https://develop.kde.org/hig/style/typography/">KDE HIG</a>. 0161 * It also corresponds to the level api of Kirigami Heading for QML applications 0162 * @since 5.53 0163 */ 0164 int level(); 0165 0166 public Q_SLOTS: 0167 /** 0168 * @param text Text displayed on the label. It can either be plain text or rich text. If it 0169 * is plain text, the text is displayed as a bold title text. 0170 * @param alignment Alignment of the text. Default is left and vertical centered. 0171 * @see text() 0172 */ 0173 void setText(const QString &text, Qt::Alignment alignment = Qt::AlignLeft | Qt::AlignVCenter); 0174 /** 0175 * @param text Text displayed on the label. It can either be plain text or rich text. If it 0176 * is plain text, the text is displayed as a bold title text. 0177 * @param type The sort of message it is; will also set the icon accordingly 0178 * @see text() 0179 */ 0180 void setText(const QString &text, MessageType type); 0181 0182 /** 0183 * @param comment Text displayed beneath the main title as a comment. 0184 * It can either be plain text or rich text. 0185 * @param type The sort of message it is. 0186 * @see comment() 0187 */ 0188 void setComment(const QString &comment, MessageType type = PlainMessage); 0189 0190 /** 0191 * Set the icon to display in the header. 0192 * @param icon the icon to display in the header. 0193 * @param alignment alignment of the icon (default is right aligned). 0194 * @since 5.63 0195 */ 0196 void setIcon(const QIcon &icon, ImageAlignment alignment = ImageRight); 0197 0198 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 72) 0199 /** 0200 * Sets the icon to the @p pixmap and also the icon size to the size of the @p pixmap. 0201 * @param pixmap Pixmap displayed in the header. The pixmap is by default right, but 0202 * @param alignment can be used to display it also left. 0203 * @see pixmap() 0204 * @deprecated Since 5.72, use setIcon(const QIcon &, ImageAlignment) 0205 */ 0206 KWIDGETSADDONS_DEPRECATED_VERSION(5, 72, "Use KTitleWidget::setIcon(const QIcon &, ImageAlignment)") 0207 void setPixmap(const QPixmap &pixmap, ImageAlignment alignment = ImageRight); 0208 #endif 0209 0210 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 63) 0211 /** 0212 * @param icon name of the icon to display in the header. The pixmap is by default right, but 0213 * @param alignment can be used to display it also left. 0214 * @see pixmap() 0215 * @deprecated since 5.63 use setIcon() instead 0216 */ 0217 KWIDGETSADDONS_DEPRECATED_VERSION(5, 63, "Use KTitleWidget::setIcon(const QIcon &, ImageAlignment)") 0218 void setPixmap(const QString &icon, ImageAlignment alignment = ImageRight); 0219 #endif 0220 0221 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 63) 0222 /** 0223 * @param icon the icon to display in the header. The pixmap is by default right, but 0224 * @param alignment can be used to display it also left. 0225 * @see pixmap() 0226 * @deprecated since 5.63 use setIcon() instead 0227 */ 0228 KWIDGETSADDONS_DEPRECATED_VERSION(5, 63, "Use KTitleWidget::setIcon(const QIcon &, ImageAlignment)") 0229 void setPixmap(const QIcon &icon, ImageAlignment alignment = ImageRight); 0230 #endif 0231 0232 /** 0233 * @param type the type of message icon to display in the header 0234 * @param alignment alignment of the icon (default is right aligned). 0235 * @see icon() 0236 * @since 5.72 0237 */ 0238 void setIcon(MessageType type, ImageAlignment alignment = ImageRight); 0239 0240 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 72) 0241 /** 0242 * @param type the type of message icon to display in the header. The pixmap is by default right, but 0243 * @param alignment can be used to display it also left. 0244 * @see pixmap() 0245 * @deprecated Since 5.72 use setIcon(MessageType, ImageAlignment) instead 0246 */ 0247 KWIDGETSADDONS_DEPRECATED_VERSION(5, 72, "Use KTitleWidget::setIcon(MessageType, ImageAlignment)") 0248 void setPixmap(MessageType type, ImageAlignment alignment = ImageRight); 0249 #endif 0250 0251 /** 0252 * Set the size of the icon to display in the header. 0253 * @param iconSize the size of the icon, or an invalid QSize to reset to the default 0254 * 0255 * The default size is defined by the GUI style and its value for QStyle::PM_MessageBoxIconSize. 0256 * 0257 * @since 5.72 0258 */ 0259 void setIconSize(const QSize &iconSize); 0260 0261 /** 0262 * Set the autohide timeout of the label 0263 * Set value to 0 to disable autohide, which is the default. 0264 * @param msecs timeout value in milliseconds 0265 */ 0266 void setAutoHideTimeout(int msecs); 0267 0268 /** 0269 * Sets the level of this title, similar to HTML's h1 h2 h3... 0270 * Follows the <a href="https://develop.kde.org/hig/style/typography/">KDE HIG</a>. 0271 * @param level the level of the title, 1 is the biggest font and most important, descending 0272 * @since 5.53 0273 */ 0274 void setLevel(int level); 0275 0276 protected: 0277 void changeEvent(QEvent *e) override; 0278 void showEvent(QShowEvent *event) override; 0279 bool eventFilter(QObject *object, QEvent *event) override; 0280 0281 private: 0282 std::unique_ptr<class KTitleWidgetPrivate> const d; 0283 0284 Q_DISABLE_COPY(KTitleWidget) 0285 }; 0286 0287 #endif