File indexing completed on 2024-04-28 03:59:15
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 Q_PROPERTY(int autoHideTimeout READ autoHideTimeout WRITE setAutoHideTimeout) 0065 0066 public: 0067 /** 0068 * Possible title pixmap alignments. 0069 * 0070 * @li ImageLeft: Display the pixmap left 0071 * @li ImageRight: Display the pixmap right (default) 0072 */ 0073 enum ImageAlignment { 0074 ImageLeft, /**< Display the pixmap on the left */ 0075 ImageRight, /**< Display the pixmap on the right */ 0076 }; 0077 Q_ENUM(ImageAlignment) 0078 0079 /** 0080 * Comment message types 0081 */ 0082 enum MessageType { 0083 PlainMessage, /**< Normal comment */ 0084 InfoMessage, /**< Information the user should be alerted to */ 0085 WarningMessage, /**< A warning the user should be alerted to */ 0086 ErrorMessage, /**< An error message */ 0087 }; 0088 0089 /** 0090 * Constructs a title widget. 0091 */ 0092 explicit KTitleWidget(QWidget *parent = nullptr); 0093 0094 ~KTitleWidget() override; 0095 0096 /** 0097 * @param widget Widget displayed on the title widget. 0098 */ 0099 void setWidget(QWidget *widget); 0100 0101 /** 0102 * @return the text displayed in the title 0103 * @see setText() 0104 */ 0105 QString text() const; 0106 0107 /** 0108 * @return the text displayed in the comment below the title, if any 0109 * @see setComment() 0110 */ 0111 QString comment() const; 0112 0113 /** 0114 * @return the icon displayed in the title 0115 * @see setIcon() 0116 * 0117 * @since 5.72 0118 */ 0119 QIcon icon() const; 0120 0121 /** 0122 * @return the size of the icon displayed in the title 0123 * @see setIconSize() 0124 * 0125 * @since 5.72 0126 */ 0127 QSize iconSize() const; 0128 0129 /** 0130 * Sets this label's buddy to buddy. 0131 * When the user presses the shortcut key indicated by the label in this 0132 * title widget, the keyboard focus is transferred to the label's buddy 0133 * widget. 0134 * @param buddy the widget to activate when the shortcut key is activated 0135 */ 0136 void setBuddy(QWidget *buddy); 0137 0138 /** 0139 * Get the current timeout value in milliseconds 0140 * @return timeout value in msecs 0141 */ 0142 int autoHideTimeout() const; 0143 0144 /** 0145 * @return The level of this title: it influences the font size following the guidelines in 0146 * the <a href="https://develop.kde.org/hig/style/typography/">KDE HIG</a>. 0147 * It also corresponds to the level api of Kirigami Heading for QML applications 0148 * @since 5.53 0149 */ 0150 int level(); 0151 0152 public Q_SLOTS: 0153 /** 0154 * @param text Text displayed on the label. It can either be plain text or rich text. If it 0155 * is plain text, the text is displayed as a bold title text. 0156 * @param alignment Alignment of the text. Default is left and vertical centered. 0157 * @see text() 0158 */ 0159 void setText(const QString &text, Qt::Alignment alignment = Qt::AlignLeft | Qt::AlignVCenter); 0160 /** 0161 * @param text Text displayed on the label. It can either be plain text or rich text. If it 0162 * is plain text, the text is displayed as a bold title text. 0163 * @param type The sort of message it is; will also set the icon accordingly 0164 * @see text() 0165 */ 0166 void setText(const QString &text, MessageType type); 0167 0168 /** 0169 * @param comment Text displayed beneath the main title as a comment. 0170 * It can either be plain text or rich text. 0171 * @param type The sort of message it is. 0172 * @see comment() 0173 */ 0174 void setComment(const QString &comment, MessageType type = PlainMessage); 0175 0176 /** 0177 * Set the icon to display in the header. 0178 * @param icon the icon to display in the header. 0179 * @param alignment alignment of the icon (default is right aligned). 0180 * @since 5.63 0181 */ 0182 void setIcon(const QIcon &icon, ImageAlignment alignment = ImageRight); 0183 0184 /** 0185 * @param type the type of message icon to display in the header 0186 * @param alignment alignment of the icon (default is right aligned). 0187 * @see icon() 0188 * @since 5.72 0189 */ 0190 void setIcon(MessageType type, ImageAlignment alignment = ImageRight); 0191 0192 /** 0193 * Set the size of the icon to display in the header. 0194 * @param iconSize the size of the icon, or an invalid QSize to reset to the default 0195 * 0196 * The default size is defined by the GUI style and its value for QStyle::PM_MessageBoxIconSize. 0197 * 0198 * @since 5.72 0199 */ 0200 void setIconSize(const QSize &iconSize); 0201 0202 /** 0203 * Set the autohide timeout of the label 0204 * Set value to 0 to disable autohide, which is the default. 0205 * @param msecs timeout value in milliseconds 0206 */ 0207 void setAutoHideTimeout(int msecs); 0208 0209 /** 0210 * Sets the level of this title, similar to HTML's h1 h2 h3... 0211 * Follows the <a href="https://develop.kde.org/hig/style/typography/">KDE HIG</a>. 0212 * @param level the level of the title, 1 is the biggest font and most important, descending 0213 * @since 5.53 0214 */ 0215 void setLevel(int level); 0216 0217 protected: 0218 void changeEvent(QEvent *e) override; 0219 void showEvent(QShowEvent *event) override; 0220 bool eventFilter(QObject *object, QEvent *event) override; 0221 0222 private: 0223 std::unique_ptr<class KTitleWidgetPrivate> const d; 0224 0225 Q_DISABLE_COPY(KTitleWidget) 0226 }; 0227 0228 #endif