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

source code of kwidgetsaddons/src/ktitlewidget.h