1 /* 2 This file is part of the KDE libraries 3 SPDX-FileCopyrightText: 2007-2009 Urs Wolfer <uwolfer@kde.org> 4 5 SPDX-License-Identifier: LGPL-2.0-or-later 6 */ 7 8 #ifndef KTITLEWIDGET_H 9 #define KTITLEWIDGET_H 10 11 #include <kwidgetsaddons_export.h> 12 13 #include <QWidget> 14 #include <memory> 15 16 /** 17 * @class KTitleWidget ktitlewidget.h KTitleWidget 18 * 19 * @short Standard title widget. 20 * 21 * This class provides a widget often used for dialog titles. 22 * \image html ktitlewidget.png "KTitleWidget with title and icon" 23 * 24 * KTitleWidget uses the general application font at 1.4 times its size to 25 * style the text. This is a visual change from 4.x. 26 * 27 * @section Usage 28 * KTitleWidget is very simple to use. You can either use its default text 29 * (and pixmap) properties or display your own widgets in the title widget. 30 * 31 * A title text with a right-aligned pixmap: 32 * @code 33 KTitleWidget *titleWidget = new KTitleWidget(this); 34 titleWidget->setText(i18n("Title")); 35 titleWidget->setIcon(QIcon::fromTheme("screen")); 36 * @endcode 37 * 38 * Use it with an own widget: 39 * @code 40 KTitleWidget *checkboxTitleWidget = new KTitleWidget(this); 41 42 QWidget *checkBoxTitleMainWidget = new QWidget(this); 43 QVBoxLayout *titleLayout = new QVBoxLayout(checkBoxTitleMainWidget); 44 titleLayout->setContentsMargins(6, 6, 6, 6); 45 46 QCheckBox *checkBox = new QCheckBox("Text Checkbox", checkBoxTitleMainWidget); 47 titleLayout->addWidget(checkBox); 48 49 checkboxTitleWidget->setWidget(checkBoxTitleMainWidget); 50 * @endcode 51 * 52 * @see KPageView 53 * @author Urs Wolfer \<uwolfer @ kde.org\> 54 */ 55 class KWIDGETSADDONS_EXPORT KTitleWidget : public QWidget 56 { 57 Q_OBJECT 58 Q_PROPERTY(QString text READ text WRITE setText) 59 Q_PROPERTY(QString comment READ comment WRITE setComment) 60 /// @since 5.72 61 Q_PROPERTY(QIcon icon READ icon WRITE setIcon) 62 /// @since 5.72 63 Q_PROPERTY(QSize iconSize READ iconSize WRITE setIconSize) 64 #if KWIDGETSADDONS_BUILD_DEPRECATED_SINCE(5, 72) 65 /// @deprecated Since 5.72, use property icon instead 66 Q_PROPERTY(QPixmap pixmap READ pixmap WRITE setPixmap) 67 #endif 68 Q_PROPERTY(int autoHideTimeout READ autoHideTimeout WRITE setAutoHideTimeout) 69 70 public: 71 /** 72 * Possible title pixmap alignments. 73 * 74 * @li ImageLeft: Display the pixmap left 75 * @li ImageRight: Display the pixmap right (default) 76 */ 77 enum ImageAlignment { 78 ImageLeft, /**< Display the pixmap on the left */ 79 ImageRight, /**< Display the pixmap on the right */ 80 }; 81 Q_ENUM(ImageAlignment) 82 83 /** 84 * Comment message types 85 */ 86 enum MessageType { 87 PlainMessage, /**< Normal comment */ 88 InfoMessage, /**< Information the user should be alerted to */ 89 WarningMessage, /**< A warning the user should be alerted to */ 90 ErrorMessage, /**< An error message */ 91 }; 92 93 /** 94 * Constructs a title widget. 95 */ 96 explicit KTitleWidget(QWidget *parent = nullptr); 97 98 ~KTitleWidget() override; 99 100 /** 101 * @param widget Widget displayed on the title widget. 102 */ 103 void setWidget(QWidget *widget); 104 105 /** 106 * @return the text displayed in the title 107 * @see setText() 108 */ 109 QString text() const; 110 111 /** 112 * @return the text displayed in the comment below the title, if any 113 * @see setComment() 114 */ 115 QString comment() const; 116 117 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 72) 118 /** 119 * @return the pixmap displayed in the title 120 * @see setPixmap() 121 * @deprecated Since 5.72, use icon() 122 */ 123 KWIDGETSADDONS_DEPRECATED_VERSION(5, 72, "Use KTitleWidget::icon()") 124 const QPixmap *pixmap() const; 125 #endif 126 127 /** 128 * @return the icon displayed in the title 129 * @see setIcon() 130 * 131 * @since 5.72 132 */ 133 QIcon icon() const; 134 135 /** 136 * @return the size of the icon displayed in the title 137 * @see setIconSize() 138 * 139 * @since 5.72 140 */ 141 QSize iconSize() const; 142 143 /** 144 * Sets this label's buddy to buddy. 145 * When the user presses the shortcut key indicated by the label in this 146 * title widget, the keyboard focus is transferred to the label's buddy 147 * widget. 148 * @param buddy the widget to activate when the shortcut key is activated 149 */ 150 void setBuddy(QWidget *buddy); 151 152 /** 153 * Get the current timeout value in milliseconds 154 * @return timeout value in msecs 155 */ 156 int autoHideTimeout() const; 157 158 /** 159 * @return The level of this title: it influences the font size following the guidelines at 160 * https://hig.kde.org/style/typography.html 161 * It also corresponds to the level api of Kirigami Heading for QML applications 162 * @since 5.53 163 */ 164 int level(); 165 166 public Q_SLOTS: 167 /** 168 * @param text Text displayed on the label. It can either be plain text or rich text. If it 169 * is plain text, the text is displayed as a bold title text. 170 * @param alignment Alignment of the text. Default is left and vertical centered. 171 * @see text() 172 */ 173 void setText(const QString &text, Qt::Alignment alignment = Qt::AlignLeft | Qt::AlignVCenter); 174 /** 175 * @param text Text displayed on the label. It can either be plain text or rich text. If it 176 * is plain text, the text is displayed as a bold title text. 177 * @param type The sort of message it is; will also set the icon accordingly 178 * @see text() 179 */ 180 void setText(const QString &text, MessageType type); 181 182 /** 183 * @param comment Text displayed beneath the main title as a comment. 184 * It can either be plain text or rich text. 185 * @param type The sort of message it is. 186 * @see comment() 187 */ 188 void setComment(const QString &comment, MessageType type = PlainMessage); 189 190 /** 191 * Set the icon to display in the header. 192 * @param icon the icon to display in the header. 193 * @param alignment alignment of the icon (default is right aligned). 194 * @since 5.63 195 */ 196 void setIcon(const QIcon &icon, ImageAlignment alignment = ImageRight); 197 198 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 72) 199 /** 200 * Sets the icon to the @p pixmap and also the icon size to the size of the @p pixmap. 201 * @param pixmap Pixmap displayed in the header. The pixmap is by default right, but 202 * @param alignment can be used to display it also left. 203 * @see pixmap() 204 * @deprecated Since 5.72, use setIcon(const QIcon &, ImageAlignment) 205 */ 206 KWIDGETSADDONS_DEPRECATED_VERSION(5, 72, "Use KTitleWidget::setIcon(const QIcon &, ImageAlignment)") 207 void setPixmap(const QPixmap &pixmap, ImageAlignment alignment = ImageRight); 208 #endif 209 210 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 63) 211 /** 212 * @param icon name of the icon to display in the header. The pixmap is by default right, but 213 * @param alignment can be used to display it also left. 214 * @see pixmap() 215 * @deprecated since 5.63 use setIcon() instead 216 */ 217 KWIDGETSADDONS_DEPRECATED_VERSION(5, 63, "Use KTitleWidget::setIcon(const QIcon &, ImageAlignment)") 218 void setPixmap(const QString &icon, ImageAlignment alignment = ImageRight); 219 #endif 220 221 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 63) 222 /** 223 * @param icon the icon to display in the header. The pixmap is by default right, but 224 * @param alignment can be used to display it also left. 225 * @see pixmap() 226 * @deprecated since 5.63 use setIcon() instead 227 */ 228 KWIDGETSADDONS_DEPRECATED_VERSION(5, 63, "Use KTitleWidget::setIcon(const QIcon &, ImageAlignment)") 229 void setPixmap(const QIcon &icon, ImageAlignment alignment = ImageRight); 230 #endif 231 232 /** 233 * @param type the type of message icon to display in the header 234 * @param alignment alignment of the icon (default is right aligned). 235 * @see icon() 236 * @since 5.72 237 */ 238 void setIcon(MessageType type, ImageAlignment alignment = ImageRight); 239 240 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 72) 241 /** 242 * @param type the type of message icon to display in the header. The pixmap is by default right, but 243 * @param alignment can be used to display it also left. 244 * @see pixmap() 245 * @deprecated Since 5.72 use setIcon(MessageType, ImageAlignment) instead 246 */ 247 KWIDGETSADDONS_DEPRECATED_VERSION(5, 72, "Use KTitleWidget::setIcon(MessageType, ImageAlignment)") 248 void setPixmap(MessageType type, ImageAlignment alignment = ImageRight); 249 #endif 250 251 /** 252 * Set the size of the icon to display in the header. 253 * @param iconSize the size of the icon, or an invalid QSize to reset to the default 254 * 255 * The default size is defined by the GUI style and its value for QStyle::PM_MessageBoxIconSize. 256 * 257 * @since 5.72 258 */ 259 void setIconSize(const QSize &iconSize); 260 261 /** 262 * Set the autohide timeout of the label 263 * Set value to 0 to disable autohide, which is the default. 264 * @param msecs timeout value in milliseconds 265 */ 266 void setAutoHideTimeout(int msecs); 267 268 /** 269 * Sets the level of this title, similar to HTML's h1 h2 h3... 270 * follows KDE HIG https://hig.kde.org/style/typography.html 271 * @param level the level of the title, 1 is the biggest font and most important, descending 272 * @since 5.53 273 */ 274 void setLevel(int level); 275 276 protected: 277 void changeEvent(QEvent *e) override; 278 void showEvent(QShowEvent *event) override; 279 bool eventFilter(QObject *object, QEvent *event) override; 280 281 private: 282 std::unique_ptr<class KTitleWidgetPrivate> const d; 283 284 Q_DISABLE_COPY(KTitleWidget) 285 }; 286 287 #endif 288